Get token
Tokens
Using our tokenization service you can tokenize re-usable payment data like card data, bank account data including Direct Debit Mandates and PayPal BillingAgreementIDs. The main purpose for tokens is re-use of payment details. The additional benefit is that you do not need to store any sensitive payment details on your server, while still having the benefit to be able to re-use them. This allows you to process recurring card transactions without actually having access to the real card data.
Tokens can be used for two types of transactions:
- Recurring: Automatically charging your consumer in a regular, e.g. monthly, time frame;
- One-off: Charge the consumer without the consumer having to re-enter all of their payment details.
The second scenario can be used to facilitate a one-click checkout solution, that would still allow the consumer to enter only their CVV value for a card transaction. CVV values can't be tokenized as they are not allowed to be stored at all.
Besides the re-use of payment data, tokens have one other major use-case: Direct Debit Mandates. Especially SEPA Direct Debit transactions require that the mandate for the transactions is managed through a token with an associated mandate. Mandates are created in one go with the token, but can have a state that requires that they are approved before they can be used. As the mandate process is in most cases an offline process the approval will allow you to set the location and date where and when the mandate was signed by the consumer. Without an approved SEPA mandate you will not be able to process any payments regarding this mandate.
Request
Use GET on a specific token to retrieve all the tokenized data for that ID. You can use some of this data towards the consumer to let them choose which stored data to re-use. You can also use data like the expiry date to check if you need to ask for updated data from your consumer.
Request example
This scenario you will probably use the most
-
TokenResponse response = client.merchant("merchantId").tokens().get("tokenId");
Responses
Please find below an overview of the possible responses.
Response 200 - OKTokenResponse
All non-sensitive data that is stored is returned.
Properties
|
|||
Property | Type | Required | Details |
---|---|---|---|
object | no | read close | |
close
DescriptionObject containing card details
|
|||
object | yes | read close | |
additionalInfo | string (50) | no | read close |
close
DescriptionAdditional address information
|
|||
city | string | depends | read close |
close
DescriptionCity
Note: For payments with product 1503 the maximum length is not 40 but 20. |
|||
countryCode | string (2) | no | read close |
close
DescriptionISO 3166-1 alpha-2 country code
|
|||
houseNumber | string (15) | depends | read close |
close
DescriptionHouse number
|
|||
state | string (35) | no | read close |
close
DescriptionFull name of the state or province
|
|||
street | string (50) | depends | read close |
close
DescriptionStreetname
|
|||
zip | string | depends | read close |
close
DescriptionZip code
Note: For payments with product 1503 the maximum length is not 10 but 8. |
|||
object | no | read close | |
name | string (40) | no | read close |
close
DescriptionName of company, as a customer
|
|||
merchantCustomerId | string (15) | no | read close |
close
DescriptionYour identifier for the customer. It is used in the fraud-screening process.
|
|||
object | no | read close | |
close
DescriptionObject containing personal information of the customer
|
|||
firstName | string (15) | no | read close |
close
DescriptionGiven name(s) or first name(s) of the customer
|
|||
surname | string (70) | no | read close |
close
DescriptionSurname(s) or last name(s) of the customer
|
|||
surnamePrefix | string (15) | no | read close |
close
DescriptionMiddle name - In between first name and surname - of the customer
|
|||
vatNumber | string (17) | no | read close |
close
Deprecated:
Use companyInformation.vatNumber instead
DescriptionLocal VAT number of the company
|
|||
cardNumber | string (19) | depends | read close |
close
DescriptionThe complete credit/debit card number (also know as the PAN). The minimum input length is 12 digits.
|
|||
cardholderName | string (51) | no | read close |
close
DescriptionCard holder's name on the card
|
|||
expiryDate | string (4) | depends | read close |
close
DescriptionExpiry date of the card
Format: MMYY |
|||
object | no | read close | |
close
DescriptionObject containing eWallet details
|
|||
object | yes | read close | |
additionalInfo | string (50) | no | read close |
close
DescriptionAdditional address information
|
|||
city | string | depends | read close |
close
DescriptionCity
Note: For payments with product 1503 the maximum length is not 40 but 20. |
|||
countryCode | string (2) | no | read close |
close
DescriptionISO 3166-1 alpha-2 country code
|
|||
houseNumber | string (15) | depends | read close |
close
DescriptionHouse number
|
|||
state | string (35) | no | read close |
close
DescriptionFull name of the state or province
|
|||
street | string (50) | depends | read close |
close
DescriptionStreetname
|
|||
zip | string | depends | read close |
close
DescriptionZip code
Note: For payments with product 1503 the maximum length is not 10 but 8. |
|||
object | no | read close | |
name | string (40) | no | read close |
close
DescriptionName of company, as a customer
|
|||
merchantCustomerId | string (15) | no | read close |
close
DescriptionYour identifier for the customer. It is used in the fraud-screening process.
|
|||
object | no | read close | |
close
DescriptionObject containing personal information of the customer
|
|||
firstName | string (15) | no | read close |
close
DescriptionGiven name(s) or first name(s) of the customer
|
|||
surname | string (70) | no | read close |
close
DescriptionSurname(s) or last name(s) of the customer
|
|||
surnamePrefix | string (15) | no | read close |
close
DescriptionMiddle name - In between first name and surname - of the customer
|
|||
vatNumber | string (17) | no | read close |
close
Deprecated:
Use companyInformation.vatNumber instead
DescriptionLocal VAT number of the company
|
|||
object | yes | read close | |
additionalInfo | string (50) | no | read close |
close
DescriptionAdditional address information
|
|||
city | string | depends | read close |
close
DescriptionCity
Note: For payments with product 1503 the maximum length is not 40 but 20. |
|||
countryCode | string (2) | no | read close |
close
DescriptionISO 3166-1 alpha-2 country code
|
|||
houseNumber | string (15) | depends | read close |
close
DescriptionHouse number
|
|||
state | string (35) | no | read close |
close
DescriptionFull name of the state or province
|
|||
street | string (50) | depends | read close |
close
DescriptionStreetname
|
|||
zip | string | depends | read close |
close
DescriptionZip code
Note: For payments with product 1503 the maximum length is not 10 but 8. |
|||
object | no | read close | |
name | string (40) | no | read close |
close
DescriptionName of company, as a customer
|
|||
merchantCustomerId | string (15) | no | read close |
close
DescriptionYour identifier for the customer. It is used in the fraud-screening process.
|
|||
object | no | read close | |
close
DescriptionObject containing personal information of the customer
|
|||
firstName | string (15) | no | read close |
close
DescriptionGiven name(s) or first name(s) of the customer
|
|||
surname | string (70) | no | read close |
close
DescriptionSurname(s) or last name(s) of the customer
|
|||
surnamePrefix | string (15) | no | read close |
close
DescriptionMiddle name - In between first name and surname - of the customer
|
|||
vatNumber | string (17) | no | read close |
close
Deprecated:
Use companyInformation.vatNumber instead
DescriptionLocal VAT number of the company
|
|||
object | depends | read close | |
additionalInfo | string (50) | no | read close |
close
DescriptionAdditional address information
|
|||
city | string | depends | read close |
close
DescriptionCity
Note: For payments with product 1503 the maximum length is not 40 but 20. |
|||
countryCode | string (2) | no | read close |
close
DescriptionISO 3166-1 alpha-2 country code
|
|||
houseNumber | string (15) | depends | read close |
close
DescriptionHouse number
|
|||
state | string (35) | no | read close |
close
DescriptionFull name of the state or province
|
|||
street | string (50) | depends | read close |
close
DescriptionStreetname
|
|||
zip | string | depends | read close |
close
DescriptionZip code
Note: For payments with product 1503 the maximum length is not 10 but 8. |
|||
object | no | read close | |
name | string (40) | no | read close |
close
DescriptionName of company, as a customer
|
|||
object | no | read close | |
close
DescriptionObject containing contact details like email address and phone number
|
|||
emailAddress | string (70) | no | read close |
close
DescriptionEmail address of the customer
|
|||
merchantCustomerId | string (15) | no | read close |
close
DescriptionYour identifier for the customer. It is used in the fraud-screening process.
|
|||
object | no | read close | |
close
DescriptionObject containing personal information of the customer
|
|||
firstName | string (15) | no | read close |
close
DescriptionGiven name(s) or first name(s) of the customer
|
|||
surname | string (70) | no | read close |
close
DescriptionSurname(s) or last name(s) of the customer
|
|||
surnamePrefix | string (15) | no | read close |
close
DescriptionMiddle name - In between first name and surname - of the customer
|
|||
vatNumber | string (17) | no | read close |
close
Deprecated:
Use companyInformation.vatNumber instead
DescriptionLocal VAT number of the company
|
|||
object | depends | read close | |
close
DescriptionObject containing Account holder and IBAN information
|
|||
iban | string (50) | depends | read close |
close
DescriptionThe IBAN is the International Bank Account Number. It is an internationally agreed format for the BBAN and includes the ISO country code and two check digits.
|
|||
isRecurring | boolean | no | read close |
close
Description
|
|||
id | string | yes | read close |
close
DescriptionID of the token
|
|||
paymentProductId | integer | yes | read close |
close
DescriptionPayment product identifier
Please see payment products for a full overview of possible values. |
Response example
This scenario you will probably use the most
-
{ "id" : "9511cb6c-a9b1-4d16-a576-dca13f72add3", "paymentProductId" : 770, "sepaDirectDebit" : { "customer" : { "companyInformation" : { "name" : "Acme Labs" }, "merchantCustomerId" : "1234", "billingAddress" : { "additionalInfo" : "Suite II", "city" : "Monument Valley", "countryCode" : "US", "houseNumber" : "1", "state" : "Utah", "street" : "Desertroad", "zip" : "84536" }, "personalInformation" : { "name" : { "firstName" : "Wile", "surname" : "Coyote", "surnamePrefix" : "E." } }, "contactDetails" : { "emailAddress" : "wile.e.coyote@acmelabs.com", "emailMessageType" : "html" } }, "mandate" : { "bankAccountIban" : { "accountHolderName" : "Wile E. Coyote", "iban" : "IT60X0542811101000000123456" }, "customerContractIdentifier" : "123456789", "debtor" : { "city" : "Burbank", "countryCode" : "US", "firstName" : "Chuck", "houseNumber" : "411", "state" : "California", "stateCode" : "CA", "street" : "N Hollywood Way", "surname" : "Jones", "zip" : "91505" }, "mandateApproval" : { "mandateSignatureDate" : "20150102", "mandateSignaturePlace" : "Monument Valley", "mandateSigned" : true }, "mandateId" : "G9991L0X14981", "preNotification" : "do-not-send", "isRecurring" : true, "creditor" : { "city" : "Monument Valley", "countryCode" : "US", "houseNumber" : "13", "id" : "US123456", "name" : "Road Runner", "street" : "Desertroad", "zip" : "84536" } } } }
Response 400 - Bad requestErrorResponse
Properties
|
|||
Property | Type | Required | Details |
---|---|---|---|
errorId | string | yes | read close |
close
DescriptionUnique reference, for debugging purposes, of this error response
|
|||
array of object | yes | read close | |
close
DescriptionList of one or more errors
|
|||
object | no | read close | |
category | string | no | read close |
close
DescriptionCategory the error belongs to. The category should give an indication of the type of error you are dealing with.
Possible values:
|
|||
code | string | yes | read close |
close
DescriptionError code
|
|||
httpStatusCode | integer | no | read close |
close
DescriptionHTTP status code for this error that can be used to determine the type of error
|
|||
id | string | no | read close |
close
DescriptionID of the error. This is a short human-readable message that briefly describes the error.
|
|||
message | string | no | read close |
close
DescriptionHuman-readable error message that is not meant to be relayed to customer as it might tip off people who are trying to commit fraud
|
|||
propertyName | string | no | read close |
close
DescriptionReturned only if the error relates to a value that was missing or incorrect.
Contains a location path to the value as a JSonata query. Some common examples:
|
Response example
This scenario you will probably use the most
-
{ "errorId" : "15eabcd5-30b3-479b-ae03-67bb351c07e6-00000092", "errors" : [ { "code" : "20000000", "propertyName" : "bankAccountBban.accountNumber", "message" : "PARAMETER_NOT_FOUND_IN_REQUEST" } ] }
Response 404 - Not foundErrorResponse
In case you are trying to retrieve a token that does not exist or has been deleted you will get a 404 response.
Properties
|
|||
Property | Type | Required | Details |
---|---|---|---|
errorId | string | yes | read close |
close
DescriptionUnique reference, for debugging purposes, of this error response
|
|||
array of object | yes | read close | |
close
DescriptionList of one or more errors
|
|||
object | no | read close | |
category | string | no | read close |
close
DescriptionCategory the error belongs to. The category should give an indication of the type of error you are dealing with.
Possible values:
|
|||
code | string | yes | read close |
close
DescriptionError code
|
|||
httpStatusCode | integer | no | read close |
close
DescriptionHTTP status code for this error that can be used to determine the type of error
|
|||
id | string | no | read close |
close
DescriptionID of the error. This is a short human-readable message that briefly describes the error.
|
|||
message | string | no | read close |
close
DescriptionHuman-readable error message that is not meant to be relayed to customer as it might tip off people who are trying to commit fraud
|
|||
propertyName | string | no | read close |
close
DescriptionReturned only if the error relates to a value that was missing or incorrect.
Contains a location path to the value as a JSonata query. Some common examples:
|
Response example
This scenario you will probably use the most
-
{ "errorId" : "657b10da-d2f9-4088-a948-bf190ef516b1-00000318", "errors" : [ { "code" : "700540", "message" : "PROFILE_NOT_FOUND" } ] }