Onboard merchant

Each merchant must be onboarded to the platform before the integrator can start to tokenize the PANs. When the merchant is onboarded toward VTS and MDES, the integrator will receive a unique Merchant ID. Below is a state-chart diagram, which shows the onboarding flow.

1. The integrator initiates the onboarding of a merchant by calling Cardtokens.

2. Cardtokens onboards towards Mastercard MDES.

3. Cardtokens onboards to VISA VTS.

4. The integrator will receive a Merchant ID when the onboarding is completed to both VTS and MDES.

Endpoint and method

Method: POST

Endpoint: https://api.cardtokens.io/api/merchant

Request parameters

Parameter name	Data type	Description
companyprimarylegalname	String	Required. The legal name of the merchant. Alphanumeric, excepting semi-colon, percent sign, and parentheses; maximum 75 characters.
primarywebsiteurl	String	Required. The primary website URL of the merchant. Must start with https://. Alphanumeric, valid URL; maximum 100 characters.
companycity	String	Required. The city of the merchant. Alphabetic, numeric, or the following characters: spaces, ' (single quote), . (period), and - (hyphen); maximum 100 characters
companycountrycode	String	Required. The country code of the merchant. E.g., Denmark is “DK”. The field is formatted according to ISO-3166-2. Alphabetic; maximum 2 characters.
primarycontactemail	String	Required. The e-mail address of the primary contact at the merchant. Alphanumeric, valid email address; maximum 256 characters.
businessidentificationtype	String	Required. The type of business identification type. Refer to the table titled Business Identification types & values below for specific formatting details for each country.
businessidentificationvalue	String	Required. The value associated with the business identifier type, if provided. For the countries specified, the value has to be formatted like {countrycode}{value}. E.g., Cardtokens Aps is formatted like DK42967920. Refer to the table titled Business Identification types & values below for specific formatting details for each country.

Business Identification types & values

Type	Value
ABN Australian business number	11 numeric digits
BID Business identification number; all countries. Note: You must contact your Visa representative before using BID for businessIdentificationType	8 numeric digits
BN Canadian business number	9 numeric digits
BRNO Malaysia only	Up to 10 numeric digits followed by a hyphen and a single character or 12 numeric digits
CL Commercial License Number; Qatar	4–6 numeric digits
CLN Company License Number; Kuwait	5–7 numeric digits
CNPJ Brazil only	14 alphanumeric characters, identified by n in the example, and punctuation characters (period, slash, and hyphen) Example: nn.nnn.nnn/nnnn-nn
CR Company Registration Number; Saudi Arabia	10–12 numeric digits
CUIT Argentina only	11 numeric digits
EDRPOU Ukraine	Ukrainian corporations: 8 numeric digits Ukrainian individual entrepreneurs: 10 numeric digits
EIN US Federal tax ID (US only)	9 numeric digits
HKBR Hong Kong only	11 numeric digits and a hyphen Example: 12345678-123
NATIONAL_ID Dominican Republic (DO); Cedula de Identidad (Merchant Owner ID)	DO + 11 digits Example: DO01234567890
NZBN New Zealand business number	13 numeric digits
PAN Indian business identification number	10 alphanumeric characters
RFC Mexico only	Mexican corporations: 12 alphanumeric Mexican individuals: 13 alphanumeric characters
RNC Dominican Republic (DO); Registro Nacional de Contribuyentes (National Contributors Number)	DO + 9 digits Example: DO123456789
RUC Peru only	11 numeric digits
RUT Chile and Colombia only	Chile: 9 numeric digits Colombia: 10 numeric digits
SIN Canadian social insurance number	9 numeric digits
SSN US social security number (US only)	9 numeric digits
UEN Singapore only	9 or 10 alphanumeric characters
VAT Austria Belgium Bulgaria Croatia Czech Republic Denmark Estonia Finland France Germany Greece Hungary Ireland Italy Latvia Lithuania Luxembourg Malta Netherlands Norway Poland Portugal Republic of Cyprus Romania Saudi Arabia Slovak Republic Slovenia South Africa Spain Sweden Switzerland Turkey Ukraine United Arab Emirates United Kingdom	Austria (AT) Format: AT + 9 characters in which the first character is always a 'U' Example: ATU12345678 Belgium (BE) Format: BE + 10 characters. Prefix with zero ‘0’ if the customer provides a 9 digit VAT number. Example: BE1234567890 Bulgaria (BG) Format: BG + 9 or 10 characters Example: BG123456789 or BG0123456789 Croatia (HR) Format: HR + 11 characters. Example: HR01234567891 Czech Republic (CZ) Format: CZ + 8, 9 or 10 characters. Example: CZ12345678, CZ123456789, or CZ0123456789 Denmark (DK) Format: DK + 8 characters Example: DK12345678 Estonia (EE) Format: EE + 9 characters Example: EE123456789 Finland (FI) Format: FI + 8 characters Example: FI12345678 France (FR) Format: FR + 11 characters Example: FR12345678901 Germany (DE) Format: DE + 9 characters Example: DE123456789 Greece (GR) Format: GR + 9 characters Example: GR123456789 Hungary (HU) Format: HU + 8 characters Example: HU12345678 Ireland (IE) Format: IE + 8 numeric or alphabetic characters Example: IE1234567X Italy (IT) Format: IT + 11 characters Example: IT12345678901 Latvia (LV) Format: LV + 11 characters Example: LV12345678901 Lithuania (LT) Format: LT + 9 or 12 characters Example: LT123456789 or LT123456789012 Luxembourg (LU) Format: LU + 8 characters Example: LU12345678 Malta (MT) Format: MT + 8 characters Example: MT12345678 Netherlands (NL) Format: NL + 12 characters of which the tenth character is always B. Example: NL123456789B01 Norway (NO) Format: NO + 9 digits and the letters + MVA Example: NO123456789MVA Poland (PL) Format: PL + 10 alphanumeric characters Example: PL1234567890 Portugal (PT) Format: PT + 9 characters Example: PT123456789 Republic of Cyprus (CY) Format: CY + 9 characters. The last character must always be a letter. Example: CY12345678X Romania (RO) Format: RO + 2 to 10 characters. Example: RO12, RO123, RO1234, RO12345, RO123456, RO1234567, RO12345678, RO123456789, or RO1234567890 Saudi Arabia (SA) Format: 15 numeric digits Example: 123456789012345 Slovak Republic (SK) Format: SK + 10 characters Example: SK1234567890 Slovenia (SI) Format: SI + 8 characters Example: SI12345678 South Africa (ZA) Format: 10 or 11 digits Example: 1234567890 or 12345678901 Spain (ES) Format: ES + 9 numeric digits Example: ES123456789 Sweden (SE) Format: SE + 12 digits Example: SE123456789012 Switzerland (CH) Format: CH + 9 digits + MWST, TVA, or IVA Note: German part: MWST - French part: TVA - Italian part: IVA Example: CH123456789MWST, CH123456789TVA, or CH123456789IVA Turkey (TR) Format: TR + 10 characters Example: TR1234567890 Ukraine (UA) Format: 9 or 12 digits Example: 123456789 or 123456789012 United Arab Emirates (AE) Format: 15 digits Example: 123456789012345 United Kingdom (GB) Format: GB + 9 digits Example: GB123456789

Response parameters

Parameter name	Data type	Description
merchantid	String	The unique reference to the onboarded merchant.
schemes	String[]	An array of schemes connected to this merchant. Values can be of “visa”, “mastercard”, “testscheme”.

Example request

{
  "companyprimarylegalname": "Cardtokens Aps",
  "primarywebsiteurl": "https://www.cardtokens.io",
  "companycity": "Aalborg",
  "companycountrycode": "DK",
  "primarycontactemail": "webmaster@cardtokens.io",
  "businessidentificationtype": "VAT",
  "businessidentificationvalue": "DK42967920"
}

Example response

{
  "merchantid": "33df271c57c6441785e03a116a35de98",
  "schemes": ["mastercard", "visa", "testscheme"]
}

Onboard time

info

Notice that it takes approx. 48 hours for the schemes to enable an onboarded merchant.

Merchants who are not yet onboarded with the schemes will return an error 400 (status code) upon create token requests:

{"status":400,"message":"Input to tokenRequestorId is invalid","reason":"trConfigIssue"}

Scheme onboarding notification

When the merchant is confirmed enabled with all the connected schemes, Cardtokens will notify the integrator using GET. You are now able to generate network tokens for the merchant. Cardtokens notifies when Cardtokens has validated that the onboarded agreement works by creating a token directly towards the schemes. A notification is transmitted for each scheme onboarded.

TRID

A token requestor ID (TRID) is a unique identifier that allows merchants to request network tokens from token providers and is a prerequisite for enabling network tokenization. Each merchant must obtain their unique TRID before moving forward with network tokenization through the card networks.

Endpoint and method

Method: GET

Endpoint: https://www.website-super-shop/{merchantid}/visa/{trid}

Endpoint: https://www.website-super-shop/{merchantid}/mastercard/{trid}

Endpoint: https://www.website-super-shop/{merchantid}/testscheme/{trid} (test only)