Server API version 1.0
Java

icon-search-large

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.

Properties
Property Type Required Details
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.

close

Description

Object containing the billing address details
  • SDK Object type
    Address
close

Description

Additional address information
close

Description

City
Note: For payments with product 1503 the maximum length is not 40 but 20.
close

Description

ISO 3166-1 alpha-2 country code
close

Description

House number
close

Description

Full name of the state or province
close

Description

Streetname
close

Description

Zip code
Note: For payments with product 1503 the maximum length is not 10 but 8.
close

Description

Object containing company information
  • SDK Object type
    CompanyInformation
close

Description

Name of company, as a customer
close

Description

Your identifier for the customer. It is used in the fraud-screening process.
close

Description

Object containing personal information of the customer
  • SDK Object type
    PersonalInformationToken
close

Description

Given name(s) or first name(s) of the customer
close

Description

Surname(s) or last name(s) of the customer
close

Description

Middle name - In between first name and surname - of the customer
close
Deprecated: Use companyInformation.vatNumber instead

Description

Local VAT number of the company
close

Description

The complete credit/debit card number (also know as the PAN)
close

Description

Card holder's name on the card
close

Description

Expiry date of the card
Format: MMYY
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.

close

Description

Object containing the billing address details
  • SDK Object type
    Address
close

Description

Additional address information
close

Description

City
Note: For payments with product 1503 the maximum length is not 40 but 20.
close

Description

ISO 3166-1 alpha-2 country code
close

Description

House number
close

Description

Full name of the state or province
close

Description

Streetname
close

Description

Zip code
Note: For payments with product 1503 the maximum length is not 10 but 8.
close

Description

Object containing company information
  • SDK Object type
    CompanyInformation
close

Description

Name of company, as a customer
close

Description

Your identifier for the customer. It is used in the fraud-screening process.
close

Description

Object containing personal information of the customer
  • SDK Object type
    PersonalInformationToken
close

Description

Given name(s) or first name(s) of the customer
close

Description

Surname(s) or last name(s) of the customer
close

Description

Middle name - In between first name and surname - of the customer
close
Deprecated: Use companyInformation.vatNumber instead

Description

Local VAT number of the company
close

Description

Object containing the billing address details
  • SDK Object type
    Address
close

Description

Additional address information
close

Description

City
Note: For payments with product 1503 the maximum length is not 40 but 20.
close

Description

ISO 3166-1 alpha-2 country code
close

Description

House number
close

Description

Full name of the state or province
close

Description

Streetname
close

Description

Zip code
Note: For payments with product 1503 the maximum length is not 10 but 8.
close

Description

Object containing company information
  • SDK Object type
    CompanyInformation
close

Description

Name of company, as a customer
close

Description

Your identifier for the customer. It is used in the fraud-screening process.
close

Description

Object containing personal information of the customer
  • SDK Object type
    PersonalInformationToken
close

Description

Given name(s) or first name(s) of the customer
close

Description

Surname(s) or last name(s) of the customer
close

Description

Middle name - In between first name and surname - of the customer
close
Deprecated: Use companyInformation.vatNumber instead

Description

Local VAT number of the company
close

Description

Object containing the billing address details
  • SDK Object type
    Address
close

Description

Additional address information
close

Description

City
Note: For payments with product 1503 the maximum length is not 40 but 20.
close

Description

ISO 3166-1 alpha-2 country code
close

Description

House number
close

Description

Full name of the state or province
close

Description

Streetname
close

Description

Zip code
Note: For payments with product 1503 the maximum length is not 10 but 8.
close

Description

Object containing company information
  • SDK Object type
    CompanyInformation
close

Description

Name of company, as a customer
close

Description

Object containing contact details like email address and phone number
  • SDK Object type
    ContactDetailsToken
close

Description

Email address of the customer
close

Description

Your identifier for the customer. It is used in the fraud-screening process.
close

Description

Object containing personal information of the customer
  • SDK Object type
    PersonalInformationToken
close

Description

Given name(s) or first name(s) of the customer
close

Description

Surname(s) or last name(s) of the customer
close

Description

Middle name - In between first name and surname - of the customer
close
Deprecated: Use companyInformation.vatNumber instead

Description

Local VAT number of the company
close

Description

Object containing Account holder and IBAN information
  • SDK Object type
    BankAccountIban
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.
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

Properties
Property Type Required Details
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
close

Description

Contains detailed information on one single error.
  • SDK Object type
    APIError
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.
close

Description

Error code
close

Description

HTTP status code for this error that can be used to determine the type of error
close

Description

ID of the error. This is a short human-readable message that briefly describes the error.
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
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.

Properties
Property Type Required Details
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
close

Description

Contains detailed information on one single error.
  • SDK Object type
    APIError
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.
close

Description

Error code
close

Description

HTTP status code for this error that can be used to determine the type of error
close

Description

ID of the error. This is a short human-readable message that briefly describes the error.
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
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"
            }
        ]
    }
    
icon_top_1