This document aims to help you in understanding the basics of our API. The code in our examples works, though should only be used as an example to make yourself familiar. We've provided the basic framework and some examples in our GitHub repository.
The code is not checked for security vulnerabilities and should not be used in a production environment without prior assessment.
- Please use an up-to-date version of PHP (https://secure.php.net/)
- Composer (https://getcomposer.org/download/)
- A PAYONE account or test account (don't have one yet? Contact us!)
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. See
Payone.php for Details.
For a detailed description of every parameter please refer to the Server API Description.
Creating a Payment
For every request to our platform, a set of default parameters is needed:
These parameters identify you as a merchant and ensure that only authorized API requests are processed by our platform. You can find these parameters in your merchant backend. See here for more info.
Additionally, some information about the customer can be transmitted, for instance received from your shop application or ERP system:
For details about the individual parameters and more parameters that are available but not listed here, please refer to the Server API Description.
Initiating a payment request
In this example, processing payment is a three step process. In the first step, the order is created (preauthorization). When we're ready to ship the goods, the receivable is booked (capture). In the third step we'll check if the funds have arrived.
Merging the arrays
Together with the recently gathered default parameters and personal data, the request can easily be merged and sent to the platform using the simple functions from the
You'll receive a status response informing you whether the request was successful and if not, about the cause of the error. However, if your API credentials were correct, you'll have received a
status=APPROVED response. In any successful response you'll always receive a transaction ID parameter txid. This parameter is vital for any further communication about that transaction.
Your First Preauthorization
This set of parameters would tell PAYONE to create an order with the aforementioned personal data and the payment method "open invoice".
Parameters in in alphabetical order
Booking the amount, capturing the funds
Once the shipment is ready, the funds 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):
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
Parameters in in alphabetical order
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.
Waiting for payment confirmation
Depending on the payment method chosen, the confirmation of the customer's payment can be instant or take up to several days. Once we have new information about the transaction, we'll send a transaction status query to the URL configured in the PAYONE Merchant Interface. This status notification should be processed by your application in a separate controller, which should only be accessible from our platform (i.e. only from our IPv4 subnet). To prevent any tampering with the notification and minimize the danger of man-in-the-middle attacks, we highly recommend making this controller available through a secure connection only. Our platform expects a
TSOK string as a confirmation that the notification has been received, if the
TSOK hasn't been sent within 10 seconds, our platform will abandon the notification and try again at a later time.
N.B. our platform does not follow HTTP 30x or any other form of redirects.
Since this is a simplified example, we left out the first transactionstatus message (txaction=appointed). For more info on transactionstatus messages, see here: Getting Started with TransactionStatus Notifications
Where to go from here
This intro is just the tip of the iceberg. For online bank transfer like Sofort.com, for instance, 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. Once you have acquainted yourself with the basic transaction principles outlined in the 1 Getting started tutorial, you're ready to tackle these payment methods. This is, again, a three step process: Preparing the (pre-)authorization, redirecting the customer, and verifying the transaction status.
Preparing the authorization
For the authorization, we'll rely on the
Payone::sendRequest() function as before. So first, we need the
However, a couple of new parameters need to be introduced:
As a change, we'll be using
"request" => "authorization" here, which means that not only the account receivable is created but also instantly booked. This is possible because Sofort.com provides instant notification about a successful payment and it saves you the hassle of implementing a separate
"request" => "capture". For rather asynchronous payment methods like prepayment or invoice this is not possible. Refer to the Server API Description for details. However, you are free to use a preauthorization/capture setup here as well if you see fit, for instance for bookkeeping reasons. The URL parameters determine to which page the customer gets redirected as soon as they a) complete the transaction (successurl), b) the transaction fails (errorurl) and the customer is advised to choose a different payment method or try again, or c) the customer hits "Back to shop" or any similar button on the 3rd party site to get back to the payment method selector (backurl). These controllers need to be implemented by you.
On authorization and preauthorization
The main difference between authorization and preauthorization is, that with authorization the funds are due instantly, while with preauthorization it is merely an "arrangement to pay". Funds in the preauthorization mode are due when a capture call is sent. With certain payment methods, the preauthorized funds are reserved (e.g. on a credit card), this is, however, not always the case. The time of the capture has implications on e.g. the dunning process as well.
To make a better example:
Imagine a standard fashion retailer. They would normally use a preauthorization workflow. The amount of the order is preauthorized when the customer finishes their checkout. When the goods are shipped (maybe partially, as not all items might be in stock), a capture API call is sent to indicate the funds are due now. There can be more than one capture call for a single preauthorization.
On the other hand, a merchant of digital content (e.g. e-books) would typically use an authorization flow to be able to make the goods available immediately.
In a typical integration, the merchant would be able to configure in their backend, which mode to use in which setting for which payment method.
Sending the authorization and redirecting the customer
Once you have prepared all the parameters needed for that transaction you're ready to authorize the transaction and then redirect the customer. We'll merge the arrays into one request, send the request to PAYONE, and see whether we get a status=REDIRECT response:
After the customer completed the transaction on the 3rd party site, they'll be redirected to the
successurl so be sure to inform them about the success of their order. However, the order is not quite finished yet.
Making sure everything is present and accounted for
However, to prevent people with fraudulent intentions from directly calling the
successurl, you can't rely on it alone. Additionally, PAYONE will sent a transaction status notification to the shop to indicate that the payment transaction has been completed. When verifying the transaction status take care to validate the key and probably the source IPv4 subnet as well. However, you won't receive a
txaction=paid notification right away but rather a
txaction=appointed to indicate that the transaction has been triggered and will be marked paid in a couple of minutes:
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:
- Create the form to capture the credit card details
- Send them to PAYONE and receive a token in a callback
- 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.
Build the form
PAYONE's "Hosted iFrame" solution gives the merchant the most flexibility in designing the checkout form while at the same time being PCI DSS compliant. The actual
<input> elements are loaded from a secure PAYONE system so that the shop software itself isn't in the scope of PCI DSS certification. First, we need a sceleton of the form:
Never calculate the hash in JS!
After the check has gone through, the pseudo card PAN and truncated card PAN (e.g. 4111xxxxxxxx1111) will be stored in the hidden input fields and submitted to your application through http post.
(Pre-)authorizing credit card transactions
After you have obtained the pseudo card PAN through the Client API channel, the rest of the transaction can be continued through the Server API channel following the scheme above:
If the card requires 3D Secure verification, our platform will respond with a
status=redirect response and give the URL the 3D Secure verification has to be carried out. After the customer successfully completed the 3D Secure form, we will send a transaction status notification
appointed and then redirect them to the URL stated in the
successurl parameter. The transaction status notification coming in before the redirect to the
successurl asserts that the customer has indeed completed their 3D Secure form.
After the preauthorization is completed, you can continue with the transaction e.g. by capturing the full or a partial amount.
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 the examples provided here with your own account credentials, please install the required libraries through composer first:
git clone https://github.com/PAYONE-GmbH/simple-php-integration cd simple-php-integration/ composer install
Then, adapt the individual files in
examples/ to your needs.
- No labels