---
title: "Create a Merchant"
method: POST
path: "/v1/merchants"
tags: ["Merchants"]
---

# Create a Merchant

`POST /v1/merchants`

## Request body

- CreateMerchantRequest
  - `externalMerchantReference` string, required — Unique reference, assigned by external client.
  - `legalEntityName` string, required — The officially registered name of the business as recorded in legal or governmental registries.
  - `legalEntityType` 'COMPANY' | 'PARTNERSHIP' | 'SOLE_TRADER' | 'INDIVIDUAL' | 'NON_PROFIT', required — Classification of the business structure. Allowed values: COMPANY, PARTNERSHIP, SOLE_TRADER, INDIVIDUAL, NON_PROFIT.
  - `tradeName` string — The name the business operates under in public-facing contexts. This is the "doing business as" (DBA) name and may differ from the legal name.
  - `registrationNumber` string — A unique identifier assigned to the business upon incorporation by a government or regulatory authority.
  - `incorporationDate` string, date — The date the business was legally registered or incorporated.
  - `address` Address, required
    - `street` string, required
    - `city` string, required
    - `region` string
    - `postalCode` string — Required for countries that use postal codes. This field can be omitted for the following country codes: AO,AI,AG,AW,BS,BZ,BJ,BM,BO,BQ,BW,CF,TD,KM,CG,CD,CK,CI,CW,DJ,DM,TL,GQ,ER,FJ,TF,GA,GM,GY,GD,HK,HM,IO,MO,MH,MS,NR,NU,NF,PW,PA,WS,KN,LC,VC,ST,SC,SL,SX,SB,SS,GS,SH,TC,TK,TO,TV,UG,AE,VA,VU,YE,ZW
    - `country` string, required — ISO 3166-1 alpha-2 Country Code
  - `phoneNumber` string
  - `people` CreateMerchantPersonRequest[]
    - `relationshipType` 'DIRECTOR' | 'ULTIMATE_BENEFICIAL_OWNER', required — The relationship type of the person in relation to the business (e.g., DIRECTOR, ULTIMATE_BENEFICIAL_OWNER)
    - `personId` string — Unique identifier for the person
    - `person` CreatePersonRequest
      - `externalPersonReference` string — Unique reference, assigned by external client.
      - `firstName` string, required — The legal given name of the person.
      - `lastName` string, required — The legal surname or family name of the person.
      - `middleName` string — An optional middle name of the person, if applicable.
      - `nativeName` string — The person’s name in their native script (e.g., Cyrillic, Kanji), if different from Latin characters.
      - `birthDate` string, date, required — The person’s birth date, in ISO-8601 format YYYY-MM-DD.
      - `address` Address, required
        - `street` string, required
        - `city` string, required
        - `region` string
        - `postalCode` string — Required for countries that use postal codes. This field can be omitted for the following country codes: AO,AI,AG,AW,BS,BZ,BJ,BM,BO,BQ,BW,CF,TD,KM,CG,CD,CK,CI,CW,DJ,DM,TL,GQ,ER,FJ,TF,GA,GM,GY,GD,HK,HM,IO,MO,MH,MS,NR,NU,NF,PW,PA,WS,KN,LC,VC,ST,SC,SL,SX,SB,SS,GS,SH,TC,TK,TO,TV,UG,AE,VA,VU,YE,ZW
        - `country` string, required — ISO 3166-1 alpha-2 Country Code
      - `email` string, email — An email address.
  - `simpleApiWebhooksUrl` string, uri — The endpoint where Simple API (v1) event webhooks should be sent.
  - `platformId` string — Unique identifier for the platform
  - `pspId` string — Unique identifier for the PSP
  - `url` string, uri, required — An e-commerce website or public-facing digital storefront.
  - `mcc` string, required — Merchant Category Code assigned to the business, indicating the type of goods or services sold.
  - `averageTransactionValue` number — The typical value of a single transaction. Major units, example 50.00
  - `monthlyTransactionCount` integer — The expected or historical number of transactions processed per month.
  - `currency` string — ISO-4217 currency code (e.g., EUR, USD)
  - `paymentDescriptor` string — The text customers see on their bank statement for transactions from this store.

## Response `201`

Merchant created successfully

- CreateMerchantResponse — Merchant record as returned by Entity .
  - `id` string, required — Unique identifier for the merchant
  - `pspId` string — Unique identifier for the PSP
  - `externalMerchantReference` string, required — Unique reference, assigned by external client.
  - `legalEntityName` string, required — The officially registered name of the business as recorded in legal or governmental registries.
  - `legalEntityType` 'COMPANY' | 'PARTNERSHIP' | 'SOLE_TRADER' | 'INDIVIDUAL' | 'NON_PROFIT', required — Classification of the business structure. Allowed values: COMPANY, PARTNERSHIP, SOLE_TRADER, INDIVIDUAL, NON_PROFIT.
  - `tradeName` string — The name the business operates under in public-facing contexts. This is the "doing business as" (DBA) name and may differ from the legal name.
  - `registrationNumber` string — A unique identifier assigned to the business upon incorporation by a government or regulatory authority.
  - `incorporationDate` string, date — The date the business was legally registered or incorporated.
  - `address` Address, required
    - `street` string, required
    - `city` string, required
    - `region` string
    - `postalCode` string — Required for countries that use postal codes. This field can be omitted for the following country codes: AO,AI,AG,AW,BS,BZ,BJ,BM,BO,BQ,BW,CF,TD,KM,CG,CD,CK,CI,CW,DJ,DM,TL,GQ,ER,FJ,TF,GA,GM,GY,GD,HK,HM,IO,MO,MH,MS,NR,NU,NF,PW,PA,WS,KN,LC,VC,ST,SC,SL,SX,SB,SS,GS,SH,TC,TK,TO,TV,UG,AE,VA,VU,YE,ZW
    - `country` string, required — ISO 3166-1 alpha-2 Country Code
  - `phoneNumber` string
  - `email` string, email — An email address.
  - `simpleApiWebhooksUrl` string, uri — The endpoint where Simple API (v1) event webhooks should be sent.
  - `platformId` string — Unique identifier for the platform
  - `createdAt` string, date-time, required — Timestamp when the resource was created. UTC timezone. Format YYYY-MM-DDTHH:MM:SS.ssssssZ
  - `updatedAt` string, date-time, required — Timestamp when the resource was last updated. UTC timezone. Format YYYY-MM-DDTHH:MM:SS.ssssssZ
  - `url` string, uri, required — An e-commerce website or public-facing digital storefront.
  - `mcc` string, required — Merchant Category Code assigned to the business, indicating the type of goods or services sold.
  - `averageTransactionValue` number — The typical value of a single transaction. Major units, example 50.00
  - `monthlyTransactionCount` integer — The expected or historical number of transactions processed per month.
  - `currency` string — ISO-4217 currency code (e.g., EUR, USD)
  - `paymentDescriptor` string — The text customers see on their bank statement for transactions from this store.
  - `people` MerchantPersonDetails[]
    - `relationshipType` 'DIRECTOR' | 'ULTIMATE_BENEFICIAL_OWNER', required — The relationship type of the person in relation to the business (e.g., DIRECTOR, ULTIMATE_BENEFICIAL_OWNER)
    - `person` PersonDetails, required — Person record with audit timestamps aligned to Entity .
      - `id` string, required — Unique identifier for the person
      - `externalPersonReference` string — Unique reference, assigned by external client.
      - `firstName` string, required — The legal given name of the person.
      - `lastName` string, required — The legal surname or family name of the person.
      - `middleName` string — An optional middle name of the person, if applicable.
      - `nativeName` string — The person’s name in their native script (e.g., Cyrillic, Kanji), if different from Latin characters.
      - `birthDate` string, date — The person’s birth date, in ISO-8601 format YYYY-MM-DD.
      - `address` Address, required
        - `street` string, required
        - `city` string, required
        - `region` string
        - `postalCode` string — Required for countries that use postal codes. This field can be omitted for the following country codes: AO,AI,AG,AW,BS,BZ,BJ,BM,BO,BQ,BW,CF,TD,KM,CG,CD,CK,CI,CW,DJ,DM,TL,GQ,ER,FJ,TF,GA,GM,GY,GD,HK,HM,IO,MO,MH,MS,NR,NU,NF,PW,PA,WS,KN,LC,VC,ST,SC,SL,SX,SB,SS,GS,SH,TC,TK,TO,TV,UG,AE,VA,VU,YE,ZW
        - `country` string, required — ISO 3166-1 alpha-2 Country Code
      - `email` string, email — An email address.
      - `createdAt` string, date-time, required — Timestamp when the resource was created. UTC timezone. Format YYYY-MM-DDTHH:MM:SS.ssssssZ
      - `updatedAt` string, date-time, required — Timestamp when the resource was last updated. UTC timezone. Format YYYY-MM-DDTHH:MM:SS.ssssssZ

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `404` — Resource not found
- `405` — Method not allowed
- `409` — Resource conflict
- `429` — Too many requests
- `500` — Internal Server Error
- `504` — Gateway Timeout

---

[API](https://skmtc.net/ppro/apis/payment-charges.md) · [All operations](https://skmtc.net/ppro/apis/payment-charges/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ppro/payment-charges/versions/112e8bb4c815/schema)