General Interface Definitions

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/

Standard parameter

The following parameters are mandatory for each request:

Account Parameters
request
required
Format LIST
Request types
Preauthorization
Authorization
Capture
Debit
Refund
...
mid
required
Format NUMERIC(5..6)

Merchant ID, defined by PAYONE

aid
required
Your subaccount ID, 5-digit numeric
portalId
required
Format NUMERIC(7)

Portal ID, defined by PAYONE

mode
required
Format LIST
Value Comment
live Transaction should be performed in live mode.
test Transaction should be simulated

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

encoding
optional
Format LIST
Value Comment
ISO-8859-1 Default if not specified
UTF-8

The type of character encoding used in the request.

responsetype
required
Format LIST

- JSON

- REDIRECT

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

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

successurl
optional

Format CHAR(2..255)

Scheme <scheme>://<host>/<path>>

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

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

URL for "payment successful"

errorurl
optional

Format CHAR(2..255)

Scheme <scheme>://<host>/<path>

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

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

URL for "faulty payment"

api_version
required
Format LIST
Api version Comment Description
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
 Our Client API Requests

Calculation of the HASH value

  • Parameters for HASH calculation
  • Example for HASH calculation

Hosted Iframe

to be PCI DSS SAQ_A compliant please use hosted iFrame

Ajax Mode

In AJAX mode, values entered in a form can be checked and processed directly without reloading the web page.

Redirect Mode

The client API forwards the user to a specific page after processing the from input. It itself doesn't have any output.

Administration-Requests