The Saferpay JSON API (JavaScript Object Notation Application Programming Interface), hereinafter also referred to as JA, is a modern streamlined interface that is independent of programming languages. The JA supports all Saferpay methods and is suitable for all shop systems, call centre solutions, merchandise management, ERP and CRM systems and other applications in which online payments are processed. This Integration Guide focuses on the basics of the Saferpay JSON API and serves as a guide for programmers, developers and integrators.
This Guide uses the Saferpay JSON-API Specification as a base reference and will frequently link to the respective Requests. All requests and parameters will be specified there.
Use of the JA requires the following:
- A corresponding licence for the Saferpay module.
- The existence of a valid identification with a username and password for the Saferpay Backoffice.
- Availability of at least one active Saferpay terminal via which payment can be carried out and the associated
- Availability of Saferpay terminal number (TerminalId parameter) and Saferpay customer number (CustomerId parameter).
- Availability of valid acceptance agreement for credit cards or other payment methods.
The credit card organisations have launched the safety program PCI DSS (Payment Card Industry Data Security Standard) to prevent misuse and fraudulent use of credit cards.
Please pay attention to the PCI DSS guidelines when setting up payment processes and deploying Saferpay.
When using the Saferpay Hosted Register Form together with the optional Saferpay Secure Card Data (SCD), you can set up and handle the payment process safely. No credit card numbers are processed, transferred or stored on your (web) servers.
To use the Saferpay Payment Page, card holders enter their credit card number and expiry date not within the merchant’s e-commerce application, but rather within the Saferpay Payment Page. As the e-commerce application and Saferpay operate on physically separate platforms, there is no risk that the credit card information could be stored in the database of the merchant’s system.
The risk of misuse of credit card details is significantly reduced via the use of Saferpay Secure Card Data or the Saferpay Payment Page and the expenditure required for PCI DSS merchant certification is reduced significantly.
If you have questions about PCI DSS, your processor or a specialised company will provide answers. More information can be found on the PCI Security Standards Council website.
3-D Secure – 3DS for short – is supported by Visa (Verified by Visa), MasterCard (MasterCard SecureCode), American Express (SafeKey), Diners Club (ProtectBuy) and others. Via liability shift, merchants that offer the 3-D Secure process benefit from fewer payment defaults and from increased security with respect to credit card acceptance. It does not matter whether the card holder (CH) participates in this process or not.
The 3-D Secure procedure can only be used for payments on the Internet. If participating in the process, CHs must identify themselves to their card-issuing banks (issuer) while making payments. Payments that merchants conclude via 3-D Secure are to be specially flagged. Only when the corresponding criteria have been sent with the authorization to the credit card company does the liability shift apply. This step is done automatically via the Transaction Interface and the Payment Page, meaning that no additional integration costs arise. The authentication of the CH proceeds via a web form provided by the issuer or by the service provider contracted by the issuer. The 3-D Secure authentication of the CH is done via an Internet browser.
A transaction with the 3-D Secure process proceeds as follows:
- The merchant sends the credit card details together with the relevant payment data to Saferpay.
- Saferpay checks whether the CH uses the 3DS process or not. If yes, she or he will be required to authenticate her or himself to her or his bank. If not, the payment can be carried out without authentication.
- The 3DS request will be forwarded to the card-issuing bank via the CH’s Internet browser. The CH must provide proof of identity by using a password, mTAN or another method.
- The result of this authentication is sent back to Saferpay via the CO’s Internet browser.
- Saferpay checks the result and ensures that no manipulation has occurred. The payment can be continued if the authentication concludes successfully.
- Saferpay links the 3DS data to the token used by the JSON API and asks for this automatically when authorizing the card.
- When receiving the authorization answer, the merchant also receives information about the output of the 3-D Secure process.
Dynamic Currency Conversion (DCC) is a dynamic currency converter that allows international customers to pay the purchase price in the local currency or their home currency. DCC is available for SIX acceptance contracts with DCC expansion. For this, the terminal used for making the payment request receives a base currency in which all transactions are settled. Via DCC, international customers are shown the purchase price in the base currency and the current exchange rate in their national currency. The customer can then decide the currency in which the payment is to be made. Separate implementation by the merchant is not necessary for DCC. Saferpay automatically handles this step during the redirect.
| Payment method | Transaction Interface | Payment Page |
|---|---|---|
| Visa | ||
| V PAY | ||
| MasterCard | ||
| Maestro International | ||
| American Express | ||
| Bancontact | ||
| Diners Club | ||
| JCB | ||
| Bonus Card | ||
| Postfinance E-Finance | ||
| PostFinance Card | ||
| MyOne | ||
| SEPA Direct Debit | ||
| PayPal | ||
| ePrzelewy | ||
| eps | ||
| giropay | ||
| iDEAL | ||
| BillPay Purchase on Receipt | ||
| BillPay Direct Debit | ||
| SOFORT | ||
| paydirekt |
For use in e-commerce, Saferpay distinguishes between two licences:
- Saferpay eCommerce
- Saferpay Business
It is extremely important to clarify before the implementation of Saferpay whether an eCommerce licence or a business license is to be used, as they provide different functions. The Saferpay Business licence is an extension of the eCommerce licence. If you have any queries, please contact your relevant contractually appointed person.
The following table shows an overview of which functions are included in the two licence models:
| Interface | eCommerce | Business |
|---|---|---|
| PaymentPage Interface | ||
| Initialize Payment Page | ||
| Assert Payment Page | ||
| Transaction Interface | ||
| Transaction Initialize | ||
| Transaction Authorize | ||
| Transaction QueryPaymentMeans | ||
| Transaction AdjustAmount | ||
| Transaction Authorize Direct | ||
| Transaction Authorize Referenced | ||
| Transaction Capture | ||
| Transaction Cancel | ||
| Transaction Refund | ||
| Transaction Refund Direct | ||
| Transaction Redirect Payment | ||
| Transaction Assert Redirect Payment | ||
| Secure Alias Store | ||
| Alias Insert | ||
| Alias Assert Insert | ||
| Alias Insert Direct | ||
| Alias Delete | ||
| Batch | ||
| Close |
Saferpay supports a variety of payment methods, including 3rd party providers such as PayPal. These 3rd party providers are not obligated to support all Saferpay functions. The following table provides an overview of the features supported by the individual payment methods:
| Means of payment | Capture | Batch | SCD | Refund | Recurring | DCC | 3DS | MOTO |
|---|---|---|---|---|---|---|---|---|
| American Express | ||||||||
| Bancontact | ||||||||
| BillPay Direct Debit | ||||||||
| BillPay Purchase on Receipt | ||||||||
| Bonus Card | ||||||||
| Diners Club | ||||||||
| Discover | ||||||||
| ePrzelewy | ||||||||
| eps | ||||||||
| giropay | ||||||||
| iDEAL | ||||||||
| JCB | ||||||||
| Maestro Int. | ||||||||
| Mastercard | ||||||||
| MyOne | ||||||||
| paydirekt | ||||||||
| PayPal | ||||||||
| PostFinance Card | ||||||||
| PostFinance eFinance | ||||||||
| SEPA Direct Debit | ||||||||
| SOFORT | ||||||||
| VISA | ||||||||
| VPay |
- Capture
- Capture required
- Batch
- Daily closing required
- SCD
- Secure Alias Store available
- Refund
- Credits payments can be made
- Recurring
- Recurring payments
- DCC
- DCC available
- 3-D Secure
- 3-D Secure available
- MOTO
- Mail Phone Order available
These two features are extremely important Saferpay features. Depending on the means of payment, the two can be directly associated with each other and they must be carried out for the cash flow to be initiated to the merchant’s account.
Capture serves to book and thus to conclude a payment. As long as a transaction has not passed through the capture, the amount is merely reserved (“authorized”) and has not yet been paid. On the API side, you receive information about the transaction via the “Status” parameter (note that this is only a part of the data):
"Transaction": {
"Type": "PURCHASE",
"Status": "AUTHORIZED",
"Id": "MUOGAWA9pKr6rAv5dUKIbAjrCGYA",
"Date": "2015-09-18T09:19:27.078Z",
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"AcquirerName": "AcquirerName",
"AcquirerReference": "Reference"
}Transactions which have not yet been booked are visible in Saferpay Backoffice as “Reservation.” If a transaction has already passed through the capture, the status is changed to “CAPTURED”:
"Transaction": {
"Type": "PURCHASE",
"Status": "CAPTURED",
"Id": "MUOGAWA9pKr6rAv5dUKIbAjrCGYA",
"Date": "2015-09-18T09:19:27.078Z",
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"AcquirerName": "AcquirerName",
"AcquirerReference": "Reference"
}Not all payment methods need a separate capture to trigger the cash flow. You can find an overview of which payment methods should be booked under Payment Method Features.
IMPORTANT: A reservation made through a certain payment processor, may only last for a limited time only. If this timeframe is exceeded, the authorized amount is released and becomes available to the card holder again. This may have the result that the amount can no longer be claimed. If possible, we recommend always triggering the Capture immediately after authorization. Either by direct API call, or manually via Saferpay Backoffice. If this is not possible, the Capture nonetheless must be done as soon as possible. With PayPal, this must happen within 48 hours. Otherwise, it may be that the Capture -and thus the money-transfer- will be refused. For other payment methods, a later Capture is sometimes possible. If necessary, please speak to your processor about guaranteed reservation times.
The daily closing follows the capture once daily, automatically at 22h CEST. During this process, all transactions that have passed through the capture are filed with the payment method processor in order to initiate the cash flow.
If desired, this step can also be triggered via the Saferpay API. The request necessary for this is called Batch Close.
However, before you can use the API, you need to disable the daily closing in the Saferpay Backoffice via "Administration -> Terminals" for the respective terminal. Closing should be carried out only once a day.
With these payment methods, daily closing is triggered alongside the capture automatically for each transaction and the cash flow is initiated immediately. With PayPal, this happens because the right is reserved to refuse the payment. For this reason, we demand the money for you immediately. For Swiss Postcard, this is established in the protocol used by PostFinance. Same goes for SEPA ELV ,Bancontact and PayDirekt.
giropay, iDEAL, SOFORT, Bancontact, eprzelewy und eps are online payment methods that trigger a transfer and thus the cash flow via the purchaser’s online banking services. A successful transaction is always 100% complete.
It’s by no means rare that customers want to cancel their orders or return goods. As a merchant, you will in such a situation either want to cancel or make a refund for the transaction in question. It should be noted that there are payment methods that do not offer this functionality. An overview can be found in the Payment Method Features chapter.
If this isn’t permitted by the payment method, payments that have not been submitted via daily closing may be canceled. If the daily closing has already been triggered, a refund will have to be issued.
IMPORTANT NOTE: Online banking payment methods do not support these two functionality by default.