> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/merchant-tokenization/ja/bakkuendo/apis/server-api/merchant-onboarding.md). # Merchant Onboarding ## POST /merchants > Create a merchant.\ > \ > The API is synchronous and the Scheme TSP is not involved. ```json {"openapi":"3.1.1","info":{"title":"Thales ETP Server API","version":"1.78"},"tags":[{"name":"Merchant Onboarding"}],"servers":[{"url":"https://thales.api.com/tsh-cof"}],"paths":{"/merchants":{"post":{"description":"Create a merchant.\n\nThe API is synchronous and the Scheme TSP is not involved.","operationId":"createMerchant","parameters":[{"$ref":"#/components/parameters/authorization"},{"$ref":"#/components/parameters/xCorrelationId"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["merchantId","creationTimestamp"],"properties":{"merchantId":{"$ref":"#/components/schemas/merchantId"},"creationTimestamp":{"$ref":"#/components/schemas/creationTimestamp"}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Merchant Onboarding"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["merchantName"],"properties":{"merchantName":{"$ref":"#/components/schemas/merchantName"}}}}}}}}},"components":{"parameters":{"authorization":{"schema":{"type":"string","maxLength":512,"minLength":1},"in":"header","description":"Technical identifier pre-defined at on-boarding that identifies the API\nconsumer.\nFormat shall be the string 'APIKEY' followed by a space and the\napi key value.\n
Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b\n","name":"authorization","required":true},"xCorrelationId":{"schema":{"type":"string","maxLength":36,"minLength":1},"in":"header","description":"Technical identifier used for troubleshooting. \n
It helps on customer support when needed. \n
Each API request must be identified with a unique correlation Id.\n
It correlates the response and the request and eventually a notification if any. ","name":"x-correlation-id","required":true}},"schemas":{"merchantId":{"type":"string","description":"Identifier of the merchant provided by Thales at on-boarding.","minLength":1,"maxLength":128},"creationTimestamp":{"type":"string","maxLength":64,"description":"Token creation timestamp compliant with ISO 8601."},"merchantName":{"type":"string","description":"An unique merchant name that is end user friendly.","minLength":1,"maxLength":60,"pattern":"^[A-Za-z0-9-_. ]+$"}},"responses":{"400":{"description":"Bad request - Not Retryable"},"401":{"description":"Unauthorized - Not Retryable"},"429":{"description":"Too Many Requests - Retryable"},"500":{"description":"Internal Server Error - Not Retryable"},"503":{"description":"Service Unavailable - Retryable"}}}} ``` ## Update Merchant Mastercard (S-COF) > Update the merchant setup for Mastercard Secure Card-On-File program. ```json {"openapi":"3.1.1","info":{"title":"Thales ETP Server API","version":"1.78"},"tags":[{"name":"Merchant Onboarding"}],"servers":[{"url":"https://thales.api.com/tsh-cof"}],"paths":{"/merchants/{merchantId}/mastercard/secure-cof":{"put":{"description":"Update the merchant setup for Mastercard Secure Card-On-File program.","operationId":"updateMerchantMastercardSecureCOF","parameters":[{"$ref":"#/components/parameters/merchantId"},{"$ref":"#/components/parameters/authorization"},{"$ref":"#/components/parameters/xCorrelationId"}],"responses":{"202":{"$ref":"#/components/responses/202"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Merchant Onboarding"],"summary":"Update Merchant Mastercard (S-COF)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["merchantLegalName","websiteUrl","merchantCity","merchantCountry"],"properties":{"merchantLegalName":{"$ref":"#/components/schemas/merchantLegalName"},"websiteUrl":{"$ref":"#/components/schemas/websiteUrl"},"merchantCity":{"$ref":"#/components/schemas/merchantCity"},"merchantCountry":{"$ref":"#/components/schemas/merchantCountry"},"mcServiceId":{"$ref":"#/components/schemas/mcServiceId"},"merchantCategory":{"$ref":"#/components/schemas/merchantCategory"},"acquirerId":{"$ref":"#/components/schemas/acquirerIdMastercard"},"locale":{"$ref":"#/components/schemas/locale"}}}}}}}}},"components":{"parameters":{"merchantId":{"schema":{"type":"string","maxLength":128,"minLength":1},"in":"path","description":"The unique merchant identifier.","name":"merchantId","required":true},"authorization":{"schema":{"type":"string","maxLength":512,"minLength":1},"in":"header","description":"Technical identifier pre-defined at on-boarding that identifies the API\nconsumer.\nFormat shall be the string 'APIKEY' followed by a space and the\napi key value.\n
Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b\n","name":"authorization","required":true},"xCorrelationId":{"schema":{"type":"string","maxLength":36,"minLength":1},"in":"header","description":"Technical identifier used for troubleshooting. \n
It helps on customer support when needed. \n
Each API request must be identified with a unique correlation Id.\n
It correlates the response and the request and eventually a notification if any. ","name":"x-correlation-id","required":true}},"responses":{"202":{"description":"Accepted"},"400":{"description":"Bad request - Not Retryable"},"401":{"description":"Unauthorized - Not Retryable"},"404":{"description":"Not Found - Not Retryable"},"429":{"description":"Too Many Requests - Retryable"},"500":{"description":"Internal Server Error - Not Retryable"},"503":{"description":"Service Unavailable - Retryable"}},"schemas":{"merchantLegalName":{"type":"string","minLength":1,"maxLength":60,"description":"Legal name of the merchant.","pattern":"^[A-Za-z0-9-_. ]+$"},"websiteUrl":{"type":"string","minLength":1,"maxLength":100,"description":"Merchant website URL.","pattern":"^[A-Za-z0-9-_.:/]+$"},"merchantCity":{"type":"string","minLength":1,"maxLength":100,"description":"City of the merchant address.","pattern":"^[A-Za-z0-9-_. ]+$"},"merchantCountry":{"type":"string","minLength":2,"maxLength":2,"description":"Merchant country in ISO-3166-1 alpha-2 two-letter country code."},"mcServiceId":{"type":"string","maxLength":256,"description":"Reserved for future use.
A unique identifier assigned by Mastercard for which tokens are created uniquely for the entity onboarded."},"merchantCategory":{"type":"string","minLength":1,"maxLength":256,"description":"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'. "},"acquirerIdMastercard":{"type":"string","pattern":"^([0-9a-zA-Z]*$)","description":"Acquiring institution identification code","minLength":1,"maxLength":11},"locale":{"type":"string","description":"Locale identifier following BCP 47 (e.g., en-US, es-MX)","minLength":1,"maxLength":10}}}} ``` ## Update Merchant Visa > Update the merchant setup for VISA. ```json {"openapi":"3.1.1","info":{"title":"Thales ETP Server API","version":"1.78"},"tags":[{"name":"Merchant Onboarding"}],"servers":[{"url":"https://thales.api.com/tsh-cof"}],"paths":{"/merchants/{merchantId}/visa":{"put":{"description":"Update the merchant setup for VISA.","operationId":"updateMerchantVisa","parameters":[{"$ref":"#/components/parameters/merchantId"},{"$ref":"#/components/parameters/authorization"},{"$ref":"#/components/parameters/xCorrelationId"}],"responses":{"202":{"$ref":"#/components/responses/202"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Merchant Onboarding"],"summary":"Update Merchant Visa","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["merchantLegalName","primaryContactEmail","websiteUrl","merchantCity","merchantCountry"],"properties":{"merchantLegalName":{"$ref":"#/components/schemas/merchantLegalName"},"primaryContactEmail":{"$ref":"#/components/schemas/primaryContactEmail"},"websiteUrl":{"$ref":"#/components/schemas/websiteUrl"},"merchantCity":{"$ref":"#/components/schemas/merchantCity"},"merchantCountry":{"$ref":"#/components/schemas/merchantCountry"},"allowCardUpdateNotification":{"$ref":"#/components/schemas/allowCardUpdateNotification"},"businessIdentificationType":{"$ref":"#/components/schemas/businessIdentificationType"},"businessIdentificationValue":{"$ref":"#/components/schemas/businessIdentificationValue"},"acquirerId":{"$ref":"#/components/schemas/acquirerId"},"acquirerMerchantId":{"$ref":"#/components/schemas/acquirerMerchantId"},"dunsNumber":{"$ref":"#/components/schemas/dunsNumber"},"tokenRequestorServiceTypes":{"$ref":"#/components/schemas/tokenRequestorServiceTypes"}}}}}}}}},"components":{"parameters":{"merchantId":{"schema":{"type":"string","maxLength":128,"minLength":1},"in":"path","description":"The unique merchant identifier.","name":"merchantId","required":true},"authorization":{"schema":{"type":"string","maxLength":512,"minLength":1},"in":"header","description":"Technical identifier pre-defined at on-boarding that identifies the API\nconsumer.\nFormat shall be the string 'APIKEY' followed by a space and the\napi key value.\n
Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b\n","name":"authorization","required":true},"xCorrelationId":{"schema":{"type":"string","maxLength":36,"minLength":1},"in":"header","description":"Technical identifier used for troubleshooting. \n
It helps on customer support when needed. \n
Each API request must be identified with a unique correlation Id.\n
It correlates the response and the request and eventually a notification if any. ","name":"x-correlation-id","required":true}},"responses":{"202":{"description":"Accepted"},"400":{"description":"Bad request - Not Retryable"},"401":{"description":"Unauthorized - Not Retryable"},"404":{"description":"Not Found - Not Retryable"},"429":{"description":"Too Many Requests - Retryable"},"500":{"description":"Internal Server Error - Not Retryable"},"503":{"description":"Service Unavailable - Retryable"}},"schemas":{"merchantLegalName":{"type":"string","minLength":1,"maxLength":60,"description":"Legal name of the merchant.","pattern":"^[A-Za-z0-9-_. ]+$"},"primaryContactEmail":{"type":"string","minLength":1,"maxLength":100,"description":"Email address of the merchant primary contact.","pattern":"^[A-Za-z0-9-_.@]+$"},"websiteUrl":{"type":"string","minLength":1,"maxLength":100,"description":"Merchant website URL.","pattern":"^[A-Za-z0-9-_.:/]+$"},"merchantCity":{"type":"string","minLength":1,"maxLength":100,"description":"City of the merchant address.","pattern":"^[A-Za-z0-9-_. ]+$"},"merchantCountry":{"type":"string","minLength":2,"maxLength":2,"description":"Merchant country in ISO-3166-1 alpha-2 two-letter country code."},"allowCardUpdateNotification":{"type":"boolean","description":"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.
\nWhen allowCardUpdateNotification = false the token is no more valid after the card renewal. No Token Update notification is sent.","title":""},"businessIdentificationType":{"type":"string","maxLength":12,"description":"One of the below configuration must be provided:
- businessIdentificationType and businessIdentificationValue or
- acquirerId and acquirerMerchantId.

Merchant business identification type.\n\n|BusinessIdentificationType|Description|Format|\n|-------|-------|-------|\n|ABN|Australian business number|11 numeric digits|\n|ACN|Australian company number|9 numeric digits|\n|BID|VISA business identification number; all countries. You must contact your Visa representative before using BID |8 numeric digits|\n|BIN|Kazakhstan business identification number|12 numeric digits|\n|BIR|Philippines certificate of registration|12 numeric digits; hyphen-separated|\n|BN|Canadian business number|9 numeric digits|\n|BRN|South Korea business registration number|10 numeric digits; hyphen-separated|\n|BRNO|Malaysia only.|Up to 10 numeric digits followed by a hyphen and a single character or 12 numeric digits|\n|CL|Commercial License Number Qatar|4-6 numeric digits|\n|CLN|Company License Number Kuwait|5-7 numeric digits|\n|CORPORATE_NUMBER|Japan corporate number|13 numeric digits; leading digit is a non-zero check digit for the following 12 digits|\n|CNPJ|Brazil only.|14 alphanumeric characters, identified by n in the example, and punctuation characters (period, slash, and hyphen)|\n|CR|Company Registration Number Saudi Arabia.|10-12 numeric digits|\n|CUIT|Argentina only.|11 numeric digits|\n|EDRPOU|Ukraine. \tUkrainian corporations|8 numeric digits and 10 numeric digits for Ukrainian individual entrepeneurs|\n|EIN|US Federal tax ID (US only).|9 numeric digits|\n|HKBR|Hong Kong only.|11 numeric digits and a hyphen|\n|INI|Andorran General Indirect Tax.|8 alphanumeric characters; the first and last characters must be alphabetic.|\n|NATIONAL_ID|Dominican Republic (DO). Cedula de Identidad (Merchant Owner ID)|DO + 11 digits| \n|NIB|Indonesia business identification number|13 numeric digits|\n|NID|South Africa national identification number|13 numeric digits|\n|NZBN|New Zealand business number.|13 numeric digits|\n|PAN|Indian business identification number|10 alphanumeric characters|\n|PAN|Belarus payer account number|9 numeric digits|\n|RFC|Mexico only.|12 alphanumeric characters for corporations and 13 alphanumeric characters for individuals|\n|RNC|Dominican Republic (DO). Registro Nacional de Contribuyentes (National Contributors Number)|DO + 9 digits|\n|RUC|Peru only.|11 numeric digits|\n|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|\n|SIN|Canadian social insurance number|9 numeric digits|\n|SSN|US social security number (US only)|9 numeric digits|\n|TC|Vietnam tax code|10 or 13 numeric digits|\n|UEN|Singapore only|9 or 10 alphanumeric characters|\n|USCI|China united social credit code|18 alphanumeric characters|\n|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|","enum":["ABN","ACN","BID","BIN","BIR","BN","BRN","BRNO","CL","CLN","CORPORATE_NUMBER","CNPJ","CR","CUIT","EDRPOU","EIN","HKBR","INI","NATIONAL_ID","NIB","NID","NZBN","PAN","RFC","RNC","RUC","RUT","SIN","SSN","TC","UEN","USCI","VAT"]},"businessIdentificationValue":{"type":"string","minLength":1,"maxLength":32,"description":"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."},"acquirerId":{"type":"string","pattern":"^([0-9]*$)","description":"One of the below configuration must be provided:
    - businessIdentificationType and businessIdentificationValue or
    - acquirerId and acquirerMerchantId.

    Numeric acquirer identifier.","minLength":1,"maxLength":11},"acquirerMerchantId":{"type":"string","description":"One of the below configuration must be provided:
    - businessIdentificationType and businessIdentificationValue or
    - acquirerId and acquirerMerchantId.

    Acquirer merchant identifier.","minLength":1,"maxLength":25},"dunsNumber":{"type":"string","minLength":9,"maxLength":9,"description":"Dun and Bradestreet number."},"tokenRequestorServiceTypes":{"type":"array","description":"The list of token requestor service types.","maxItems":2,"minItems":1,"items":{"type":"string","maxLength":20,"enum":["PURCHASE","VISA_DIRECT"]},"uniqueItems":true}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.payments.thalescloud.io/merchant-tokenization/ja/bakkuendo/apis/server-api/merchant-onboarding.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.