Skip to end of metadata
Go to start of metadata

Requirements

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

Communication Principles

Communication from your server to our platform is performed by sending key-value-pairs per HTTP Post over a secure channel. 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.

Detailed description of every parameter: Server API Description.

Creating an order

Default parameters

For every request to our platform, a set of default parameters is needed:

mid=12345 (your merchant id)
portalid=12345 (your portal id)
aid=12345 (your account id)
key=a07daf3210b06327612abae3ed477b0f (your secret portal key as md5 hash)
mode=test
encoding=UTF-8

These parameters 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.

Personal Data

Additionally, some information about the customer can be transmitted:

city=Kiel
country=DE
currency=EUR
email=shopper@example.com
lastname=Payer
street=Fraunhoferstr. 2 - 4
zip=24118
birthday=19700101
language=de

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.

clearingtype=rec
reference=1234567890 (your unique reference)
amount=10000
currency=EUR
request=preauthorization

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

Preauthorization

This set of parameters would tell PAYONE to create an order with the above mentioned personal data and the payment method "open invoice".

mid=12345 (your merchant id)
portalid=12345 (your portal id)
aid=12345 (your account id)
key=3adxxxxxxxxxxxxxxxxxxxxxxxx1cb9e (your secret portal key as sha2-384 hash)
mode=test
encoding=UTF-8

city=Kiel
country=DE
currency=EUR
email=shopper@example.com
lastname=Payer
street=Fraunhoferstr. 2 - 4
zip=24118
birthday=19700101
language=de  

clearingtype=rec
reference=1234567890 (your unique reference)
amount=10000
currency=EUR
request=preauthorization 
status=APPROVED
txid=98xxxx21
userid=123456789
Capture

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.

Your First Capture

mid=12345 (your merchant id)
portalid=12345 (your portal id)
aid=12345 (your account id) 
key=3adxxxxxxxxxxxxxxxxxxxxxxxx1cb9e (your secret portal key as sha2-384 hash) mode=test
encoding=UTF-8

reference=1234567890 (your unique reference) 
amount=10000
currency=EUR
request=capture
txid=98xxxx21 (from preauthorization request)
sequencenumber=1

For payment methods that require the customer to send money themselves (like inovice), PAYONE will include clearing data in the response to the capture request. The customer has to know these bank account details to be able to wire the money to that account.

status=APPROVED
txid=98xxxx21
settleaccount=no
clearing_bankaccountholder=PAYONE GmbH
clearing_bankcountry=DE
clearing_bankname=Testbank AG
clearing_bankbic=TESTDEXX210
clearing_bankiban=DE00123456781234567890

Where to go from here

This intro is just the tip of the iceberg. For online bank transfer like Sofort.com, 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 above.

Redirect payment methods


Sometimes, payment methods require information from the customer on 3rd party websites. Usually this is the case if the customer needs to enter transaction credentials, such as username/password or a TAN. Again, a three step process: Preparing the (pre-)authorization, redirecting the customer, and verifying the transaction status.

Credit Card Payments

Online payments with credit cards are de facto mandatory for every online shop. However, the credit card issuers have high requirements concerning the security of credit card transactions. The Payment Card Industry Data Security Standard (PCI DSS) defines the prerequisites and certification steps. As certification is quite complex for merchants, PAYONE developed a solution that only requires the lowest level of PCI DSS compliance. Essentially, processing a credit card transaction is a three step process:

  1. Create the form to capture the credit card details
  2. Send them to PAYONE and receive a token in a callback
  3. Perform (pre-)authorization using the token

The token is a so called pseudo card PAN, a number that resembles a credit card number, so that 3rd party systems can use it, but doesn't entail the PCI DSS requirements for storing card data. To avoid the software on the server to come in contact with credit card data, the Client API is used for communication between the buyer's browser and PAYONE.

Examples

There are some handy examples in the examples folder. You're welcome to add more, if you feel like it!

Try it out

If you want to try out our API with your own account credentials, please install our checkout demo app.


  • No labels