--- title: "Create a Merchant" method: POST path: "/payments/merchants" tags: ["Payments", "Merchants"] --- # Create a Merchant `POST /payments/merchants` ## Request - Base URL: `https://api.evervault.com` - URL: `https://api.evervault.com/payments/merchants` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) Enrolls a Merchant with Card Networks. In rare cases it can take up to 48 hours to enroll a merchant with each of the card networks. If you are still unable to provision network tokens after this period, please contact support@evervault.com ## Request body - object - `name` string, required: **Must be globally unique. We recommend adding a suffix, for example `Acme 123456`. Onboarding may fail otherwise!** The official name of the Merchant as recognized in transactions and communications. This name is used for display purposes and may be the company's trade name or a derived nickname. - `shortName` string: A shorter version of the Merchant's name. Optional. When creating a 3D Secure session that references this Merchant by ID, `shortName` is used in place of `name` if `name` exceeds the 40-character limit imposed by the 3D Secure specification. - `website` string, required: The official website URL of the Merchant. The domain must use a valid IANA top-level domain. See https://data.iana.org/TLD/tlds-alpha-by-domain.txt - `categoryCode` string, required: The 4-digit Merchant Category Code (MCC). - `business` object, required: The business details of the Merchant. - `legalName` string, required: The legal name under which the Merchant's business is registered. - `address` Address, required - `line1` string, required: The first line of the address. - `line2` string: The second line of the address. - `city` string, required: The city where the address is located. - `state` string, iso-3166-2-subdivision: The state or province code. Required when `country` is `us`, `ca`, or `au`. - `postalCode` string, required: The postal code of the address. - `country` string, iso-3166-1-alpha-2, required: The country where the address is located. - `applePay` object: The Merchant's Apple Pay configuration. - `domains` string[], required: The domains the Merchant wants registered with Apple Pay. Only the domain name is required, without the protocol or path. For example, `example.com` is a valid domain, but `https://example.com` is not. - `preChargebackAlerts` MerchantPreChargebackAlertsConfig: The enrolment fields shared by the pre-chargeback alerts create and update configs: the chargeback merchant type, and the Ethoca and Verifi RDR enrolment details. - `merchantType` string: The chargeback merchant type. When omitted, a default is applied. - `ethocaAlert` object: The Merchant's Ethoca alert enrolment configuration. - `descriptors` object[], required: The billing descriptors to enroll for Ethoca alerts. Each `descriptor` must be 1–100 printable ASCII characters. - `descriptor` string, required: The billing descriptor to match against. Must contain printable ASCII characters only. - `matchType` 'STARTS_WITH' | 'EXACT_MATCH', required: How the descriptor is matched against transactions. - `verifiRdr` object: The Merchant's Verifi RDR enrolment configuration. Provide either `bin` and `caid` together, or at least one ARN in `arns`. - `bin` string: The Bank Identification Number (BIN) associated with the Merchant. Must be exactly 6 digits. - `caid` string: The Card Acceptor ID (CAID) associated with the Merchant. Must be exactly 15 alphanumeric characters. - `arns` string[]: The Acquirer Reference Numbers (ARNs) to enroll. - `contact` MerchantContact: The business contact details of the Merchant. Visa needs `phoneNumber` and `name` to enroll the Merchant for Network Retry Signals. - `phoneNumber` string: The business phone number of the Merchant. Up to 20 characters, with at least seven digits. It can contain a leading `+`, spaces, dots, dashes, and parentheses. - `email` string, email: The email address of the business contact. - `name` object: The name of the business contact. Both `firstName` and `lastName` are required when `name` is sent. - `firstName` string, required: The first name of the business contact. - `lastName` string, required: The last name of the business contact. - `externalCustomerReference` string: An optional reference of your choice, such as a correlation ID, that is attached to the request. The reference will be visible in your logs. Must be between 1 and 255 characters. ## Response `201` Returns a Merchant object. - Merchant - `id` string, required: A unique identifier assigned to each Merchant. - `name` string, required: **Must be globally unique. We recommend adding a suffix, for example `Acme 123456`.** The official name of the Merchant as recognized in transactions and communications. This name is used for display purposes and may be the company's trade name or a derived nickname. - `shortName` string: A shorter version of the Merchant's name. When creating a 3D Secure session that references this Merchant by ID, `shortName` is used in place of `name` if `name` exceeds the 40-character limit imposed by the 3D Secure specification. - `website` string, required: The official website URL of the Merchant. The domain must use a valid IANA top-level domain. See https://data.iana.org/TLD/tlds-alpha-by-domain.txt - `business` object, required: The business details of the Merchant. - `legalName` string, required: The legal name under which the Merchant's business is registered. - `address` Address, required - `line1` string, required: The first line of the address. - `line2` string: The second line of the address. - `city` string, required: The city where the address is located. - `state` string, iso-3166-2-subdivision: The state or province code. Required when `country` is `us`, `ca`, or `au`. - `postalCode` string, required: The postal code of the address. - `country` string, iso-3166-1-alpha-2, required: The country where the address is located. - `categoryCode` string, required: The 4-digit Merchant Category Code (MCC). - `networkTokens` MerchantNetworkTokenStatus, required - `enrolment` object[], required: An array detailing the Merchant's enrollment status for network token issuance across different card brands. - `cardBrand` 'visa' | 'mastercard' | 'american-express' | 'discover' | 'diners-club' | 'jcb' | 'unionpay', required: The card brand associated with the payment card. - `tokenRequestorIdentifier` string, nullable: The unique Token Requestor Identifier (TRID) associated with the Merchant for the specific card brand. This identifier is used when creating Network Tokens for the Merchant. - `status` 'active' | 'inactive', required: The current stage of the Merchant's enrolment process for network token issuance with the specified card brand. - `applePay` MerchantApplePay, required - `domains` object[], required: The domains the Merchant has enrolled with Apple Pay and the status of the enrollment. - `merchantUuid` string, required: The ID of the Merchant the domain is enrolled for. - `domain` string, required: The top-level domain name of the Merchant's website. - `status` 'active' | 'pending' | 'failed', required: The current status of the Merchant's Apple Pay enrollment for the specified domain. `active` means the Merchant is fully enrolled and can accept Apple Pay payments on the domain. - `preChargebackAlerts` MerchantPreChargebackAlerts: The Merchant's pre-chargeback alert enrolments, returned on Merchant responses when pre-chargeback alerts have been configured. - `enrolments` object[], required: The merchant's enrolments with Ethoca and/or Verifi RDR. - `type` 'ETHOCA_ALERT' | 'VERIFI_RDR', required: The enrolment network. - `status` 'PENDING' | 'ACTIVE' | 'ACTION_REQUIRED' | 'CANCELLED', required: The enrolment status. It can take 2–10 days to move from `PENDING` to `ACTIVE`. - `ethocaAlert` object: Ethoca alert enrolment details. Present when `type` is `ETHOCA_ALERT`. - `descriptors` object[]: The billing descriptors enrolled for Ethoca alerts. - `descriptor` string, required: The billing descriptor matched against transactions. - `matchType` 'STARTS_WITH' | 'EXACT_MATCH', required: How the descriptor is matched against transactions. - `status` string: The descriptor enrolment status. - `verifiRdr` object: Verifi RDR enrolment details. Present when `type` is `VERIFI_RDR`. - `bin` string: The Bank Identification Number (BIN) associated with the Merchant. Must be exactly 6 digits. - `caid` string: The Card Acceptor ID (CAID) associated with the Merchant. Must be exactly 15 alphanumeric characters. - `arns` string[]: The Acquirer Reference Numbers (ARNs) enrolled. - `contact` MerchantContact: The business contact details of the Merchant. Visa needs `phoneNumber` and `name` to enroll the Merchant for Network Retry Signals. - `phoneNumber` string: The business phone number of the Merchant. Up to 20 characters, with at least seven digits. It can contain a leading `+`, spaces, dots, dashes, and parentheses. - `email` string, email: The email address of the business contact. - `name` object: The name of the business contact. Both `firstName` and `lastName` are required when `name` is sent. - `firstName` string, required: The first name of the business contact. - `lastName` string, required: The last name of the business contact. - `createdAt` integer, required: The exact time, in epoch milliseconds, when this Merchant was created. - `updatedAt` integer: The exact time, in epoch milliseconds, when this Merchant was last updated. ## Changes - **2026-11-06** `8d0ca833fa04`: 8 breaking, 6 warning, 26 info - the request property `applePay/domains` became required - added the pattern `^(?:https?://[a-z0-9.-]+\.[a-z]{2,63}|www\d{0,3}\.[a-z0-9.-]+\.[a-z]{2,63}|[a-z0-9.-]+\.[a-z]{2,63}/)(?:(?:[^\s()<>:]+|\((?:[^\s()<>:]+|\([^\s()<>:]+\))*\))*(?:\((?:[^\s()<>:]+|\([^\s()<>:]+\))*\)|[^\s`!()\[\]{};:'".,<>?«»“”‘’:]))?$` to the request property `website` - added the pattern `^[0-9a-zA-Z ]*$` to the request property `business/address/postalCode` - added the pattern `^[0-9a-zA-Z _\-¡-￿]+$` to the request property `business/address/city` - …36 more - **2026-04-17** `5e1eb58d42d5`: 2 breaking, 2 info - the `business/address/country` request property format changed from no format to `iso-3166-1-alpha-2` - the `business/address/state` request property format changed from no format to `iso-3166-2-subdivision` - removed the pattern `^[a-z]{2}$` from the request property `business/address/country` - the `business/address/country` response's property pattern `^[a-z]{2}$` was removed for the status `201` - …earlier changes not shown [Operation history](https://skmtc.dev/evervault/apis/evervault-api/changes/payments/merchants/post.md) --- [API](https://skmtc.dev/evervault/apis/evervault-api.md) - [All operations](https://skmtc.dev/evervault/apis/evervault-api/llms.txt) - [OpenAPI document](https://skmtc.dev/evervault/apis/evervault-api/revisions/8d0ca833fa04?raw)