Merchants

Create a new merchant

post/api/v1/merchants

Request body

partner_idstring uuid

Partner ID. Defaults to the logged-in partner if not provided. Required for admin tokens.

brand_namestring required

The brand name of the merchant

uristring required

The URI of the merchant's website (protocol optional, will be normalized)

category_codestring required

The merchant category code

countrystring

The country of the merchant

Example request

{
  "partner_id": "550e8400-e29b-41d4-a716-446655440000",
  "brand_name": "Example Brand",
  "uri": "example-merchant.com",
  "category_code": "4816",
  "country": "GB",
  "account_owner": {
    "full_name": "John Doe",
    "email": "john.doe@example.com",
    "phone_number": "44;7395236209",
    "role": "Owner"
  }
}

Response

Created

successboolean required

Indicates if the request was successful

Example response

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "brand_name": "Example Brand",
    "uri": "https://example-merchant.com",
    "category_code": "4816",
    "country": "GB",
    "settlement_currency": "EUR",
    "multi_account_setting": true,
    "refund_retention_rate": "0.0500",
    "client_id": "merchant_123",
    "has_client_secret": true,
    "account_owners": []
  }
}

Changes

Changed in 3 of the 8 revisions of this API.2111

Jun 16, 2026b372e7d5563d1110See the full diff
- ▲
  the error/code response's property type/format changed from string/ to / for status 400
  response-property-type-changed
- ●
  removed the optional property error/errors from the response with the 400 status
  response-optional-property-removed
- ○
  added the new optional request property country
  new-optional-request-property
- ○
  added the new optional request property partner_id
  new-optional-request-property
- ○
  the request property account_owner became optional
  request-property-became-optional
- ○
  the uri request property type/format was generalized from string/uri to string/
  request-property-type-generalized
- ○
  added the optional property data/country to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property data/settlement_currency to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property error/metadata to the response with the 400 status
  response-optional-property-added
- ○
  added subschema #1 subschema #2 to the error/code response property allOf list for the response status 400
  response-property-all-of-added
- ○
  added the required property data/has_client_secret to the response with the 201 status
  response-required-property-added
- ○
  added the required property data/refund_retention_rate to the response with the 201 status
  response-required-property-added
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Nov 3, 20256637b341d86d1See the full diff
- ○
  endpoint added
  endpoint-added
This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Nov 2, 2025919eb7a392aa1See the full diff
- ▲
  api path removed without deprecation
  api-path-removed-without-deprecation
This revision also has 367 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history