Communication from your server to our platform is performed by sending key-value-pairs via secure channel per HTTP Post request. In return, your application will receive a response string containing the result of your request. For sending the request to us, we recommend using a cURL wrapper that sends an array as key-value-pairs. The response are key value pairs delimited by EOL breaks, which can easily be parsed into an array.


An active PAYONE - Account is required. If you do not have one yet, please contact us.

Communication Principles

Getting Started

Data transfer

In order to send data to Payone, the content type must be set to "application/x-www-form-urlencoded".

The data transfer is based on HTTPS-POST request (key/value pairs).

API Endpoint

The requests must be sent to the following URL:

POST: /post-gateway/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Our sample request throughout the docs favor readability over technical accuracy, so we'll show the sample requests as multiple lines, even though the content is technically x-www-form-urlencoded.
Receiving Data from PAYONE

The return of the data is based on a line-by-line basis. The name of the parameter is separated from the parameter value with an equal sign ("=").

POST: /post-gateway/ HTTP/1.1
User-Agent: "xxx x.x"
Content-Type: application/x-www-form-urlencoded charset=UTF-8
encoding=UTF-8& parameter1=value1& parameter2=value2& ...

How to Read Our Parameter Tables

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

The parameter name as you need to send it
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 or Default parameter

The following parameters are mandatory for each request. They identify you as a merchant and ensure that only authorized API requests are processed by our platform. You can find the parameters in our PMI:


Merchant ID, defined by PAYONE

Format: NUMERIC(5..6)

Portal ID, defined by PAYONE

Format: NUMERIC(7)

Payment portal key as MD5 or as SHA2-384 value. The key is used to check the authentification of the sender (either your system for sending requests or PAYONE platform for sending notifications).


SHA2-384 (Recommended) : CHAR(1..96) lowercase

Permitted Symbols: [0-9,a-z]

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

Format: LIST
api version Comment Description


Current API-version
(Default if not present)


New API-version
from 2015-01-05

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


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, …)


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 for transactions, either ‘live’ or ‘test’

Format: LIST


Transaction should be performed in live mode.


Transaction should be simulated.


MThe type of request you would like to perform

Format: LIST
Link: Request overview page

The type of character encoding used in the request.

Format: LIST


Default if not specified


current standart, but not default

Personal parameter

Additionally, some information about the customer can be transmitted. For details about the individual parameters and more parameters that are available but not listed here, please refer to the Server API Description.:

Order Details

We need also information about the order and the choosen payment method.

    reference=1234567890 (your unique reference)

For details about the individual parameters and more parameters that are available but not listed here, please refer to the Server API Description.:

Where to go from here

This intro is just the tip of the iceberg. For online bank transfer like, you'll need to redirect the customer to an URL specified in the response. For credit card processing, you'll need to setup a HTML container for input fields made available through our invisible iFrame integration and make sure your system never comes in contact with genuine credit card data. PAYONE will provide you with a pseudo card number that you can use to preauthorize and capture transactions just like in the examples below:


This set of parameters would tell PAYONE to create an order with the above mentioned personal data. For detailed information Server API - Preauthorization


Once the shipment is ready, the order can be captured. Capturing indicates that the order should be finalized in terms of bookkeeping and, if applicable, that the money can be transferred (i.e. for credit card payments or direct debit, see below):

The sequencenumber parameter ensures that all transaction status notifications have been processed before new requests can be sent to our API. It is incremented with each pair of request and transaction status notification. For the preauthorization request it is always implied as 0 and must not be sent. For detailed information Server API - Capture