Introduction

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 are specified there.

The sequential steps of the general integration process are described in our Step-by-step Integration-Manual.

Requirements

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.

Data Security and PCI DSS

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 instead 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 should be able to assist you. More information can also be found on the PCI Security Standards Council website.

Additional tips and hints in regards to PCI-compliancy

The following tips, tricks and also "don't"s should help to build a fully PCI-compliant shop-plattform, with relatively little effort.

Certification Levels

The PCI-DSS certification is devided into multiple compliance levels, called SAQ (Self Assigned Questionary). Each SAQ has its own set of questions and requirements to meet in order to be certified. Every party involved with the processing of credit card information has to be PCI-compliant. That includes you -the merchant-, your Payment Service Processor -in this case Saferpay- your Acquirer -for example SIX Payment Services- and the card holders bank -also called Issuer-. Each certification is valid for a year at most and has then to be renewed.

The two PCI levels most relevant for the majority of merchants integrating Saferpay into their webhsop are; SAQ-A and SAQ-A EP.

Attention: Saferpay is capable of covering multiple levels of PCI-compliance besides SAQ-A and EP. Please contact your acquirer/processor or a specialized company, should you have any questions regarding PCI compliancy. You can also find more information as well as sample SAQ-questionnaires on the official PCI DSS website to get a better understanding and overview about the requirements you have to meet as a merchant, or ask your Acquirer/Credit Card Processor (e.g. SIX Payment Services) for help!

  1. SAQ-A
    This level of certification is the easiest to maintain for a merchant. It mostly involves using a solution, that is maintained by a fully PCI-certified processor. The merchant only specifies his PSP to be compliant, which then holds the risk and responsibility of being compliant. Saferpay is fully PCI SAQ-A compliant and offers solutions for the merchant to be SAQ-A compliant, however the merchant has to follow the following rules, in order to apply this to his plattform:
    The merchant must not use his own (HTML-)form to capture credit card data! This is now forbidden for SAQ-A merchants, defined by the PCI DSS standard version 3, released on January 1st 2015! The merchant can use the Saferpay Payment Page, the Saferpay Fields, for a seamless integration, or the Hosted Forms inside an iFrame, provided by the Transaction Interface and the Secure Alias Store.
    Every Element on the Payment Page and/or inside the iFrame, must be hosted by a PCI-certified processor! The merchant is NOT allowed to add or change any elements by hosting external CSS, or by breaking into the iFrame, using JavaScript. Both the Payment Page as well as the Hosted Forms offer the necessary solutions to meet these PCI requirements. Please refer to chapter Using CSS on how to use the CSS-styling-feature, while being SAQ-A compliant.

  2. SAQ-A EP
    If the SAQ-A level does not suite your requirements or demands, you can certify for SAQ-A EP. This level is more advanced as it enables you to use your own (HTML-)form, however it also requires more effort to be certified. The certification process involves matters like intruder and virus scans and certain firewall configurations.

  3. SAQ-C (VT)
    This is a special certification for merchants, who want to do Mail Phone Order Transactions and card registrations through their own systems. While the JSON-API can be used to capture cards by a merchant employee through the phone, on the merchant system, further tasks and requirements have to be met by the merchant and his system, in order to be allowed to do this. Even the usage of the Saferpay Hosted Form is not enough in this case, because the card details are captured by the merchants employee. Due to that, a higher certification-level is required!

Note: The Saferpay Backoffice itself offers tools to capture card details in a PCI-compliant manner, for Mail Phone Order Transactions, or just register them inside the Secure Alias Store! However the Backoffice does not offer an interface, to be integrated into a merchant-system. If that is required, a SAQ-C certification is inevitable!

Processes, that are NOT allowed

Even with an SAQ-A EP certification, some processes are still not allowed. The following describes such processes, that the merchant MUST NOT DO UNDER ANY CIRCUMSTANCES!

  1. Credit Card Information: It is not allowed to process credit card data through the merchants server. This includes, among others posting credit card data from an HTML-form to the merchant-server to perform a Saferpay request. It is especially forbidden to save credit card data. It doesn't just involve saving! It is enough, if the card details run through your system and be it for just a second! All credit card information involving the Card Verification Code (CVC/CVV) and the card number (PAN), must be processed through Saferpay, if you aren't explicitly allowed to do otherwise! Saferpay does offer the option, to post the collected data directly, however this can only be used by merchants that are fully PCI-certified and allowed to process/save credit card data accordingly.

Warning: DO NOT use real credit card details, when testing on the Saferpay test-environment! Even though the test accounts cannot process real payment means, it is also important to not share them in the first place on the test-system, for security reasons!

3-D Secure

New: Introducing 3-D Secure 2 for Visa and Mastercard. Less hassle for customers, a higher conversion rate for you! Already have a Saferpay Integration with the JSON-API and 3-D Secure? Great! Saferpay will rollout 3DSv2 automatically for you starting in May 2019, with no changes needed!

3-D Secure – 3DS for short – is supported by Visa (Visa Secure), Mastercard (Mastercard ID check), 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 authorisation 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:

  1. The merchant sends the credit card details together with the relevant payment data to Saferpay.
  2. 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.
  3. The 3DS request will be forwarded to the card-issuing bank via the CH’s Internet browser.
  4. The Issuing bank, or its 3DS provider will then perform a so called scoring. This scoring will determine the fraud risk, which will lead to one of two outcomes:
  5. Frictionless: The fraud risk is low and 3-D Secure will proceed without user interaction. The bank will be the liable entity. This also applies to all orders smaller, or equal to 30 Euro, or equivalent, though with a maximum of 5 concurrent transactions (Globally, not merchant/shop-based!).
  6. Challanged: The fraud risk is high, or the issuer wants to force 3D Secure (E.g. after 5 concurrent transactions, as described aboe!), thus the card holder needs to authenticate him/herself, by using a password and mTAN, an App, or even the fingerprint-sensor on his phone. If 3-D Secure was successfull, the bank will still be the liable entity.
  7. The result of this authentication is sent back to Saferpay.
  8. Saferpay checks the result and ensures that no manipulation has occurred.
  9. Saferpay links the 3DS data to the token used by the JSON API and uses this data automatically when authorising the card.
  10. When receiving the authorisation answer, the merchant also receives information about the output of the 3-D Secure process.

What is LiabilityShift and why is it important for me as a merchant?

The best way to understand what LiabilityShift means, is by a small example:

Let's say a merchant is offering certain goods and gets an order for 1000,-. The merchant finalizes the order and the money gets charged from the card holders bank account. After he recieved his money, the merchant ships the goods to the given destination.

After three weeks the merchant gets the information, that this transaction is a fraud-case and that the actual card holder initiated a chargeback. Here is what happens, either with, or without 3-D Secure/LiabilityShift:

  1. Without 3-D Secure/Liabilityshift: The Money gets transfered back, from the merchants bank account, to the original card holder. The merchant, in this case, is liable for the damage that has been caused and even though the goods already have been shipped (probably to a criminal subject), he has to pay the full amount back to the card holder. So he carries the whole risk and the cost in a fraud-case!

Attention: A high amount of chargebacks can also cause penalties from the brands (E.g. VISA and Mastercard) directly! So it can be, that they will force you -the merchant- into using 3-D Secure, if the fraud-rate is too high!

  1. With 3-D Secure/LiabilityShift: Like the name suggests, the liability gets shiftet! Shifted from the merchant, to the bank. So in case of fraud, the chargeback gets completely carried by the issuer. The card holder will get his money back, BUT, unlike before, the merchant can keep the charged money. The risk and the cost is carried by the issuer in this case, negating the costs on the merchant side.

3-D Secure on API-Level

The Saferpay JSON-API does return all necessary information inside the Liability-Container, when using Transaction Authorize or PaymentPage Assert. The important parameters are Authenticated and especially LiabilityShift. Furthermore LiableEntity will provide information about who will be liable in case of fraud.

Attention: Only the Transaction interface and Payment Page processes do support 3-D Secure! Please keep that in mind, when implementing Saferpay!

Attention: With 3DSv2 the XID value format changes (see respective request specification and below), while the VerificationValue is no longer returned!

"Liability": {
    "LiabilityShift": true,
    "LiableEntity": "ThreeDs",
    "ThreeDs": {
      "Authenticated": true,
      "LiabilityShift": true,
      "Xid": "63b1c8e6-2f51-4bb8-bd7b-32bb107f9d1b"
    }
  }

It depends on the merchant, how to proceed further, however Saferpay does recommend the following behaviors:

Tip: Only want to accept transactions with LiabilityShift? Check out the Condition-flag, that can be set within the Payment Page Initialize and Transaction Authorize requests, to control whether an authorization should be performed, or not, in the first place. Important Note: Issuers may reject the LiabilityShift with the authorization itself. The Condition-parameter does not cover such cases. Please still process the parameters accordingly!

Attention: These are only recommendations! Your credit card contract can dictate otherwise. Please contact your acquirer/card processor for further information!

Caution: Saferpay also returns LiabilityShift: false, if the used payment method does not support 3D Secure at all! Please also check the used payment method! Information, about whether, or not a payment method does support 3DS, can be found over here!

Authenticated LiabilityShift (Overall/3DS) Liable Entity Recommended behavior Info
true true/true ThreeDs Everything is okay. Continue transaction A full 3-D Secure authentication has been performed by the card holder. This is the best case scenario
false true/true ThreeDs Continue transaction In some cases, it can be, that the card holders bank grants the LiabilityShift. For instance, some banks only require one 3-D Secure every 24 hours and the others will be approved, in order to speed up the payment process. The LiabilityShift is still granted, however high risk businesses (Jewelery, Electronics, ect.) may want to stick to the highest level of security. It is your (The merchant) decision, if you want to accept these transactions, or if you want a full authentication.
true false/true Merchant Abort transaction Continue at your own risk In this case, the card holder authenticated him-/herself successfully, but his/her bank still rejects the LiabilityShift during authorization for internal reasons (Note that we -Saferpay- only get a rejection. The real reason is only known to the card holders bank). You are allowed to continue, but please note, that you (The merchant) will be liable in case of fraud (See above in this chapter). We recommend to not continue
false false/false Merchant Abort transaction Continue at your own risk Similar to the previous case, but this time, the card holder did not authenticated him-/herself successfully, which causes the LiabilityShift to be completely rejected. You are allowed to continue, but please note, that you (The merchant) will be liable in case of fraud (See above in this chapter). We highly recommend to not continue

Attention: If you intend on doing a dummy authorization, using 3-D Secure as a card holder verification measure, we do not recommend an amount < 1,-! Small amounts often get rejected by issuing banks, thus causing issues, with amount 0 not being possible at all.

Tip: If you want to keep the amount of Challenged transactions as low and thus your conversion-rate as high as possible, please make sure to submit a BillingAddress and DeliveryAddress within the PaymentPage Initialize or Transaction Initialize requests. This information will then be used for the scoring, as mentioned earlier, to increase the possibility of a frictionless transaction and thus a smooth experience for your customers!

Dynamic Currency Conversion

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, via the Payment Page or the Transaction Interface flows. 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.

Example of the DCC response

"Dcc": {
    "PayerAmount": {
      "Value": "352",
      "CurrencyCode": "JPY"
    }
  }

Versioning

If you are implementing new payment methods and/or features, please make sure to implement the correct SpecVersion of our API. If you are unsure, you should refer to the newest SpecVersion. Our Changelog will give you further information about the current and past spec-versions. You'll also find the newest Version in the top left of our API Specification.

Furthermore, it is possible to go back to previous spec-versions, by adding the version to the url. For example, if you want to go back to the 1.4 specification, simply add the version to the url like this:

https://saferpay.github.io/jsonapi/1.4

Note: SpecVersion 1.1 and lower are not available, since those were only released for internal use

Important Changes in certain SpecVersions

If you plan on upgrading to a newer SpecVersion, you may have to keep the following major changes in mind:

SpecVersion Changes
1.17+
  • Alias Insert Redirect: The redirectUrl has been moved into the new Redirect container and out of the root-object.
1.12+
  • Notification E-Mail: MerchantEmail has been replaced with MerchantEmails, a string array, that now accepts up to 10 e-mails, instead of the one, with SpecVersion 1.11 and lower!
1.10+
  • Refund Handling: Due to the introduction of Partial Captures and thus the splitting of a transaction into multiple transactions, you must do a refund using the CaptureId provided in the Capture and MultipartCapture responses, instead of the TransactionId, as with SpecVersions 1.9 and lower!
1.9+
  • Shift of the ThreeDs-container: Due to the introduction of the Fraud Free Service, the Liability can now be accepted by one of two entities. Thusly the old ThreeDs container has been moved a level down, into the Liability container. This also applies for merchants, that do not use the Fraud Free Service!. For more information, please consult the API-Specification!

Tip: You should also keep an eye on our API Changelog, where we keep a record of API changes!

Payment Method Features

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:

Payment method Capture|Cancel Multipart Captures Batch SCD Refund Recurring DCC 3DS MOTO Testing
American Express
Bancontact
BillPay Direct Debit
BillPay Purchase on Receipt
Bonus Card
Diners Club
Discover (See Diners)
ePrzelewy
eps
giropay
iDEAL
JCB
Maestro Int.
Mastercard
Payment method Capture|Cancel Multipart Captures Batch SCD Refund Recurring DCC 3DS MOTO Testing
MyOne
paydirekt
PayPal
PostFinance Card
PostFinance eFinance
SEPA Direct Debit
SOFORT
VISA
VPay (Processed via Visa!)
TWINT
Unionpay
Alipay
Apple Pay
This feature is available for the given Payment Method!
This feature is mandatory, for this payment method to function!
This feature needs requirements to be met! Please refer to the specific payment method chapter!
This feature is not available for the given Payment Method!
This feature depends on certain factors! For instance with wallets, it depends on the given means of payment, saved inside the wallet!
Capture|Cancel
Capture required, Cancel possible.
Multipart Captures
Multipart Captures can be performed! SIX ACQUIRING ONLY!
Batch
Daily closing required
SCD
Secure Alias Store available
Refund
Credit payments can be made
Recurring
Recurring payments
DCC
DCC available
3-D Secure
3-D Secure available
MOTO
Mail Phone Order available
Testing
A Simulator/Sandbox is available

Capture and Daily Closing

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

Capture serves to book and thus to conclude/finalize a payment. As long as a transaction has not passed through the capture, the amount is merely reserved (“authorised”), but it will not be transfered to the merchant account. On the API side, you receive information about the transaction via the Transaction => Status parameter (note that this is only a part of the data), e.g. through the PaymentPage Assert, or Transaction Authorize. Transactions which have not yet been booked are visible in Saferpay Backoffice as “Reservation", Reservations are marked as "AUTHORIZED" on API-level and have to go through the Capture, to be finalized:

"Transaction": {
  "Type": "PURCHASE",
  "Status": "AUTHORIZED",
  "Id": "MUOGAWA9pKr6rAv5dUKIbAjrCGYA",
  "Date": "2015-09-18T09:19:27.078Z",
  "Amount": {
    "Value": "100",
    "CurrencyCode": "CHF"
  },
  "AcquirerName": "AcquirerName",
  "AcquirerReference": "Reference"
}

If a transaction has already passed through, or does not need 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"
}


A Capture may only be executed once! Should a second Capture be attempted, the API will throw an error, informing you, that the Capture already happened:

{
  "ResponseHeader": {
    "SpecVersion": "1.14",
    "RequestId": "93388d85dc4519ea37595121dd8bd4ae"
  },
  "Behavior": "ABORT",
  "ErrorName": "TRANSACTION_ALREADY_CAPTURED",
  "ErrorMessage": "Transaction already captured"
}

Not all payment methods need a separate capture to trigger the cash flow. You can find an overview of which payment methods must be captured under Payment Method Features. Methods, that do not need the capture, will return the status "CAPTURED" right away.

Important: A reservation made through a certain payment processor, may only last for a limited time only. If this timeframe is exceeded, the authorised amount is released and becomes available to the card holder again. This may have the result that the amount can no longer be claimed. We recommend to Capture an authorization as soon as possible. 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.

Why do a Capture in the first place and not finalize the payment right away?

There are multiple reasons, why a capture is the better option:

  • Some countries require the merchant to only capture the money, if the goods get delivered and not beforehand! A Capture together, with the authorization, would be illegal in this case!
  • In rare cases, the processor may not respond to the autocapture. In these cases, it may be successfull, or not. You, the merchant, wouldn't know the final status in this case, which would make these cases rather complicated. In case of a seperate Capture, you can simply execute the request again, with the API giving you the final status!
  • Error and exception-handling would be way more costly and complex, with an autocapture. A simple reversal/Cancel, in case something went wrong (For example rejected LiabilityShift), wouldn't be possible, requiring you, to do a Refund, which will cost you money!
  • Fullfilling orders on store side would actually be more complex. What if you cannot deliver? An autocapture, as mentioned before, would lead to a Refund, instead of a simple reversal/Cancel.
  • Features like partial Captures and the Marketplace wouldn't be possible in the first place.

Daily Closing

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.

Important: Once the closing is complete, a transaction cannot be cancelled

anymore! You have to execute a Refund instead!

Special Cases

PAYPAL, SWISS POSTCARD, SEPA ELV, BANCONTACT and paydirekt

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.

Online Banking

giropay, iDEAL, SOFORT, Bancontact, eprzelewy und eps are online-banking solutions, that trigger a transfer and thus the cash flow via the purchaser’s online banking services. A successful transaction is always 100% complete.

Credit Cards via SIX Acquiring

Credit Cards (Includes: VISA, VPay, Mastercard, Maestro) with SIX Payment Services as processor, also execute the Daily Closing with the Capture!

Capturing a different amount

The Capture can also be used to change the amount of the transaction. It is generally possible to capture less, than initially authorized. So applying things like voucher codes, or similar is possible. Capturing more than initially authorized however, may result in an error and is not recommended. This however depends on your processor.

Reservation-Times

The time, in which a reservation can be successfully captured, highly depends on the respective processor and sometimes even the contract. Due to that, we cannot provide exact information, on when exactly to execute the capture of a specific transaction. Please contact your contract manager, or the processor, in order to get more information on the reservation-times.

Testing and Go Live

Saferpay offers an extensive Sandbox, that allows you to simulate transactions, flows and other things. When integrating Saferpay, it is very benefitial, to create your own test-account. You can get your own test-account over here.

Everything you need will be sent to you via E-Mail, ncluding things like your test CustomerId, TerminalIds, API user andpassword etc.

Difference between the Test and Live environments

  • First and foremost, test and live are completely seperated systems. So everything you do on one, or the other, cannot be transferred to the other system, like your transactions, or your saved cards. Due to this, it is very important, that you also seperate your data accordingly and keep an eye on which system the data belongs to. If actions are performed, with data, that does not belong to the respective system, the action will fail. This is so merchants may not confuse one system, with the other. For example by running on the test environment, whilst thinking they're live.
  • To reinforce this philosophy, Saferpay will not accept real credit cards on the test environment and vice versa! The test environment uses especially designed test-card, which can be found over here, alongside information abou the other simulators.
  • Furthermore, the test environment only runs simulators, that will emulate the behavior of the given payment method. However, no real money will be transferred, of course.
  • The test environment will behave as closely to the live environment, as possible -aside the above mentioned differences-. To ensure this, every function and every URL is mirrored onto the test environment. For example the live backoffice can be found under https://www.saferpay.com/bo/login, whereas the test backoffice can be found under https://test.saferpay.com/bo/login. You can access any URL, by simply changing the www to test and vice versa. This also applies to API URLs. For example https://test.saferpay.com/api/Payment/v1/PaymentPage/Initialize and https://www.saferpay.com/api/Payment/v1/PaymentPage/Initialize. The JSON-Object structure is the same on both systems, making a switch as easy, as possible.

Go live

You have completed your testing and are now ready to go live, but do not know how?

Well, if you haven't already, you need to contact our Sales in order to sign a live contract. Please mention the payment methods and currencies you may want to be activated. Some 3rd party payment methods may also require you to configure certain things, like a UserId, or a password. Those are also necessary for our activation-team to know, so you can process the given method, through Saferpay.

We will then activate everything necessary for you and send you the respective logins and Ids (Customer-and TerminalId), you need to go live. However, there are things you need to change on your end, with the Go-Live, before you can start accepting payments:

  • As mentioned, you will get new Logins and IDs with your live account. Those have to be changed inside your application.
  • The JSON-API user and password need to be set. Once you have recieved your live Backoffice user, you need to log into the Saferpay Backoffice. There you need to create your own credentials under Settings > JSON API basic authentication or JSON API client certificate. Those credentials have to be entered inside your application, so your system may authenticate itself towards our gateway. It is exactly the same, as with the credentials, you have recieved with the e-mail for your test account. However, due to security constraints, we will not generate these for you for the live environment. That is, why you have to do it yourself.
  • Lastly, you need to change the request-gateway URL from https://test.saferpay.com/api/[...] to https://www.saferpay.com/api/[...] in order to send your requests to the Saferpay live-system, instead of the test-system. Some pre-made modules (Like our own) however offer a live-mode, or a possibility to set the gateway-URL! Please look inside the admin backend of your shop. As mentioned above, all functions, URLs etc. can also be found on the test environment, by just changing this small detail.

After that, we recommend, trying out the payment methods, for example by using your own credit card for a test-order. You can always refund yourself inside the Saferpay Backoffice (If available for the given payment method! More over here), or inside your shop directly, should you have access to refunds via API. This ensures, that everything works as smoothly, as possible. If you encounter any problems during thistest, do not hesitate to contact us, so we may help you fix it as soon, as possible!

Understanding common Saferpay Terms

If you start with Saferpay, you'll often encounter certain terms and phrases, that are important to understand, when using Saferpay. What is a Customer, or Terminal ID? What is the difference between a Token and Tokenization? This part of the introduction aims to help you understand these terms and also their relationship to one another.

Term Explanation Where to find it
CustomerId

This is your primary account-number! Everything else about your Account is directly linked to this ID e.g.: Terminals, Card Aliases, Backoffice-Accounts, JSON-API Credentials and more!

The CustomerId is part of many other things. For example your Backoffice userId: e123456001 . It also is contained within your JSON-API userId: API_123456_12345678. additionally, it is displayed inside the Backoffice under Settings > JSON API Basic Authentication and Settings > JSON API Client Certificate.

TerminalId

A terminal always belongs to a Customerid and thus one account. The terminal contains certain payment methods, the connected contracts to those payment methods e.g. your acquiring contracts for credit cards, the supported currencies and other settings, like 3D Secure. Each terminal can only have one processor for a given payment method. If you want to process the same payment method over different processors, you need to have two different terminals. Each Saferpay account (CustomerId) can have multiple terminals beneath it. This could also be helpful, if you want to operate multiple shops (e.g. for different countries, or different sets of good alltogether) under one Saferpay account (CustomerId).

You can find each terminal for your given account inside the Saferpay Backoffice under Settings > Terminals

E Commerce Terminal

This is your standard terminal for transactions. It should be the standard terminal, if you are using Payment Page Initialize or Transaction initialize for secure E Commerce transactions (hence the name). You can have one, or more (see TerminalId), if you so desire, e.g. for multiple webshops. This type of terminal usually has the format 17xxxxxx.

You can differentiate between all your terminal types inside the Saferpay Backoffice under Settings > Terminals:

Backoffice Terminals
Secure PayGate (Terminal)

This terminal is the little brother of the E Commerce terminal. While also capable of processing secure E Commerce transactions, it is meant to be used within the Secure PayGate, a Saferpay product, that enables you to send payment-links and offers within an e-mail, through the Saferpay Backoffice. For your normal webshop, you should use your E Commerce terminal. Similar to its bigger brother, it also has the format 17xxxxxx.

You can differentiate between all your terminal types inside the Saferpay Backoffice under Settings > Terminals:

Backoffice Terminals
Mail Phone Order (MOTO) Terminal

This terminal is used, like the name suggests, for Mail Phone Order transactions within the Saferpay Backoffice. The background is, that the card holder is unable to perform a 3D Secure Authentication, or enter his/her CVC. Please note, that these security-measures also do not apply with transactions made over this type of terminal! MOTO terminals usually have the following format: 19xxxxxx

You can differentiate between all your terminal types inside the Saferpay Backoffice under Settings > Terminals:

Backoffice Terminals
Saferpay Backoffice

This is the Saferpay Web Backend, that contains information about your transactions, settings for your account, API-credentials and more.

The Live Backoffice can be found over here and the Test Backoffice can be found over here.

Backoffice Login

This is your login to the Saferpay Backoffice and it is directly connected to your CustomerId and thus your Saferpay account. In fact it incorporates the CustomerId. A Backoffice login may look like this: e123456001. The first being the type of the login, e for E Commerce, t for technician for example, the second being your CustomerId and the last the overall number of the login for said account.

The login will only be sent towards the login owner, that had be requested durign the signing of the Saferpay contract. New logins may be requested, but only through the contract holder of the Saferpay account him/herself.

API Credentials (API User/API Password)

These are your API authentication credentials. They're needed so your shop may authenticate itself which each request, towards our payment gateway. DO NOT CONFUSE THEM WITH YOUR BACKOFFICE LOGIN AND PASSWORD! Those are two different things. Each credential pair is linked directly to one CustomerId and only that Id. If you try to authenticate a different CustomerId, with credentials, that aren't connected to said Id, the request will fail. You can easily find out, if a CustomerId and API-user are connected together, by checking the userId itself. The customerId is part of said id: API_123456_12345678

On the test-environment, you'll get these credentials automatically, with your registration mail. However on the live-system, you need to create them inside the Saferpay Backoffice under Settings > JSON API Basic Authentication. There you'll also find a list with previously created userIds (Also applies to the automatically created test-credentials!). However, please note, that we only save the password encrypted! There is no way to recover it, should you lose it, so keep it somewhere safe, like a password-safe! You can however always create new credentials. Up to 10 are supported per Saferpay account. After that, you need to delete previously created ones.

Card Alias

This value is part of the Saferpay Secure Card Data store, which savely encrypts and stores card data in a PCI compliant manner. Most merchants do not have the necessary PCI certification to handle, in this case save, card details directly. Thusly Saferpay provides a service, that does exactly that. In return the merchant-system gets a card alias, which references the card details. This way the merchant can process card details, without actually knowing them.

The Alias is only returned through the API, when using Secure Card Data, or it has been set by the merchant in advance. Obtaining the alias in a different manner is not possible!

Token

First and foremost, one important thing: Do not confuse this with tokenization. Tokenization is essentially, what Secure Card Data is for. However the token is not meant to reference card details. That is, what the alias (See Card Alias) is meant for. It is important to seperate these two values, in order to avoid confusion. The Token is a value returned by the Saferpay API, to enable further actions on a transaction, not a card! So it actually references a specific transaction -and thus indirectly the card details- and by submitting it via the API, Saferpay knows what transaction you want to do an action with. For example with the Payment Page Assert, Saferpay knows, that you want the transaction details for the transaction behind said token!

The token is only returned via the API. Either through Payment Page Initialize, Transaction Initialize, or Alias Insert.

TransactionId

Each Saferpay transaction gets assigned a unique transactionId. This Id can be used to search for said transaction inside the Saferpay Backoffice, do captures and more. It can also help the Saferpay Support, if you need help with a certain transaction. If available, always submit the transactionId. This way the support can easily find the transaction and help you!

The transactionId is returned via the API. Either through Payment Page Assert, Transaction Authorize, Transaction AuthorizeDirect, or Transaction AuthorizeReferenced, inside Transaction.Id. Furthermore, you can also find it inside the Saferpay Backoffice, when checking the details for a given transaction.

CaptureId

With the introduction of Partial Captures, it became possible to split one transaction into multiple parts, allowing to gather multiple parts of the transaction amount and even transfer it to different bank accounts! However that also made it necessary to give each part its own Id, in order to do Refunds on an individual part! In order to not confuse it with the transactionId, the captureId has the suffix "_c"!

The captureId is returned via the API. Either through Transaction Capture, or Transaction MultipartCapture.

OrderId

This Id is your identifier, for a given order. It has to be created by your system and then be submitted through the API inside the Payment.OrderId parameter. While not mandatory (Note, that this may be manddatory for certain 3rd party processors!), we highly recommend using it. This Id will be passed through, all the way up to the processor. It will show up inside the Saferpay Backoffice as reference number, which enables you, to search for a transaction with said OrderId. It will also show up on your reconciliation files, you get from your processor, so you are able to keep track of your transactions and it will show up on the card holders bank statement. Note, that this depends on the card holders bank. Some do not support it, even though the OrderId is set! Also, should you use PayerNote (See PayerNote), this will be used instead of the OrderId, to show up on the card holders bank statement, if supported by his bank. The OrderId however will still be used for your reconciliation files.

This has to be set by the merchants system in Payment.OrderId. Furthermore, you can also find it inside the Saferpay Backoffice, when checking the details for a given transaction, as Reference number.

PayerNote

Sometimes the merchant wants to seperate the Orderid from the text, that is displayed on the card holders bank statement. This is, what PayerNote is used for. If filled, PayerNote will be used, instead of the OrderId, for the card holder. Note, that your reconciliation-files will still use the orderid! Furthermore, some banks may not support this feature and will instead display a static text.

This has to be set by the merchants system in Payment.Payernote. Important Note: Your contract needs to be set up for the usage of the "dynamic descriptor" in order for PayerNote to take effect!. Please contact your contractual manager for more details!

Back to Top