---
title: "Self-service merchant registration for users with global:user role"
method: POST
path: "/api/v1/merchants/register"
tags: ["Merchants"]
---

# Self-service merchant registration for users with global:user role

`POST /api/v1/merchants/register`

Self-service merchant registration for users with global:user role

## Request body

- MerchantRegistrationInput — Self-service merchant registration input
  - `brand_name` string, required — The brand name of the merchant
  - `uri` string, required — The URI of the merchant's website (protocol optional, will be normalized)
  - `category_code` string, required — The merchant category code (MCC)
  - `country` string — The country of the merchant
  - `clientEvidence` object, required
    - `checkout_page_version` string — APP_COMMIT_SHA the page was built from
    - `timezone` string — Browser IANA timezone
    - `fingerprint` string — FingerprintJS visitor id if available
    - `consented_agreements` object[], required — One entry per required consent kind for the current acceptance
      - `kind` string, required — AgreementKind literal
      - `agreement_id` string, uuid, required
    - `checkbox_language` object[], required — Rendered text of each checkbox the user ticked
      - `checkbox_id` string, required
      - `rendered_text` string, required
      - `covers_kinds` string[], required

## Response `201`

Created

- MerchantRegistrationResponse
  - `success` boolean, required — Indicates if the request was successful
  - `data` object, required
    - `merchant` object, required — Merchant information
      - `id` string, uuid, required — The unique identifier of the merchant
      - `brand_name` string, required — The brand name of the merchant
      - `uri` string, uri, required — The URI of the merchant's website
      - `category_code` string, required — The merchant category code
      - `activation_status` union, required — The activation status of the merchant
        - 'active'
        - 'inactive'
      - `mode` union, required — The mode of the merchant
        - 'sandbox'
        - 'live'
      - `country` string — The country of the merchant
      - `settlement_currency` string, nullable — The merchant's effective billing/settlement currency, derived from their settlement bank account (with a country fallback). Null when it can't be resolved. Populated by GET /merchants/:id only; absent from list responses.
      - `multi_account_setting` boolean, required — The multi-account setting of the merchant
      - `refund_retention_rate` string, nullable, required — The refund retention rate as a decimal (e.g. "0.0500" for 5%)
      - `client_id` string, required — The client ID of the merchant
      - `has_client_secret` boolean, required — Whether a client secret is set for this merchant
      - `account_owners` object[] — The account owners associated with this merchant
        - `id` string, uuid, required — The unique identifier of the account owner
        - `full_name` string, required — The full name of the account owner
        - `email` string, email, required — The email address of the account owner
        - `phone_number` string — The phone number in format: country_code;number (e.g., 44;7395236209)
        - `role` string — The role of the account owner within the organization
        - `is_primary` boolean, required — Whether this account owner is the primary contact
        - `created_at` string, date-time, required — The timestamp when the account owner was created
        - `updated_at` string, date-time, required — The timestamp when the account owner was last updated
    - `access_token` string, required — New access token with merchant:admin role
    - `refresh_token` string, required — New refresh token
    - `token_type` 'Bearer', required
    - `expires_in` number, required — Token expiry in seconds

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Response

---

[API](https://skmtc.net/banqzinc/apis/quidkey-api.md) · [All operations](https://skmtc.net/banqzinc/apis/quidkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/banqzinc/quidkey-api/revisions/f86d2bdbcb08/schema)