General

Data transfer

The data transfer is processed directly via an HTTPS-POST or HTTPS-GET request by the browser of the customer.

The data is returned in JSON data format or as parameter in an HTTP redirect.

Endpoint URL

The requests must be sent to the following URL:

Client API URL:  https://secure.pay1.de/client-api/

How to Read Our Parameter Tables

Parameters and their possible values are presented as tables. Here's how to read them:

ParameterRequiredShort Explanation
the parameter name as you need to send it

+ - always required

- - always optional

o - conditionally required (see explanation for conditions)

a short explanation of what the parameter does plus format definitions

Formats can be


Format

CHAR(1..255)
Permitted Symbols
[a-z][0-9],.-

any string with a length of one to 255 characters and conditionally allowed characters as regex


Format

NUMERIC(1..10)

Only numbers allowed


Format

LIST

choose from a list of permitted values

Standard parameter

With each request the following parameters must always be submitted.

Standard parameter

Parameter

Required

Format

Comment

mid

+

N..6

Merchant ID, defined by PAYONE

Format

NUMERIC(5..6)

portalid

+

N..7

Portal ID, defined by PAYONE

Format

NUMERIC(7)

api_version

+

Default

New parameter api_version should be added to current implementations as it will be mandatory in future.

Format

LIST
api_versionCommentDescription

3.8

Current API-version
(Default if not present)


3.9

New API-version
from 2015-01-05

New response “pending” added for “preauthorization” / “authorization”

3.10

New API-version
from 2016-06-01

Response for “customermessage” can be more specific in case of error by containing detailed error messages from external payment gateways (e.g. Ratepay, …)

3.11

New API-version
from 2018-02-01

Request “capture” with response “pending”

  • Announcement for upcoming request “refund” / response “pending”
  • Announcement for upcoming request “createaccess” / response “pending”

mode

+

Default

Mode for transactions, either ‘live’ or ‘test’

Format

LIST

valueComment

live

Transaction should be performed in live mode.

test

Transaction should be simulated

request

+

Default

Queries:

- creditcardcheck

- bankaccountcheck

…

The type of request you would like to perform

Format

LIST

Link to Request-Overview: Request Overview

responsetype

+

Default

- JSON

- REDIRECT

hash

+

AN..32
AN..96

MD5 hash code (see CA - Calculation of the HASH value)
SHA2-384 hash code (see CA - Calculation of the HASH value)

The hash code is used to prevent that a customer changes any relevant value (like payment type, your MID or the amount).

MD5 hash code SHA2-384 hash code. Details: FE - Calculation of the HASH value

Format

CHAR(1..96) lowercase
Permitted Symbols
[0-9,a-z]

successurl

o

AN..255

URL "payment successful"

(only if responsetype=REDIRECT or required by corresponding request)

URL for "payment successful"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

errorurl

o

AN..255

URL "faulty payment"

(only if responsetype=REDIRECT or required by corresponding request)

URL for "faulty payment"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

encoding

-

Default

The type of character encoding used in the request.

Format

LIST

valueComment

ISO-8859-1

Default if not specified

UTF-8




  • No labels