Before You Start
This Quick Start Guide is a step by step instruction for the setup process of the PAYONE Platform. The guide uses examples to demonstrate the set-up and configuration process of the merchant account, the utilisation of the various interfaces as well as the PAYONE Merchant Interface (PMI).
The modular design of the PAYONE Platform allows you to choose the ideal range of services to suit your business model and your particular requirements. The examples used in this Quick Start Guide are based on a particular configuration – simply adapt these settings according to your needs.
Additional supporting documents will help you with this, for example the technical reference documents (API documentations). Should you still need further assistance with any particular item, simply contact the PAYONE Merchant Service who will be happy to help you.
To actively follow the steps described below, one of the following conditions should be met:
You have received your user name and password (in a separate e-mail after the order has been accepted by PAYONE).
This data is used for logging into the PMI, the centralised web-based management interface of the PAYONE Platform.
You have received the credentials for a test account and want to try out the system with no obligation.
Step by Step to Your First Transaction
A merchant account with PAYONE always includes at least one payment portal, one sub-account and at least one type of connection (interface). Together, these components make up the basic system. The functions described here are available in test mode and live operation. The system is identical for both types of operation, the only difference being that in test mode no data is transmitted to external systems. The responses (e.g. by banks) are – as far as this is possible – simulated. We can provide you with test data for several transactions. For more information, please check here Testdata.
If you execute requests in live operation, these will be transmitted externally upon submission – using the test data. If, for example, this operation initiates the dispatching of documents by mail or a chargeback, this will incur real costs. Therefore, always check whether you have selected the right mode before triggering any operation.
Some payment methods require more data than others, so the live mode may not work. This is only activated in the service once all data is available and/or all risk checks have been completed. You can then switch to live mode in the shop.
Setting up Your Merchant Account
Step one on the way to your first transaction is to log in to the PAYONE Merchant Interface (PMI) via the URL https://pmi.pay1.de or via the link on www.bspayone.com (Login -> Merchant Interfaces -> Login)
Please register with your user name and the corresponding password, which you must change after your first login. Your merchant ID, displayed within the PMI in the top right corner, serves as a reference for service requests and should therefore be stated whenever you contact PAYONE.
The link for entering the password is only valid for 720 min. After that, a new link must be generated by the PAYONE Merchant Service.
Passwords follow PCI DSS guidelines (requirement 8.2.3), i.e.: Passwords have to consist of at least 8 characters (numeric, alphabetic), change at least every 90 days, are blocked after 6 false tries, cannot be the same as the four previously used passwords, cannot contain username, have to be changed after first use/reset.
Configuring a Payment Portal
Each payment process must be assigned to a particular payment portal within the PAYONE Platform. In the course of the set-up process, the PAYONE service team has already created at least one payment portal for you, which you must configure now. To do this, go to Configuration and select the item Payment portals. You will be shown an overview of all existing payment portals.
Depending on the selected portal, you must enter various data. The example used here shows the configuration of the portal type Shop (see info box on the right). You can edit the name of the portal that was entered by the PAYONE team.
What is a payment portal?
A payment portal contains the settings for payment transactions and debtor management. The PAYONE Platform will select one of two types of billing depending on the selected payment portal:
- Shop type payment portals invoice by event, such as the purchase in your online shop.
- Login type payment portals invoice based on a predefined time period, for example monthly subscription fees or a video flat rate.
In order to create a Shop type payment portal, all you need to do after naming the portal is to specify the shop URL using the format http://www.yourURL.com . Depending on the options you have booked, you may be required to enter a return address for e-mails that automatically dispatched to your end customers by PAYONE. In addition, the PAYONE Merchant Service will enable the selected interfaces after booking.
For a payment portal of the Login type, at least one offer must be created that has not yet been created.
The number of shops or accesses is determined by PAYONE. Please do not hesitate to contact us.
The first three lines should be filled in for a successful transaction.
You have further configurations for messages from PAYONE platform to your system:
Additional response-data -> recommended: Switched on
You can configure for mode test and live individually whether the API-response contains additional data.
- Switched off: Only „status“, „txid“, and „userid“ will be sent in API-response.
- Switched on: Additional data (like SEPA mandate information) and further information depending on type of payment will be sent.
Transaktions-Status -> recommended: all checkboxes activated
You can specify the type of data sent in the transaction status (same settings for mode test and live).
Notify-Version -> Standard / recommended: Notify Version 7.6
Relevant currently for the following payment methods: Pay Direct (PDT), PayPal (PPE), Amazon Pay (AMZ)
Version 7.6, recommended setting for new integrations: New parameter „transaction_status“ has been introduced with values „completed“ || „pending“ for "txaction=capture". Additionally new parameter „reasoncode“ for „transaction_status=pending“
For more information, see the Server API documentation in the Parameters for the TransactionStatus query chapter.
TransactionStatus Failed -> recommended setting for new integrations: Send
- Send notify: A transaction status message will be sent for failed transactions (from notify version 7.5 up).
- Do not send: A transaction status message for failed transactions will be suppressed.
After that, continue with the configuration in the next tab Advanced. Here, you should enter the transaction status URL, i.e. the address to which PAYONE is supposed to transfer status changes for all payment processes and other payment-related information via HTTP request. It must follow the format http(s)://www.yourURL.com . In addition, this is where you select the key (see info box).
What is the key?
In order to ensure that only you as the legitimate merchant access our platform, you have to determine a key. This personal identification is known only to you and it is transmitted as an MD5 hash value (in lower case letters) each time a PAYONE interface is invoked.
You can choose the key freely, it is recommended to use at least 10 randomly selected characters (lower and upper case letters, special characters, numbers, no diacritic signs, maximum 32 characters) for your key. For example:
Never share this key with any third party!
The key must match the data stored in your shop system!
You can make a number of general provisions in the PMI, which you can overwrite individually with the parameters for the respective API request at a later point in time. As a basic rule: An API request is rated higher than settings made in the PMI. For details please refer to the API documentation. The following advanced settings can be overwritten:
- The Return URL to which a consumer is redirected if a transaction was unsuccessful, for example when he or she decides to cancel the purchase after being forwarded to a payment site such as PayPal.
- The Success URL to which a consumer is directed if the order was passed successfully.
- The purpose that the consumer will see on his or her bank account or credit card statement for direct debit or credit card payments.
recommended: "sha2 or md5"
This setting ensures best compatibility for all types of integrations. However, we strongly recommend switching all your applications to sha2 only to ensure best security.
The last field is used to add front end user interface templates. You can add standard templates for the layout of the user interface, which can be further customised in an advanced dialogue. Thus, the fields seamlessly integrate into the design of your online offer, meaning that the consumer is not aware of PAYONE's interference during the checkout process.
The [Options] tab is already preassigned by us when you create your account and can be edited in part by you.
The tab [API parameters] contains a summary of the absolutely necessary data in the communication to your shop system as well as a list of the sub-accounts created by you (next section: Creating sub-accounts).
For a successful transaction, all fields should be filled out and also match the data stored in the shop system.
The [Riskcheck] tab is only available if you have commissioned the Risk Management product.
Please inform yourself here in detail about the different Riskcheck procedures and make sure that your configuration matches your requirements/desires.
Subaccounts are used for purely analytical purposes and can be created on your own terms. There is no upper limit to the number of sub-accounts, however, you are required to create at least one such subaccount.
Application examples for sub-accounts:
If you operate your online offer in several different countries, sub-accounts provide you with a convenient tool for breaking down your sales by country. It is also easy to analyse your turnover from different lead sources using subaccounts. Further examples would be discount promotions, filtering by article groups or the division into summer and winter months.
By default, there is no subaccount yet.
In order to create a subaccount, go to Configuration >> Accounts. Click Add account and enter a name for your subaccount.
This must be unique payonewide. Should the name already be used for another subaccount, an error message will appear. Click Create account to save your new subaccount.
The Most Important Account Data at a Glance
Do you use PAYONE via an extension such as Magento, OXID or pixi*?
Then you must enter additional data such as the portal ID in your module. These and other required data can be found under:
You will also need these data for connecting the different interfaces.
After this last step, you have completed the basic configuration of your merchant account.
Depending on the interfaces employed, you are now ready to use the PAYONE Platform to process payment transactions in various ways.
Communicating with the Platform via Interfaces
There are substantial differences in terms of the various interfaces' functionalities. For a comprehensive description, please refer to the PAYONE Platform specification of services. The following table provides a brief overview:
|Server API||Client API||Frontend|
|Simplifying PCI DSS certification as a merchant|
|Posting of credit memos|
|Posting of receivables|
|Updating of customer data|
|Control of the dunning process|
Security for credit card details
The Payment Card Industry Data Security Standard (PCI DSS) is a set of rules regulating the handling of credit card data. Every company that processes or stores credit card data must pass certification. The client API and the front end, however, allow you to simplify the cost-intensive certification process as a merchant by redirecting all sensitive data directly to PAYONE for processing. PAYONE itself is certified according to the highest PCI DSS level 1. For more information, please refer to our PCI DSS info sheet. Upon request, we will send you a copy of this document. Alternatively, you can download it directly from our website.
Invoking the Platform Using the Example of the Client/Server API
Each payment process can be mapped as a series of individual process steps – in so-called sequence diagrams.
The following two examples show common business transactions in an online offer from the purchase to the delivery of the goods. The commands used and the sequence may vary depending on the selected connectivity option.
You will find details on the interface you use in the technical reference documents (API documentation).
A variety of solutions:
The PAYONE Platform supports a variety of payment methods and options to adapt to your particular business model. Find out more about the offered solutions in the PAYONE Platform services specification or contact our sales team with any questions.
Sequence Diagram of a Credit Card Payment with Pre-Authorisation
As an example, we will elaborate on the procedure of a credit card payment with reservation and collection.
This commonly-used sequence is recommended if you wish to make sure that the payment amount will be available and can be debited from the consumer's account after checking the availability of the product. A preceding reservation of the payment amount is also a precondition for many acquiring partners.
After placing the order, the consumer's credit card details are transmitted via an AJAX call to the client API, for example. The request employed for this is creditcardcheck. This checks the respective credit card for plausibility in real time. In addition, this request allows you store credit card data (cardpan, expiration date) with PAYONE. In this case, the response returns a so-called pseudo card number (pseudocardpan), which can be stored by the merchant and later re-assigned to the real credit card by PAYONE. This means that the merchant does not have to be certified according to PCI DSS (see above).
The next step is the request preauthorization which triggers the reservation of the amount of the order at the acquirer, i.e. your credit card acceptance partner. This process will reduce the consumer's credit card limit accordingly. Other parameters that can be transmitted with this request include the consumer's customer number or the delivery address. You can freely adapt the layout of the requests according to your individual needs. A successful transmission is confirmed by changing the status to approved.
The next sequence is the transmission of PAYONE's so-called TransactionStatus in form of a message reading appointed. This confirms the successful initiation of the payment process. The payment is now reserved and the consumer's payment process completed.
Once the ordered goods are available and the shipment to the consumer has been initiated, you can use the request capture to debit the previously reserved amount from the consumer's credit card as the next step.
Sequence Diagram of an Online Bank Transfer
Also when using an online bank transfer the placement of the consumer's order is followed by the request preauthorization. In addition to any required address data, the system can transmit other information such as the consumer's account number and bank code, which also need to be entered in your checkout. This way, the consumer's account details can be checked at the same time as the online bank transfer session is initiated. Furthermore, the account details are stored for any refunds due to returns.
After the response redirect the consumer is redirected to his or her bank. There, the consumer uses his or her account data to log in via the usual user interface and confirms the payment.
The consumer's bank subsequently notifies PAYONE about the successful payment and the consumer's account is debited immediately (as opposed to the preliminary authorisation for credit card payments). PAYONE then transmits the TransactionStatus appointed which confirms the successful payment. The consumer is finally redirected to the success URL of your website.
Here again, the response approved confirms the successful transmission of the request and is formally closed with the transmission of the TransactionStatus capture. The payment is made directly to the bank account that you have specified during the PAYONE activation process.
Transaction Logs: Troubleshooting
Your transaction was not completed successfully? An open transaction status can have a number of reasons. You will get a first hint in the PAYONE Merchant Interface (PMI). Go to the Debtor administration and search for the transaction using the PAYONE payment process ID (TX-ID). Once you have found the dataset, click on Details for more information on the payment process: Here, you will find the field Cause of fault. If the information given here is insufficient for understanding the cause, go to [Configuration] >> [Transaction status] to view all currently blocked transactions and access additional details about the cause of the fault, provided the fault is not older than 48 hours and has not exceeded the maximum number of 12 attempts.
- No labels