Get token

GET https://{domainname}/v1/{merchantId}/tokens/{tokenId}

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.

We will never return full card details.

The request does not have any additional input parameters.

Request example

SDK: Java

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.

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
Group card	object	no	read close
close Description Object containing card details SDK Object type TokenCard Property is part of a group Learn more Properties that make up a group are mutually exclusive, which means you can only include one of each group in any given call. If there are multiple groups at one level in the object hierarchy we use numbers to distinguish groups from one another.
billingAddress	object	yes	read close
close Description Object containing the billing address details SDK Object type Address
additionalInfo	string (50)	no	read close
close Description Additional address information
city	string	depends	read close
close Description City Note: For payments with product 1503 the maximum length is not 40 but 20. Depends on: Required for Invoice payments (201) Required for Direct Debit UK (705), except when a token has been included in the request that includes this value. Required for the creation of a Payout. Required for payments with product 9000 (AfterPay Installments) or 9001 (AfterPay Invoice). Required when address is included in Seller.
countryCode	string (2)	no	read close
close Description ISO 3166-1 alpha-2 country code
houseNumber	string (15)	depends	read close
close Description House number Depends on: Required when address is included in Seller.
state	string (35)	no	read close
close Description Full name of the state or province
street	string (50)	depends	read close
close Description Streetname Depends on: Required for Invoice payments (201) Required for Direct Debit UK (705), except when a token has been included in the request that includes this value. Required for the creation of a Payout. Required for payments with product 9000 (AfterPay Installments) or 9001 (AfterPay Invoice). Required when address is included in Seller.
zip	string	depends	read close
close Description Zip code Note: For payments with product 1503 the maximum length is not 10 but 8. Depends on: Required for Direct Debit UK (705), except when a token has been included in the request that includes this value. Required for payments with product 9000 (AfterPay Installments) or 9001 (AfterPay Invoice).
companyInformation	object	no	read close
close Description Object containing company information SDK Object type CompanyInformation
name	string (40)	no	read close
close Description Name of company, as a customer
merchantCustomerId	string (15)	no	read close
close Description Your identifier for the customer. It is used in the fraud-screening process.
personalInformation	object	no	read close
close Description Object containing personal information of the customer SDK Object type PersonalInformationToken
firstName	string (15)	no	read close
close Description Given name(s) or first name(s) of the customer
surname	string (70)	no	read close
close Description Surname(s) or last name(s) of the customer
surnamePrefix	string (15)	no	read close
close Description Middle name - In between first name and surname - of the customer
vatNumber	string (17)	no	read close
close Deprecated: Use companyInformation.vatNumber instead Description Local VAT number of the company
cardNumber	string (19)	depends	read close
close Description The complete credit/debit card number (also know as the PAN). The minimum input length is 12 digits. Depends on: Required for Create and Update token.
cardholderName	string (51)	no	read close
close Description Card holder's name on the card
expiryDate	string (4)	depends	read close
close Description Expiry date of the card Format: MMYY Depends on: Required for Create and Update token.
Group eWallet	object	no	read close
close Description Object containing eWallet details SDK Object type TokenEWallet Property is part of a group Learn more Properties that make up a group are mutually exclusive, which means you can only include one of each group in any given call. If there are multiple groups at one level in the object hierarchy we use numbers to distinguish groups from one another.
billingAddress	object	yes	read close
close Description Object containing the billing address details SDK Object type Address
additionalInfo	string (50)	no	read close
close Description Additional address information
city	string	depends	read close
close Description City Note: For payments with product 1503 the maximum length is not 40 but 20. Depends on: Required for Invoice payments (201) Required for Direct Debit UK (705), except when a token has been included in the request that includes this value. Required for the creation of a Payout. Required for payments with product 9000 (AfterPay Installments) or 9001 (AfterPay Invoice). Required when address is included in Seller.
countryCode	string (2)	no	read close
close Description ISO 3166-1 alpha-2 country code
houseNumber	string (15)	depends	read close
close Description House number Depends on: Required when address is included in Seller.
state	string (35)	no	read close
close Description Full name of the state or province
street	string (50)	depends	read close
close Description Streetname Depends on: Required for Invoice payments (201) Required for Direct Debit UK (705), except when a token has been included in the request that includes this value. Required for the creation of a Payout. Required for payments with product 9000 (AfterPay Installments) or 9001 (AfterPay Invoice). Required when address is included in Seller.
zip	string	depends	read close
close Description Zip code Note: For payments with product 1503 the maximum length is not 10 but 8. Depends on: Required for Direct Debit UK (705), except when a token has been included in the request that includes this value. Required for payments with product 9000 (AfterPay Installments) or 9001 (AfterPay Invoice).
companyInformation	object	no	read close
close Description Object containing company information SDK Object type CompanyInformation
name	string (40)	no	read close
close Description Name of company, as a customer
merchantCustomerId	string (15)	no	read close
close Description Your identifier for the customer. It is used in the fraud-screening process.
personalInformation	object	no	read close
close Description Object containing personal information of the customer SDK Object type PersonalInformationToken
firstName	string (15)	no	read close
close Description Given name(s) or first name(s) of the customer
surname	string (70)	no	read close
close Description Surname(s) or last name(s) of the customer
surnamePrefix	string (15)	no	read close
close Description Middle name - In between first name and surname - of the customer
vatNumber	string (17)	no	read close
close Deprecated: Use companyInformation.vatNumber instead Description Local VAT number of the company
billingAddress	object	yes	read close
close Description Object containing the billing address details SDK Object type Address
additionalInfo	string (50)	no	read close
close Description Additional address information
city	string	depends	read close
close Description City Note: For payments with product 1503 the maximum length is not 40 but 20. Depends on: Required for Invoice payments (201) Required for Direct Debit UK (705), except when a token has been included in the request that includes this value. Required for the creation of a Payout. Required for payments with product 9000 (AfterPay Installments) or 9001 (AfterPay Invoice). Required when address is included in Seller.
countryCode	string (2)	no	read close
close Description ISO 3166-1 alpha-2 country code
houseNumber	string (15)	depends	read close
close Description House number Depends on: Required when address is included in Seller.
state	string (35)	no	read close
close Description Full name of the state or province
street	string (50)	depends	read close
close Description Streetname Depends on: Required for Invoice payments (201) Required for Direct Debit UK (705), except when a token has been included in the request that includes this value. Required for the creation of a Payout. Required for payments with product 9000 (AfterPay Installments) or 9001 (AfterPay Invoice). Required when address is included in Seller.
zip	string	depends	read close
close Description Zip code Note: For payments with product 1503 the maximum length is not 10 but 8. Depends on: Required for Direct Debit UK (705), except when a token has been included in the request that includes this value. Required for payments with product 9000 (AfterPay Installments) or 9001 (AfterPay Invoice).
companyInformation	object	no	read close
close Description Object containing company information SDK Object type CompanyInformation
name	string (40)	no	read close
close Description Name of company, as a customer
merchantCustomerId	string (15)	no	read close
close Description Your identifier for the customer. It is used in the fraud-screening process.
personalInformation	object	no	read close
close Description Object containing personal information of the customer SDK Object type PersonalInformationToken
firstName	string (15)	no	read close
close Description Given name(s) or first name(s) of the customer
surname	string (70)	no	read close
close Description Surname(s) or last name(s) of the customer
surnamePrefix	string (15)	no	read close
close Description Middle name - In between first name and surname - of the customer
vatNumber	string (17)	no	read close
close Deprecated: Use companyInformation.vatNumber instead Description Local VAT number of the company
billingAddress	object	depends	read close
close Description Object containing the billing address details Depends on: Required for the creation of a token for the countryCode property within this object. SDK Object type Address
additionalInfo	string (50)	no	read close
close Description Additional address information
city	string	depends	read close
close Description City Note: For payments with product 1503 the maximum length is not 40 but 20. Depends on: Required for Invoice payments (201) Required for Direct Debit UK (705), except when a token has been included in the request that includes this value. Required for the creation of a Payout. Required for payments with product 9000 (AfterPay Installments) or 9001 (AfterPay Invoice). Required when address is included in Seller.
countryCode	string (2)	no	read close
close Description ISO 3166-1 alpha-2 country code
houseNumber	string (15)	depends	read close
close Description House number Depends on: Required when address is included in Seller.
state	string (35)	no	read close
close Description Full name of the state or province
street	string (50)	depends	read close
close Description Streetname Depends on: Required for Invoice payments (201) Required for Direct Debit UK (705), except when a token has been included in the request that includes this value. Required for the creation of a Payout. Required for payments with product 9000 (AfterPay Installments) or 9001 (AfterPay Invoice). Required when address is included in Seller.
zip	string	depends	read close
close Description Zip code Note: For payments with product 1503 the maximum length is not 10 but 8. Depends on: Required for Direct Debit UK (705), except when a token has been included in the request that includes this value. Required for payments with product 9000 (AfterPay Installments) or 9001 (AfterPay Invoice).
companyInformation	object	no	read close
close Description Object containing company information SDK Object type CompanyInformation
name	string (40)	no	read close
close Description Name of company, as a customer
contactDetails	object	no	read close
close Description Object containing contact details like email address and phone number SDK Object type ContactDetailsToken
emailAddress	string (70)	no	read close
close Description Email address of the customer
merchantCustomerId	string (15)	no	read close
close Description Your identifier for the customer. It is used in the fraud-screening process.
personalInformation	object	no	read close
close Description Object containing personal information of the customer SDK Object type PersonalInformationToken
firstName	string (15)	no	read close
close Description Given name(s) or first name(s) of the customer
surname	string (70)	no	read close
close Description Surname(s) or last name(s) of the customer
surnamePrefix	string (15)	no	read close
close Description Middle name - In between first name and surname - of the customer
vatNumber	string (17)	no	read close
close Deprecated: Use companyInformation.vatNumber instead Description Local VAT number of the company
bankAccountIban	object	depends	read close
close Description Object containing Account holder and IBAN information Depends on: Required for the creation of a token for the iban property within this object. SDK Object type BankAccountIban
iban	string (50)	depends	read close
close Description The 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. Depends on: Required for the creation of a Payout Required for Create and Update token. Required for payments with product 9000 (AfterPay Installments) in Austria (AT) and Germany (DE). Required for Create mandate and Create payment with mandate calls
isRecurring	boolean	no	read close
close Description true false
id	string	yes	read close
close Description ID of the token
paymentProductId	integer	yes	read close
close Description Payment product identifier Please see payment products for a full overview of possible values.

Response example

SDK: Java

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

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
errorId	string	yes	read close
close Description Unique reference, for debugging purposes, of this error response
errors	array of object	yes	read close
close Description List of one or more errors
items	object	no	read close
close Description Contains detailed information on one single error. SDK Object type APIError
category	string	no	read close
close Description Category the error belongs to. The category should give an indication of the type of error you are dealing with. Possible values: CONNECT_PLATFORM_ERROR - indicating that a functional error has occurred in the E-Payment platform. PAYMENT_PLATFORM_ERROR - indicating that a functional error has occurred in the Payment platform. IO_ERROR - indicating that a technical error has occurred within the E-Payment platform or between E-Payment and any of the payment platforms or third party systems.
code	string	yes	read close
close Description Error code
httpStatusCode	integer	no	read close
close Description HTTP status code for this error that can be used to determine the type of error
id	string	no	read close
close Description ID of the error. This is a short human-readable message that briefly describes the error.
message	string	no	read close
close Description Human-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 Description Returned 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: a.b selects the value of property b of root property a, a[1] selects the first element of the array in root property a, a[b='some value'] selects all elements of the array in root property a that have a property b with value 'some value'.

Response example

SDK: Java

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.

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
errorId	string	yes	read close
close Description Unique reference, for debugging purposes, of this error response
errors	array of object	yes	read close
close Description List of one or more errors
items	object	no	read close
close Description Contains detailed information on one single error. SDK Object type APIError
category	string	no	read close
close Description Category the error belongs to. The category should give an indication of the type of error you are dealing with. Possible values: CONNECT_PLATFORM_ERROR - indicating that a functional error has occurred in the E-Payment platform. PAYMENT_PLATFORM_ERROR - indicating that a functional error has occurred in the Payment platform. IO_ERROR - indicating that a technical error has occurred within the E-Payment platform or between E-Payment and any of the payment platforms or third party systems.
code	string	yes	read close
close Description Error code
httpStatusCode	integer	no	read close
close Description HTTP status code for this error that can be used to determine the type of error
id	string	no	read close
close Description ID of the error. This is a short human-readable message that briefly describes the error.
message	string	no	read close
close Description Human-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 Description Returned 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: a.b selects the value of property b of root property a, a[1] selects the first element of the array in root property a, a[b='some value'] selects all elements of the array in root property a that have a property b with value 'some value'.

Response example

SDK: Java

This scenario you will probably use the most

{
    "errorId" : "657b10da-d2f9-4088-a948-bf190ef516b1-00000318",
    "errors" : [
        {
            "code" : "700540",
            "message" : "PROFILE_NOT_FOUND"
        }
    ]
}

Get token

Tokens

Request

Request example

Responses

Response 200 - OKTokenResponse

Description

Description

Description

Description

Depends on:

Description

Description

Depends on:

Description

Description

Depends on:

Description

Depends on:

Description

Description

Description

Description

Description

Description

Description

Description

Description

Depends on:

Description

Description

Depends on:

Description

Description

Description

Description

Depends on:

Description

Description

Depends on:

Description

Description

Depends on:

Description

Depends on:

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Depends on:

Description

Description

Depends on:

Description

Description

Depends on:

Description

Depends on:

Description

Description

Description

Description

Description

Description

Description

Description

Description

Depends on:

Description

Description

Depends on:

Description

Description