Add Token Vault to a Gateway Account
POST /v4/marketplace_app/ctv/onboarding
Environment and operation
Use this endpoint contract with the account and environment assigned to your integration. Values in angle brackets are placeholders. This reference does not execute requests. Documented server https://sandbox.nmi.com/api Schema reference: field definitions do not include every behavioral rule. Follow the workflow guidance and account prerequisites for this operation before submitting requests.
Request route
POST /v4/marketplace_app/ctv/onboarding Security scheme Type Credential location Scopes None declared Verify account setup Not inferred Not inferred
Request language templates
Original transport templates derived from this endpoint’s documented method, server, authentication and media type. Replace path/query/credential placeholders with authorized sandbox values. These examples print the raw status and response; they do not infer business success or retry a request. Save one valid request variant from the fields/examples below as request.json. Do not combine mutually exclusive variants. The payload is deliberately not fabricated from schema defaults. Node requires a runtime with fetch; PHP requires cURL. Generated source-based examples have not been executed against provider accounts. curl --request POST \ --url 'https://sandbox.nmi.com/api/v4/marketplace_app/ctv/onboarding' \ --header 'Authorization: <Authorization>' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' import { readFile } from 'node:fs/promises'; const body = await readFile('request.json', 'utf8'); const response = await fetch("https://sandbox.nmi.com/api/v4/marketplace_app/ctv/onboarding", { method: 'POST', headers: { "Authorization": "<Authorization>", "Content-Type": "application/json" }, body }); console.log(response.status, await response.text()); from urllib.request import Request, urlopen from urllib.error import HTTPError from pathlib import Path request = Request('https://sandbox.nmi.com/api/v4/marketplace_app/ctv/onboarding', method='POST', headers={'Authorization': '<Authorization>', 'Content-Type': 'application/json'}, data=Path('request.json').read_bytes()) try: with urlopen(request, timeout=30) as response: print(response.status, response.read().decode()) except HTTPError as error: print(error.code, error.read().decode()) require 'net/http' require 'uri' uri = URI("https://sandbox.nmi.com/api/v4/marketplace_app/ctv/onboarding") request = Net::HTTP::Post.new(uri) request["Authorization"] = "<Authorization>" request["Content-Type"] = "application/json" request.body = File.binread('request.json') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https', read_timeout: 30) { |http| http.request(request) } puts response.code puts response.body <?php $curl = curl_init('https://sandbox.nmi.com/api/v4/marketplace_app/ctv/onboarding'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => ['Authorization: <Authorization>', 'Content-Type: application/json'], CURLOPT_POSTFIELDS => file_get_contents('request.json') ]); $response = curl_exec($curl); if ($response === false) { throw new RuntimeException(curl_error($curl)); } echo curl_getinfo($curl, CURLINFO_HTTP_CODE), PHP_EOL, $response; curl_close($curl);
Path and query parameters
Required flags apply to the parameter itself. Additional limits and enum values appear in the contract below. Parameter Location Required Type Description Authorization header true string Reseller API Key [ { "name": "Authorization", "in": "header", "required": true, "description": "Reseller API Key", "schema": { "type": "string", "default": "" } } ] true
Request body
Use the declared media type: application/json. Required flags below apply within the selected object or variant. Read the workflow notes before choosing a variant. Field Type Required Description Constraints merchantId string yes Merchant gateway ID default: "" applications array yes applications[].serviceId string yes This value will always be "ctv" default: "ctv" applications[].application object yes Information regarding signup for the Customer Token Vault application applications[].application.merchantLegalName string yes Legal business name of the merchant default: "ExampleMerchant LTC" applications[].application.merchantDbaName string yes "Doing Business As" name for the merchant default: "ExampleMerchant" applications[].application.merchantEmail string yes Valid merchant email address default: "example@email.com" applications[].application.merchantCity string yes Merchant’s city that business is located. default: "Chicago" applications[].application.merchantCountryCode string yes Two-letter country code. default: "US" applications[].application.merchantWebsiteUrl string yes Merchant's website url. This must be unique for each merchant gateway. If merchants share a URL, making them unique is required (e.g. https://example.com/2 if a merchant is already using the example.com domain). default: "https://example-site.com" applications[].application.merchantBusinessId object yes Business identification information which is used to identify and sign up merchant for Customer Token Vault applications[].application.merchantBusinessId.ssn string no Social Security Number (United States) example: 123-45-6789 default: "" applications[].application.merchantBusinessId.ein string no Employer Identification Number (Tax ID) (United States) example: 12-3456789 default: "" applications[].application.merchantBusinessId.acquirerId string no (must be used with mid) example: 123456 applications[].application.merchantBusinessId.mid string no merchant identification (must be used acquirerId). example: 123456 applications[].application.merchantBusinessId.abn string no Australian Business Number (Australia). example: 83123456789 default: "" applications[].application.merchantBusinessId.bid string no Business Identification Number. example: BID123456 default: "" applications[].application.merchantBusinessId.bn string no Canadian Business Number (Canada). 123456789RC0001 default: "" applications[].application.merchantBusinessId.brno string no Malaysian Business Registration Number (Malaysia). example: 1234567 default: "" applications[].application.merchantBusinessId.cl string no Commercial License Number (Qatar). example: 12345678 default: "" applications[].application.merchantBusinessId.cln string no Commercial License Number (Kuwait). example: 987654 default: "" applications[].application.merchantBusinessId.corporateNumber string no Corporate Number (Japan). example: 1234567890123 default: "" applications[].application.merchantBusinessId.cnpj string no (Brazil). example: 12.345.678/0001-95 default: "" applications[].application.merchantBusinessId.cr string no Company Registration Number (Saudi Arabia). example: 1234567890 default: "" applications[].application.merchantBusinessId.cuit string no (Argentina). example: 20-12345678-9 default: "" applications[].application.merchantBusinessId.edrpou string no Unified State Register of Enterprises (Ukraine). example: 12345678 default: "" applications[].application.merchantBusinessId.hkbr string no Hong Kong Business Registration (Hong Kong). example: 12345678-000-01 default: "" applications[].application.merchantBusinessId.nationalId string no National Taxpayer ID (Dominican Republic). example: 001-1234567-8 default: "" applications[].application.merchantBusinessId.nzbn string no New Zealand Business Number (New Zealand). example: 9429031234567 default: "" applications[].application.merchantBusinessId.pan string no Permanent Account Number (India). example: ABCDE1234F default: "" applications[].application.merchantBusinessId.rfc string no Business ID (Mexico). example: ABC123456T89 default: "" applications[].application.merchantBusinessId.rnc string no National Taxpayer Registry (Dominican Republic). example: 101123456 default: "" applications[].application.merchantBusinessId.ruc string no Single Taxpayer Registry (Peru). example: 20123456789 default: "" applications[].application.merchantBusinessId.rut string no Single Tax Role (Chile / Colombia). example: 12.345.678-9 default: "" applications[].application.merchantBusinessId.sin string no Social Insurance Number (Canada). example: 123-456-789 default: "" applications[].application.merchantBusinessId.uen string no Unique Entity Number (Singapore). example: 201234567W default: "" applications[].application.merchantBusinessId.vat string no Value-Added Tax Number (EU & various). example: DE123456789 default: "" applications[].application.paymentAppId string yes Unique v4 UUID for this app instance. You can generate this how you want, but each must be unique to all applications across the platform. Duplicates will result in boarding errors. example: 5487317d-0a22-4d14-9d70-774331f62004 default: "" applications[].application.paymentAppLegalName string yes Typically the same as the "merchantLegalName" value. default: "ExampleMerchant LTC" applications[].application.paymentAppDisplayName string yes The app that will be using tokens. Something generic like "webApp" will work. default: "webApp" { "content": { "application/json": { "schema": { "properties": { "merchantId": { "type": "string", "description": "Merchant gateway ID", "default": "" }, "applications": { "type": "array", "items": { "properties": { "serviceId": { "type": "string", "default": "ctv", "description": "This value will always be \"ctv\"" }, "application": { "type": "object", "properties": { "merchantLegalName": { "type": "string", "description": "Legal business name of the merchant", "default": "ExampleMerchant LTC" }, "merchantDbaName": { "type": "string", "description": "\"Doing Business As\" name for the merchant", "default": "ExampleMerchant" }, "merchantEmail": { "type": "string", "description": "Valid merchant email address", "default": "example@email.com" }, "merchantCity": { "type": "string", "description": "Merchant\u2019s city that business is located.", "default": "Chicago" }, "merchantCountryCode": { "type": "string", "description": "Two-letter country code.", "default": "US" }, "merchantWebsiteUrl": { "type": "string", "default": "https://example-site.com", "description": "Merchant's website url. This must be unique for each merchant gateway. If merchants share a URL, making them unique is required (e.g. https://example.com/2 if a merchant is already using the example.com domain)." }, "merchantBusinessId": { "type": "object", "properties": { "ssn": { "type": "string", "description": "Social Security Number (United States) example: 123-45-6789", "default": "" }, "ein": { "type": "string", "description": "Employer Identification Number (Tax ID) (United States) example: 12-3456789", "default": "" }, "acquirerId": { "type": "string", "description": "(must be used with mid) example: 123456" }, "mid": { "type": "string", "description": "merchant identification (must be used acquirerId). example: 123456" }, "abn": { "type": "string", "description": "Australian Business Number (Australia). example: 83123456789", "default": "" }, "bid": { "type": "string", "default": "", "description": "Business Identification Number. example: BID123456" }, "bn": { "type": "string", "description": "Canadian Business Number (Canada). 123456789RC0001", "default": "" }, "brno": { "type": "string", "description": "Malaysian Business Registration Number (Malaysia). example: 1234567", "default": "" }, "cl": { "type": "string", "description": "Commercial License Number (Qatar). example: 12345678", "default": "" }, "cln": { "type": "string", "description": "Commercial License Number (Kuwait). example: 987654", "default": "" }, "corporateNumber": { "type": "string", "description": "Corporate Number (Japan). example: 1234567890123", "default": "" }, "cnpj": { "type": "string", "description": "(Brazil). example: 12.345.678/0001-95", "default": "" }, "cr": { "type": "string", "description": "Company Registration Number (Saudi Arabia). example: 1234567890", "default": "" }, "cuit": { "type": "string", "description": "(Argentina). example: 20-12345678-9", "default": "" }, "edrpou": { "type": "string", "description": "Unified State Register of Enterprises (Ukraine). example: 12345678", "default": "" }, "hkbr": { "type": "string", "description": "Hong Kong Business Registration (Hong Kong). example: 12345678-000-01", "default": "" }, "nationalId": { "type": "string", "description": "National Taxpayer ID (Dominican Republic). example: 001-1234567-8", "default": "" }, "nzbn": { "type": "string", "description": "New Zealand Business Number (New Zealand). example: 9429031234567", "default": "" }, "pan": { "type": "string", "description": "Permanent Account Number (India). example: ABCDE1234F", "default": "" }, "rfc": { "type": "string", "description": "Business ID (Mexico). example: ABC123456T89", "default": "" }, "rnc": { "type": "string", "description": "National Taxpayer Registry (Dominican Republic). example: 101123456", "default": "" }, "ruc": { "type": "string", "description": "Single Taxpayer Registry (Peru). example: 20123456789", "default": "" }, "rut": { "type": "string", "description": "Single Tax Role (Chile / Colombia). example: 12.345.678-9", "default": "" }, "sin": { "type": "string", "description": "Social Insurance Number (Canada). example: 123-456-789", "default": "" }, "uen": { "type": "string", "description": "Unique Entity Number (Singapore). example: 201234567W", "default": "" }, "vat": { "type": "string", "description": "Value-Added Tax Number (EU & various). example: DE123456789", "default": "" } }, "description": "Business identification information which is used to identify and sign up merchant for Customer Token Vault" }, "paymentAppId": { "type": "string", "description": "Unique v4 UUID for this app instance. You can generate this how you want, but each must be unique to all applications across the platform. Duplicates will result in boarding errors. example: 5487317d-0a22-4d14-9d70-774331f62004", "default": "" }, "paymentAppLegalName": { "type": "string", "description": "Typically the same as the \"merchantLegalName\" value.", "default": "ExampleMerchant LTC" }, "paymentAppDisplayName": { "type": "string", "description": "The app that will be using tokens. Something generic like \"webApp\" will work.", "default": "webApp" } }, "required": [ "merchantLegalName", "merchantDbaName", "merchantEmail", "merchantCity", "merchantCountryCode", "merchantWebsiteUrl", "merchantBusinessId", "paymentAppId", "paymentAppLegalName", "paymentAppDisplayName" ], "description": "Information regarding signup for the Customer Token Vault application" } }, "type": "object", "required": [ "serviceId", "application" ] } } }, "type": "object", "required": [ "applications", "merchantId" ] } } } } true
Responses
Match the HTTP status to its response schema below. For financial operations, also inspect the payment outcome before updating your order or retrying. HTTP status Media type Meaning 200 application/json { "200": { "description": "", "content": { "application/json": { "examples": { "Example Successful Onboard": { "summary": "Example Successful Onboard", "value": { "visa": { "requestStatus": "completed", "requestStatusCode": "ok", "onboardStatus": "inProgress", "onboardId": "428f1794-b474-4e63-8698-da28ca41f724" }, "mastercard": { "requestStatus": "completed", "requestStatusCode": "ok", "onboardStatus": "inProgress", "onboardId": "b8740d75-7ca5-40d1-9cf9-eb921c8ed2aa" } } } } } } } } true
Referenced schema definitions
References beginning with #/components resolve to these definitions. These are field contracts, not example payment values. Use the applicable variant, required fields and constraints. {} true
Integration checks
Validate the request against its selected schema before submission. Keep secrets outside browser code. Test permitted and denied account access, validation failures and interrupted responses in the sandbox. Account-management or messaging operations require the corresponding partner access and intended recipient context.