This site requires javascript to be enabled.

  • Search AI-powered

Results for

xxx

Create token

POST https://{domainname}/v1/{merchantId}/tokens

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 this call to tokenize payment details. Note that only basic input validation is performed as no actual transaction is processed. We do not check the validity of the payment details with any of its acquirers or third party payment processors. If you want to only tokenize payment details that have been successfully processed it is advised to create tokens using the tokenize action on successful payments. The payload can, next to the paymentProductID contain one of the following types of objects to tokenize:

  • card data
  • SEPA Direct Debit data (including mandate information)
  • Non SEPA Direct Debit data
  • eWallet data

Tokenization using Encrypted Customer Input

Note: this applies only for sending encrypted customer card data, and cannot be used to tokenize (SEPA) Direct Debit or eWallet data

The mandatory and optional fields are the same as for the card group when not using the encrypted customer input.

Please ensure that the following 3 mandatory fields are present:
  • cardNumber
  • expiryDate
  • countryCode

The following optional fields may also be submitted:
  • cardholderName
  • additionalInfo
  • city
  • houseNumber
  • stateCode
  • street
  • zip
  • firstName
  • surname

PayloadCreateTokenRequest

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

An alias for the token. This can be used to visually represent the token.
If no alias is given in Create token calls, a payment product specific default is used, e.g. the obfuscated card number for card payment products.
Do not include any unobfuscated sensitive data in the alias.
close

Description

Object containing the details of the customer
  • SDK Object type
    CustomerToken
close

Description

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

Description

Additional address information. The additionalInfo is truncated after 10 characters for payments, refunds or payouts that are processed by the WL Online Payment Acceptance platform
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. The houseNumber is truncated after 10 characters for payments, refunds or payouts that are processed by the WL Online Payment Acceptance platform
close

Description

Full name of the state or province
close

Description

ISO 3166-2 alpha-3 state code
Notes:
  • The maximum length for 3-D Secure version 2 is AN3 for payments that are processed by the GlobalCollect platform
  • The maximum length for paymentProductId 1503 (Boleto) is AN2 for payments that are processed by the GlobalCollect platform
  • The maximum length is 3 for payments that are processed by the WL Online Payment Acceptance platform
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

The date of incorporation is the specific date when the company was registered with the relevant authority.
Format: YYYYMMDD
close

Description

Name of company, as a customer
close

Description

Local VAT number of the company
close

Description

Your identifier for the customer. It can be used as a search criteria in the GlobalCollect Payment Console and is also included in the GlobalCollect report files. It is used in the fraud-screening process for payments on the Ogone Payment Platform.
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
  • SDK Object type
    PersonalNameToken
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 card tokenizable details
  • SDK Object type
    TokenCardData
close

Description

Object containing the card details (without CVV)
  • SDK Object type
    CardWithoutCvv
close

Description

The complete credit/debit card number (also know as the PAN). The minimum input length is 12 digits.
close

Description

The card holder's name on the card. Minimum length of 2, maximum length of 51 characters.
close

Description

Expiry date of the card
Format: MMYY
close

Description

Issue number on the card (if applicable)
close

Description

Date of the first transaction (for ATOS)
Format: YYYYMMDD
close

Description

Reference of the provider (of the first transaction) - used to store the ATOS Transaction Certificate
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

An alias for the token. This can be used to visually represent the token.
If no alias is given in Create token calls, a payment product specific default is used, e.g. the obfuscated card number for card payment products.
Do not include any unobfuscated sensitive data in the alias.
close

Description

Object containing the details of the customer
  • SDK Object type
    CustomerToken
close

Description

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

Description

Additional address information. The additionalInfo is truncated after 10 characters for payments, refunds or payouts that are processed by the WL Online Payment Acceptance platform
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. The houseNumber is truncated after 10 characters for payments, refunds or payouts that are processed by the WL Online Payment Acceptance platform
close

Description

Full name of the state or province
close

Description

ISO 3166-2 alpha-3 state code
Notes:
  • The maximum length for 3-D Secure version 2 is AN3 for payments that are processed by the GlobalCollect platform
  • The maximum length for paymentProductId 1503 (Boleto) is AN2 for payments that are processed by the GlobalCollect platform
  • The maximum length is 3 for payments that are processed by the WL Online Payment Acceptance platform
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

The date of incorporation is the specific date when the company was registered with the relevant authority.
Format: YYYYMMDD
close

Description

Name of company, as a customer
close

Description

Local VAT number of the company
close

Description

Your identifier for the customer. It can be used as a search criteria in the GlobalCollect Payment Console and is also included in the GlobalCollect report files. It is used in the fraud-screening process for payments on the Ogone Payment Platform.
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
  • SDK Object type
    PersonalNameToken
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 eWallet tokenizable data
  • SDK Object type
    TokenEWalletData
close

Description

Identification of the PayPal recurring billing agreement
close

Description

Object containing non SEPA Direct Debit details
  • SDK Object type
    TokenNonSepaDirectDebit
  • 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

An alias for the token. This can be used to visually represent the token.
If no alias is given in Create token calls, a payment product specific default is used, e.g. the obfuscated card number for card payment products.
Do not include any unobfuscated sensitive data in the alias.
close

Description

Object containing the details of the customer
  • SDK Object type
    CustomerToken
close

Description

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

Description

Additional address information. The additionalInfo is truncated after 10 characters for payments, refunds or payouts that are processed by the WL Online Payment Acceptance platform
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. The houseNumber is truncated after 10 characters for payments, refunds or payouts that are processed by the WL Online Payment Acceptance platform
close

Description

Full name of the state or province
close

Description

ISO 3166-2 alpha-3 state code
Notes:
  • The maximum length for 3-D Secure version 2 is AN3 for payments that are processed by the GlobalCollect platform
  • The maximum length for paymentProductId 1503 (Boleto) is AN2 for payments that are processed by the GlobalCollect platform
  • The maximum length is 3 for payments that are processed by the WL Online Payment Acceptance platform
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

The date of incorporation is the specific date when the company was registered with the relevant authority.
Format: YYYYMMDD
close

Description

Name of company, as a customer
close

Description

Local VAT number of the company
close

Description

Your identifier for the customer. It can be used as a search criteria in the GlobalCollect Payment Console and is also included in the GlobalCollect report files. It is used in the fraud-screening process for payments on the Ogone Payment Platform.
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
  • SDK Object type
    PersonalNameToken
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 mandate details
  • SDK Object type
    MandateNonSepaDirectDebit
close

Description

Object containing specific data for Direct Debit UK
  • SDK Object type
    TokenNonSepaDirectDebitPaymentProduct705SpecificData
  • 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

Core reference number for the direct debit instruction in UK
close

Description

Object containing account holder name and bank account information
  • SDK Object type
    BankAccountBban
close

Description

Name of the account holder
close

Description

Bank account number
close

Description

Bank code
close

Description

Name of the bank
close

Description

Branch code
close

Description

Bank check digit
close

Description

ISO 3166-1 alpha-2 country code of the country where the bank account is held For UK payouts this value is automatically set to GB as only payouts to UK accounts are supported.
close

Description

Object containing specific data for ACH
  • SDK Object type
    TokenNonSepaDirectDebitPaymentProduct730SpecificData
  • 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 account holder name and bank account information
  • SDK Object type
    BankAccountBban
close

Description

Name of the account holder
close

Description

Bank account number
close

Description

Bank code
close

Description

Name of the bank
close

Description

Branch code
close

Description

Bank check digit
close

Description

ISO 3166-1 alpha-2 country code of the country where the bank account is held For UK payouts this value is automatically set to GB as only payouts to UK accounts are supported.
close

Description

Object containing SEPA Direct Debit details
  • SDK Object type
    TokenSepaDirectDebitWithoutCreditor
  • 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

An alias for the token. This can be used to visually represent the token.
If no alias is given in Create token calls, a payment product specific default is used, e.g. the obfuscated card number for card payment products.
Do not include any unobfuscated sensitive data in the alias.
close

Description

Object containing the details of the customer
  • SDK Object type
    CustomerTokenWithContactDetails
close

Description

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

Description

Additional address information. The additionalInfo is truncated after 10 characters for payments, refunds or payouts that are processed by the WL Online Payment Acceptance platform
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. The houseNumber is truncated after 10 characters for payments, refunds or payouts that are processed by the WL Online Payment Acceptance platform
close

Description

Full name of the state or province
close

Description

ISO 3166-2 alpha-3 state code
Notes:
  • The maximum length for 3-D Secure version 2 is AN3 for payments that are processed by the GlobalCollect platform
  • The maximum length for paymentProductId 1503 (Boleto) is AN2 for payments that are processed by the GlobalCollect platform
  • The maximum length is 3 for payments that are processed by the WL Online Payment Acceptance platform
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

The date of incorporation is the specific date when the company was registered with the relevant authority.
Format: YYYYMMDD
close

Description

Name of company, as a customer
close

Description

Local VAT number of the company
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

Preference for the type of email message markup
  • plain-text
  • html
close

Description

Your identifier for the customer. It can be used as a search criteria in the GlobalCollect Payment Console and is also included in the GlobalCollect report files. It is used in the fraud-screening process for payments on the Ogone Payment Platform.
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
  • SDK Object type
    PersonalNameToken
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 mandate details
  • SDK Object type
    MandateSepaDirectDebitWithoutCreditor
close

Description

Object containing Account holder and IBAN information
  • SDK Object type
    BankAccountIban
close

Description

Name in which the account is held.
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

Identifies the contract between customer and merchant
close

Description

Object containing information on the debtor
  • SDK Object type
    Debtor
close

Description

Additional information about the debtor's address, like Suite II, Apartment 2a
close

Description

City of the debtor's address
close

Description

ISO 3166-1 alpha-2 country code of the debtor's address
close

Description

Debtor first name
close

Description

House number of the debtor's address
close

Description

State of debtor address
close

Description

ISO 3166-2 alpha-3 state code
Notes:
  • The maximum length for 3-D Secure version 2 is AN3.
  • The maximum length for paymentProductId 1503 (Boleto) is AN2.
close

Description

Street of debtor's address
close

Description

Debtor's last name
close

Description

Prefix of the debtor's last name
close

Description

ZIP code of the debtor's address
close

Description

  • true
  • false
close

Description

Object containing the details of the mandate approval
  • SDK Object type
    MandateApproval
close

Description

The date when the mandate was signed
Format: YYYYMMDD
close

Description

The city where the mandate was signed
close

Description

  • true = Mandate is signed
  • false = Mandate is not signed
close

Description

Indicates whether a pre-notification should be sent to the customer.
  • do-not-send - Do not send a pre-notification
  • send-on-first-collection - Send a pre-notification
close

Description

Data that was encrypted client side containing all customer entered data elements like card data.
Note: Because this data can only be submitted once to our system and contains encrypted card data you should not store it. As the data was captured within the context of a client session you also need to submit it to us before the session has expired.
close

Description

Payment product identifier
Please see payment products for a full overview of possible values.

Request example

SDK: JSON

This scenario you will probably use the most

  • {
        "paymentProductId" : 705,
        "nonSepaDirectDebit" : {
            "mandate" : {
                "paymentProduct705SpecificData" : {
                    "authorisationId" : "123456",
                    "bankAccountBban" : {
                        "accountNumber" : "000000123456",
                        "bankCode" : "05428",
                        "branchCode" : "11101",
                        "checkDigit" : "X",
                        "countryCode" : "IT"
                    }
                }
            },
            "customer" : {
                "merchantCustomerId" : "1234",
                "companyInformation" : {
                    "name" : "Acme Labs"
                },
                "personalInformation" : {
                    "name" : {
                        "firstName" : "Wile",
                        "surnamePrefix" : "E.",
                        "surname" : "Coyote"
                    }
                },
                "billingAddress" : {
                    "city" : "Monument Valley",
                    "countryCode" : "US",
                    "houseNumber" : "1",
                    "additionalInfo" : "Suite II",
                    "state" : "Utah",
                    "street" : "Desertroad",
                    "zip" : "84536"
                }
            }
        }
    }
    
  • {
        "paymentProductId" : 1,
        "card" : {
            "customer" : {
                "billingAddress" : {
                    "countryCode" : "US"
                }
            },
            "data" : {
                "cardWithoutCvv" : {
                    "cardNumber" : "****************",
                    "expiryDate" : "****"
                }
            }
        }
    }
    
  • {
        "paymentProductId" : 1,
        "card" : {
            "customer" : {
                "merchantCustomerId" : "1234",
                "personalInformation" : {
                    "name" : {
                        "firstName" : "Wile",
                        "surnamePrefix" : "E.",
                        "surname" : "Coyote"
                    }
                },
                "companyInformation" : {
                    "name" : "Acme Labs"
                },
                "billingAddress" : {
                    "street" : "Desertroad",
                    "houseNumber" : "13",
                    "additionalInfo" : "b",
                    "zip" : "84536",
                    "city" : "Monument Valley",
                    "state" : "Utah",
                    "countryCode" : "US"
                }
            },
            "data" : {
                "cardWithoutCvv" : {
                    "cardNumber" : "****************",
                    "expiryDate" : "****",
                    "cardholderName" : "Wile E. Coyote"
                }
            }
        }
    }
    

Responses

When we are able to tokenize the payment details two possible responses can occur:

  • HTTP Response 200 is returned when you try to tokenize card details for a card that has already been tokenized in the past
  • HTTP Response 201 is returned when the system successfully created a new token
When we are unable to tokenize the payment details an HTTP response in the 4XX or 5XX range is returned.

Response 200 - OKCreateTokenResponse

An HTTP 200 response indicates that the card data was previously tokenized. The previous token is returned again. The evaluation regarding duplication is done purely on the card number. Please note that it is possible that the data other than the card number is different from the stored data, in that case you may need to update the token with the new data.

Properties
Property Type Required Details
close

Description

Indicates if a new token was created
  • true - A new token was created
  • false - A token with the same card number already exists and is returned. Please note that the existing token has not been updated. When you want to update other data then the card number, you need to use the update API call, as data is never updated during the creation of a token.
close

Description

The initial Payment ID of the transaction from which the token has been created
close

Description

ID of the token

Response example

SDK: JSON

This scenario you will probably use the most

  • {
        "isNewToken" : false,
        "token" : "49575a9c-5bd5-4539-a672-b5b4e7abf681"
    }
    

Response 201 - CreatedCreateTokenResponse

An HTTP 201 response indicates that the data was successfully tokenized and the newly created token is returned.

Properties
Property Type Required Details
close

Description

Indicates if a new token was created
  • true - A new token was created
  • false - A token with the same card number already exists and is returned. Please note that the existing token has not been updated. When you want to update other data then the card number, you need to use the update API call, as data is never updated during the creation of a token.
close

Description

The initial Payment ID of the transaction from which the token has been created
close

Description

ID of the token

Response example

SDK: JSON

This scenario you will probably use the most

  • {
        "isNewToken" : true,
        "token" : "49575a9c-5bd5-4539-a672-b5b4e7abf681"
    }
    

Response 400 - Bad requestErrorResponse

Properties
Property Type Required Details
close

Description

Unique reference, for debugging purposes, of this error response
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 Connect 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 Connect platform or between Connect 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'.
close

Description

ID of the request that can be used for debugging purposes

Response example

SDK: JSON

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 403 - UnauthorizedErrorResponse

When something is wrong with your credentials you will get a 403 response. This could happen when your account is not allowed to tokenize any payment data.

Properties
Property Type Required Details
close

Description

Unique reference, for debugging purposes, of this error response
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 Connect 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 Connect platform or between Connect 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'.
close

Description

ID of the request that can be used for debugging purposes

Response example

SDK: JSON

This scenario you will probably use the most

  • {
        "errorId" : "657b10da-d2f9-4088-a948-bf190ef516b1-000002b4",
        "errors" : [
            {
                "code" : "700660",
                "message" : "SERVICE_NOT_ALLOWED"
            }
        ]
    }