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 tpyes
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
  1. JSON
  2. 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

Request “capture” with response “pending”

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

New parameter api_version should be added to current implementations as it will be mandatory in future.
key
required
Format CHAR(1..32) lowercase
Permitted Symbols [0-9,a-z]

The key is used to check the authentification of the sender (either your system for sending requests or PAYONE platform for sending notifications).

 
Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded