Common Saferpay terms - Glossary
Last updated
Was this helpful?
Last updated
Was this helpful?
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.
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 and .
This is the Saferpay Web Backend, that contains information about your transactions, settings for your account, API-credentials and more.
The Live Backoffice and the Test Backoffice .
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 during the signing of the Saferpay contract. New logins may be requested, through the contract holder of the Saferpay account him/herself, or created by someone with access to the .
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 altogether) under one Saferpay account (CustomerId).
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.
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
The contract number is not the same, as your TerminalId and cannot serve as its replacement. When connecting to the Saferpay APIs, you have to use the TerminalId and not the contract number.
These are your API authentication credentials. They're needed so your shop may authenticate itself which each request, towards our payment gateway. 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
First and foremost, one important thing:
Do not confuse this with tokenization.
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.
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 mandatory for certain 3rd party processors.), we highly recommend using it.
Sometimes the merchant wants to separate 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.
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.
Some banks may not support this feature and will instead display a static text for your card holder.
This has to be set by the merchants system in Payment.Payernote.
Those are a lot of terms at once and sometimes it is hard to understand in what relationship, or hierarchy these things stand to each other.
The following picture will give you an overview about this:
At the top, you'll always find your account, represented by the CustomerId. Everything about your account is connected to that Id. Some other values may be part of the overall account, but are connected to something else within that account.
For example your contract number is connected to a terminal and that terminal is connected to your customerId.
This also does not mean, that everything is gated off within your account. Some things can also have an indirect relationship with each other. For example a Backoffice user can create API credentials, but they are not directly linked to each other. Instead, they are part of the same account. As another example, you can use one, or multiple sets of API credentials, in order to access all your terminals on that account, but the terminals are not directly bound to a specific set of API credentials.
You can find each terminal for your given account inside the Saferpay Backoffice under
This is your standard terminal for transactions. It should be the standard terminal, if you are using or 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 .
Please note, that you'll only have such a terminal, if you also have signed an E-Commerce contract. If you cannot find an E-Commerce terminal and you need one, please , or your direct sales contact, if you have one.
You can differentiate between all your terminal types inside the Saferpay Backoffice under .
Please note, that you'll only have such a terminal, if you also have signed a Secure PayGate contract. If you cannot find a Secure PayGate terminal and you need one, please , or your direct sales contact, if you have one.
You can differentiate between all your terminal types inside the Saferpay Backoffice under .
Please note, that you'll only have such a terminal, if you also have signed a Mail Phone Order contract. If you cannot find a Mail Phone Order terminal and you need one, please , or your direct sales contact, if you have one.
The contract number (Sometimes also called VP-Number), as the name suggests, is the ID of your contract with the respective processor of a given payment method, so the processor can identify the merchant. It can have multiple formats, depending on said processor/payment method. The contract number is connected to at least one and the contract itself defines things like the payment method itself, the currency and the availability of other features, like for example. Without the contract number, a payment method does not work.
You can find your contract number in your terminal configuration, inside the Saferpay Backoffice under .
Do not confuse them with your and password! These are not the same credentials and will lead to an error.
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 . 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.
This token is an extra credential, that is needed to use the .
The Access Token must be created by the merchant, similar to the API credentials. You can do so inside the Saferpay Backoffice under .
This value is part of the , which safely 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.
It is important to note, that the Card Alias only belongs to one and only one and thus Saferpay Account. It cannot be shared between accounts.
The Alias is only returned through the API, when using , or it has been set by the merchant in advance. Obtaining the alias in a different manner is not possible.
Tokenization is essentially, what is for. However the token is not meant to reference card details. That is, what the is meant for. It is important to separate 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 , Saferpay knows, that you want the transaction details for the transaction behind said token.
The token is only returned via the API. Either through , , or .
The transactionId is returned via the API. Either through , , , or , inside Transaction.Id. Furthermore, you can also find it inside the , when checking the details for a given transaction.
With the introduction of , 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 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 , or .
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 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 , when checking the details for a given transaction, as Reference number.
Note, that your -files will still use the OrderId.
