Merchant Onboarding

post

Create a merchant.

The API is synchronous and the Scheme TSP is not involved.

Header parameters

authorizationstring · min: 1 · max: 512Required

Technical identifier pre-defined at on-boarding that identifies the API consumer. Format shall be the string 'APIKEY' followed by a space and the api key value.
Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b

x-correlation-idstring · min: 1 · max: 36Required

Technical identifier used for troubleshooting.
It helps on customer support when needed.
Each API request must be identified with a unique correlation Id.
It correlates the response and the request and eventually a notification if any.

Body

merchantNamestring · min: 1 · max: 60Required

An unique merchant name that is end user friendly.

Example: My MerchantPattern: ^[A-Za-z0-9-_. ]+$

Responses

201

Created

application/json

merchantIdstring · min: 1 · max: 128Required

Identifier of the merchant provided by Thales at on-boarding.

creationTimestampstring · max: 64Required

Token creation timestamp compliant with ISO 8601.

Example: 2025-11-10T09:08:24.479Z

400

Bad request - Not Retryable

401

Unauthorized - Not Retryable

429

Too Many Requests - Retryable

500

Internal Server Error - Not Retryable

503

Service Unavailable - Retryable

post/merchants

POST /tsh-cof/merchants HTTP/1.1
Host: thales.api.com
authorization: text
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "merchantName": "the-ecom-store.com"
}

{
  "merchantId": "85f6a8d7-a946-46a2-8c9d-075701e678f9",
  "creationTimestamp": "2021-05-11T11:52:20.354Z"
}

Update Merchant Mastercard (S-COF)

put

Update the merchant setup for Mastercard Secure Card-On-File program.

Path parameters

merchantIdstring · min: 1 · max: 128Required

The unique merchant identifier.

Header parameters

authorizationstring · min: 1 · max: 512Required

x-correlation-idstring · min: 1 · max: 36Required

Body

merchantLegalNamestring · min: 1 · max: 60Required

Legal name of the merchant.

Pattern: ^[A-Za-z0-9-_. ]+$

websiteUrlstring · min: 1 · max: 100Required

Merchant website URL.

Example: http://www.mymerchant.comPattern: ^[A-Za-z0-9-_.:/]+$

merchantCitystring · min: 1 · max: 100Required

City of the merchant address.

Example: San FranciscoPattern: ^[A-Za-z0-9-_. ]+$

merchantCountrystring · min: 2 · max: 2Required

Merchant country in ISO-3166-1 alpha-2 two-letter country code.

Example: US

mcServiceIdstring · max: 256Optional

Reserved for future use.
A unique identifier assigned by Mastercard for which tokens are created uniquely for the entity onboarded.

merchantCategorystring · min: 1 · max: 256Optional

Required only for Payment Facilitator model. Can define a type of merchants group. merchantCategory value is forwarded to the issuers. Thales recommends to set it to the generic value 'payfac'.

acquirerIdstring · min: 1 · max: 11Optional

Acquiring institution identification code

Pattern: ^([0-9a-zA-Z]*$)

localestring · min: 1 · max: 10Optional

Locale identifier following BCP 47 (e.g., en-US, es-MX)

Example: en-US

Responses

202

Accepted

No content

400

Bad request - Not Retryable

401

Unauthorized - Not Retryable

404

Not Found - Not Retryable

429

Too Many Requests - Retryable

500

Internal Server Error - Not Retryable

503

Service Unavailable - Retryable

put/merchants/{merchantId}/mastercard/secure-cof

PUT /tsh-cof/merchants/{merchantId}/mastercard/secure-cof HTTP/1.1
Host: thales.api.com
authorization: text
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 169

{
  "merchantLegalName": "My Merchant SARL",
  "websiteUrl": "http://mymerchant.com",
  "merchantCity": "Paris",
  "merchantCountry": "FR",
  "supportedCardType": "CREDIT",
  "mcServiceId": ""
}

No content

Update Merchant Visa

put

Update the merchant setup for VISA.

Path parameters

merchantIdstring · min: 1 · max: 128Required

The unique merchant identifier.

Header parameters

authorizationstring · min: 1 · max: 512Required

x-correlation-idstring · min: 1 · max: 36Required

Body

merchantLegalNamestring · min: 1 · max: 60Required

Legal name of the merchant.

Pattern: ^[A-Za-z0-9-_. ]+$

primaryContactEmailstring · min: 1 · max: 100Required

Email address of the merchant primary contact.

Example: jsmith@mymerchant.comPattern: ^[A-Za-z0-9-_.@]+$

websiteUrlstring · min: 1 · max: 100Required

Merchant website URL.

Example: http://www.mymerchant.comPattern: ^[A-Za-z0-9-_.:/]+$

merchantCitystring · min: 1 · max: 100Required

City of the merchant address.

Example: San FranciscoPattern: ^[A-Za-z0-9-_. ]+$

merchantCountrystring · min: 2 · max: 2Required

Merchant country in ISO-3166-1 alpha-2 two-letter country code.

Example: US

allowCardUpdateNotificationbooleanOptional

Visa charges to the acquirers the update of the token when a card is renewed. The acquirers may reflect the service fees to the customer. allowCardUpdateNotification = true enables the service.
When allowCardUpdateNotification = false the token is no more valid after the card renewal. No Token Update notification is sent.

Example: true

businessIdentificationTypestring · enum · max: 12Optional

One of the below configuration must be provided:
- businessIdentificationType and businessIdentificationValue or
- acquirerId and acquirerMerchantId.

Merchant business identification type.

BusinessIdentificationType	Description	Format
ABN	Australian business number	11 numeric digits
ACN	Australian company number	9 numeric digits
BID	VISA business identification number; all countries. You must contact your Visa representative before using BID	8 numeric digits
BIN	Kazakhstan business identification number	12 numeric digits
BIR	Philippines certificate of registration	12 numeric digits; hyphen-separated
BN	Canadian business number	9 numeric digits
BRN	South Korea business registration number	10 numeric digits; hyphen-separated
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
CORPORATE_NUMBER	Japan corporate number	13 numeric digits; leading digit is a non-zero check digit for the following 12 digits
CNPJ	Brazil only.	14 alphanumeric characters, identified by n in the example, and punctuation characters (period, slash, and hyphen)
CR	Company Registration Number Saudi Arabia.	10-12 numeric digits
CUIT	Argentina only.	11 numeric digits
EDRPOU	Ukraine. Ukrainian corporations	8 numeric digits and 10 numeric digits for Ukrainian individual entrepeneurs
EIN	US Federal tax ID (US only).	9 numeric digits
HKBR	Hong Kong only.	11 numeric digits and a hyphen
INI	Andorran General Indirect Tax.	8 alphanumeric characters; the first and last characters must be alphabetic.
NATIONAL_ID	Dominican Republic (DO). Cedula de Identidad (Merchant Owner ID)	DO + 11 digits
NIB	Indonesia business identification number	13 numeric digits
NID	South Africa national identification number	13 numeric digits
NZBN	New Zealand business number.	13 numeric digits
PAN	Indian business identification number	10 alphanumeric characters
PAN	Belarus payer account number	9 numeric digits
RFC	Mexico only.	12 alphanumeric characters for corporations and 13 alphanumeric characters for individuals
RNC	Dominican Republic (DO). Registro Nacional de Contribuyentes (National Contributors Number)	DO + 9 digits
RUC	Peru only.	11 numeric digits
RUT	Chile and Colombia only.	8 numeric digits followed by a hyphen and one verification character or digit for Chile; 10 numeric digits for Columbia
SIN	Canadian social insurance number	9 numeric digits
SSN	US social security number (US only)	9 numeric digits
TC	Vietnam tax code	10 or 13 numeric digits
UEN	Singapore only	9 or 10 alphanumeric characters
USCI	China united social credit code	18 alphanumeric characters
VAT	Austria, Belgium, Bulgaria, Croatia, Czech Republic, Denmark, Estonia, Finland, Faroe Islands, France, Germany, Greece, Hungary, Iceland, Ireland, Isle of Man, Israel, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Republic of Cyprus, Romania, Saudi Arabia, Slovak Republic, Slovenia, South Africa, Spain, Sweden, Switzerland, Thailand, Turkey, Ukraine, United Arab Emirates, United Kingdom	Austria AT + 9 characters in which the first character is always a 'U' Belgium BE + 10 characters. Prefix with zero '0' if the customer provides a 9 digit VAT number Bulgaria BG + 9 or 10 characters Croatia HR + 11 characters Cyprus CY + 9 characters Czech Republic CZ + 8, 9 or 10 characters. Denmark DK + 8 characters Estonia EE + 9 characters Finland FI + 8 characters Faroe Islands FO + 6 characters France FR + 11 characters Germany DE + 9 characters Greece EL + 9 characters Hungary HU + 8 characters Iceland IS + 5 or 6 characters Ireland IE + 8 numeric or alphabetic characters Israel IL + 9 numeric digits Isle of Man GB + 9 or 12 digits; first 2 digits must be 00 Italy IT + 11 characters Latvia LV + 11 characters Lithuania LT + 9 or 12 characters Luxembourg LU + 8 characters Malta MT + 8 characters. Netherlands NL + 12 characters of which the tenth character is always B. Norway NO + 9 digits and the letters + MVA Poland PL + 10 alphanumeric characters Portugal PT + 9 characters Republic of Cyprus CY + 9 characters. The last character must always be a letter. Romania RO + 2 to 10 characters. Saudi Arabia 15 numeric digits Slovak Republic SK + 10 characters Slovenia SI + 8 characters South Africa 10 or 11 digits Spain ES + 9 numeric digits Sweden SE + 12 digits Switzerland CH + 9 digits + MWST (German part), TVA(French part), or IVA(Italian part) Thailand 13 numeric digits Turkey TR + 10 characters Ukraine 9 or 12 digits United Arab Emirates 15 digits United Kingdom GB + 9 digits

Example: BIDPossible values:

businessIdentificationValuestring · min: 1 · max: 32Optional

One of the below configuration must be provided:
- businessIdentificationType and businessIdentificationValue or
- acquirerId and acquirerMerchantId.

The format of merchant business identification value depends on the business identification type.

Example: 12345678

acquirerIdstring · min: 1 · max: 11Optional

One of the below configuration must be provided:
- businessIdentificationType and businessIdentificationValue or
- acquirerId and acquirerMerchantId.

Numeric acquirer identifier.

Pattern: ^([0-9]*$)

acquirerMerchantIdstring · min: 1 · max: 25Optional

One of the below configuration must be provided:
- businessIdentificationType and businessIdentificationValue or
- acquirerId and acquirerMerchantId.

Acquirer merchant identifier.

dunsNumberstring · min: 9 · max: 9Optional

Dun and Bradestreet number.

Example: 568918742

Responses

202

Accepted

No content

400

Bad request - Not Retryable

401

Unauthorized - Not Retryable

404

Not Found - Not Retryable

429

Too Many Requests - Retryable

500

Internal Server Error - Not Retryable

503

Service Unavailable - Retryable

put/merchants/{merchantId}/visa

PUT /tsh-cof/merchants/{merchantId}/visa HTTP/1.1
Host: thales.api.com
authorization: text
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 280

{
  "merchantLegalName": "My Merchant SARL",
  "primaryContactEmail": "jsmith@mymerchant.com",
  "websiteUrl": "http://mymerchant.com",
  "merchantCity": "Paris",
  "merchantCountry": "FR",
  "allowCardUpdateNotification": true,
  "businessIdentificationType": "BID",
  "businessIdentificationValue": "12345678"
}

No content

PreviousHealthcheck NextToken Management

Last updated 18 days ago

Was this helpful?