This technical reference includes detailed descriptions and examples for the communication with the PAYONE Platform.

Methods of payment

PAYONE Platform supports the following methods of payment:

Optional modules

PAYONE Platform includes the following optional modules:

The administration of subscriptions (Contract), the creation of invoices (Invoicing) and the dunning processes (Collect) are, depending on the settings, automatically carried out in the background. You can, however, use API to control these procedures.

The communication is based on HTTPS-POST requests (key/value pairs) between the merchant’s systems and PAYONE Platform.

The PAYONE Platform and its connected systems are designed for IP addresses Version 4.

This technical reference may include functions that are not activated for your merchant account due to contractual terms.  If you have any questions or problems please do not hesitate to contact our service team.

Mode "test" / "live"

• Basically all API-requests can be used in mode "test" and "live" in the same way. But please note that the processes may differ slightly different in mode "test" and "live". So in mode "test" a lot of downstreamed processes are simulated by the PAYONE Platform and are not forwarded to other service providers.

• Please also note that you should not use any live data in mode "test". The PAYONE Platform offers a set of test data to simulate several test cases in payment processing. Please find the prepared test data here: Testdata.

• Attention: Requests in mode "live" are always processed and forwarded to service providers – even if test data are used. By this additional cost may come up (e.g. by post delivery of documents or by chargebacks).

• Please note that the intention for mode “test” in the PAYONE Platform is to exercise and to test the behavior of the PAYONE Platform – the intention is not to serve for regression / integration tests.

• Please note that transactions and their data in mode “test” may be deleted after 3 months.

Costs:

Please note that depending on the transaction type used costs may occur in addition to transaction fees. See our List of Prices and Services for details.

Accounts

The PAYONE Platform includes merchant accounts and what is known as sub accounts. For the settlement of your goods you need at least one sub account to which your payments will be allocated.

Each merchant account can include any number of sub accounts. This combination of merchant and sub accounts offers a multitude of flexible options to the merchant.

The merchant can, for example, allocate marketing campaigns to different sub accounts in order to receive exact statistics concerning all transactions, accesses, revenues, subscriptions and purchases generated through the corresponding marketing campaign. The merchant can thus easily measure and analyse the success of his marketing campaigns with just one merchant account.

This combination of merchant and sub accounts can also be used for multilevel marketing platforms (partner programs) or resellers.

Payment portals

In order to carry out payment processes via the PAYONE Platform, you must first create a payment portal. All settings regarding payment processes and debtor management are anchored in the payment portals. All payment processes are conducted via the different payment portals.

The PAYONE Platform has two different versions of payment portals: "Access" and "Shop".

The fundamental difference between the two payment portal versions is the following: In the "Access" version you need to set up orders/contract templates and the PAYONE Platform can handle the access management for you. You can define how long or how often your customers have access to your products and services after a successful payment process. In the same manner, subscriptions are supported by the PAYONE Platform payment portals of the version "Access".

"Access" payment portals are thus specifically useful for accounting digital products or services which will grant your customer access for a specific period of time determined by you or if the PAYONE Platform is to manage a subscription.

In payment portals of the version "Shop" a one-time settlement occurs. In this case it is not necessary to set up offers because the products and services that are to be settled are dynamically submitted to the PAYONE Platform. It is therefore possible to settle retail as well as digital products and services.

Versions:

Debtor accounts

With each initialisation of a payment process the PAYONE Platform sets up a debtor account and opens up a payment process in this account.

Each payment process includes an unique PAYONE payment process ID (txid). An individual balance is kept for each payment process. A payment process usually includes an invoice and, where applicable, several credit memos. All payments or return debit notes are automatically allocated to the corresponding payment process. Once a payment request is settled, the balance is reduced by the corresponding amount. In the case of return debit notes or chargebacks the balance is increased by the amount of the return debit notes.

During each booking the master data/payment data for the customer is saved. Each customer (debtor) is assigned a PAYONE debtor ID (userid) by the PAYONE Platform. If you enter the PAYONE debtor ID assigned by the PAYONE Platform (userid) for follow-up bookings for the same debtor, the booking will automatically be assigned to the same debtor.

The second option is to use your own customer ID (customerid). If you use the same customer ID (customerid) for two different bookings, the bookings will also be allocated to the same internal debtor by the PAYONE Platform.

Advantage:

All payment processes by the same debtor are managed automatically internally. Among other things, this makes it possible to synchronise the booking, dunning and encashment processes by combining several open requests for one debtor within one process. In addition, the payment processes or the master data/ payment data for one debtor can easily be administered.

By storing customer data in the PAYONE Platform it is moreover possible to initiate follow-up bookings for a customer without needing to submit the customer data. It is therefore not necessary for the merchant to store e.g. credit card information.

Attention:

When follow-up bookings for the same customer (debtor) (same userid or customerid) are carried out, the debtor's master data is updated / overwritten with the current values.

Invoicing

The PAYONE Platform can automatically generate invoices and credit memos for you and send these, e.g. as PDF documents, to your customer via email or post.

With the "Access" version the description provided in the offer you have generated is automatically used as the invoice item.

With the "Shop" version you have the possibility to supply the PAYONE Platform with your complete shopping cart including article number, quantity, description, price and VAT. These positions are automatically used as invoice items.

You can create the invoices according to your specifications.

Once the invoice is activated and the invoice/credit memo has been successfully carried out, an invoice/credit memo in your design is automatically created by the PAYONE Platform and sent to the customer as a PDF document via email or post. Afterwards you can download the invoices sent at any time in the PMI (PAYONE Merchant Interface).

For configuration of the PAYONE Platform invoicing module please contact the PAYONE merchant service.

Dunning processes and encashment

At your request the PAYONE Platform will carry out commercial dunning processes as well as the transfer to encashment. Within the dunning process, the customer will receive up to three reminders (e.g. via email, post) with requests for payment. If the dunning process is without success, the case can be transferred to an external encashment agency. All reminders that have been sent can be viewed via PMI (PAYONE Merchant Interface).

If an invoice is not settled by the specified date or in the case of return debit notes and chargebacks (credit card) the case is automatically transferred to the PAYONE Platform's internal dunning.

In the reminders, the customer receives an overview of all outstanding requests and of any additional fees that may have resulted. The email includes all data relevant for payment and the customer is therefore able to settle all outstanding requests by credit transfer straight away. The incoming payments are automatically assigned to the outstanding request by the PAYONE debtor management system. If the dunning procedure is without success, the case is transferred to an encashment agency.

The merchant is supplied with all outstanding requests via the TransactionStatus (see Parameter for the TransactionStatus query). In the same manner the TransactionStatus transmits the settlement of every outstanding request. The customer is optionally provided with a confirmation mail acknowledging the settlement of the outstanding request.

For configuration of the PAYONE Platform Collect module please contact the PAYONE Merchant Service.

Administration of subscriptions

With the help of the Contract module the PAYONE Platform manages subscriptions and recurring payments. Terms, prices and dependencies can be defined freely within the PMI (PAYONE Merchant Interface), which means that complex order models can be displayed as well.

In order for subscriptions to be managed automatically via the PAYONE Platform, you must first provide the key details of the subscription in the PMI (PAYONE Merchant Interface). For this purpose, create a payment portal of the type "Access" and corresponding offers (templates) for the different subscriptions (see Payment portals (Access / Shop)). Here, you can define terms, prices, etc. for the subscription.

To initialise a subscription use the corresponding order ID (template) and a "createaccess" request. If the first booking is successful, a subscription will be created for the customer using the template.

All bookings created by the administration of subscriptions via the TransactionStatus (see Parameter for the TransactionStatus query) are submitted to the merchant. If Invoicing is active, the customer will automatically receive an invoice with each booking.

For configuration of the PAYONE Platform Contract module please contact the PAYONE merchant service.