# Merchant Onboarding API (/platform-api/merchant_onboarding)





All requests on this page use your Server Secret Token. See [Authentication](/platform-api#authentication).

<Callout title="One onboarding for In-Store and Online" type="info">
  A merchant can request [In-Store Acceptance](/in-store), [Online Payments](/online), or both in one onboarding application. This page applies to every integration: the Accept SDK, the Tapaya Terminal app, and
  Checkout. Use it to create and manage merchants through the API instead of the Tapaya Platform UI. Request the payment capabilities the merchant needs. An in-store approval alone does not enable online payments.
</Callout>

Creating a merchant with `POST /integrator/merchant`, or with `POST /merchant/auth/register` in an
[Accept SDK integration](/in-store/integration/backend_integration#merchant-authentication-accept-sdk-integrations),
creates its account, but the merchant cannot process live payments in store or online until onboarding is complete.
For online payments, request the Checkout capability and wait for online processor approval and gateway setup. Merchants appear automatically in [Checkout settings](/online/integration/checkout_settings), where you can check readiness and configure keys and wallets. Tapaya supports several onboarding experiences; all can be managed from the Tapaya Platform UI and automated where appropriate.

| Flow                   | When to use it                                                             | API entry point                                                                                                                                                                                                    |
| ---------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Tapaya Platform UI** | Your operations team completes onboarding on the merchant's behalf.        | Create or select the merchant in the Tapaya Platform UI and open the hosted onboarding there.                                                                                                                      |
| **Your own UI**        | You collect and validate onboarding information in your product.           | Validate sections with `POST /integrator/merchant/onboarding/validate/*`, then submit with `POST /integrator/merchant/onboarding`. Detailed below.                                                                 |
| **Email invite**       | A known merchant receives a single-use invitation to self-onboard.         | Send an invite with `POST /integrator/merchant/send-registration-invite`; include `merchantToken` to bind the invite to an existing merchant shell, then list or revoke it through `/integrator/merchant/invites`. |
| **Campaign link**      | Multiple or not-yet-known merchants use a reusable self-registration link. | Create a link with `POST /integrator/merchant/reusable-registration-invites`; list or revoke links through the same resource.                                                                                      |

For a detailed comparison of these flows, see the [Merchant Onboarding guide](/merchants/onboarding).

For saved drafts, channel updates, reusable invite controls and pricing profiles, see [Merchant Management](/platform-api/merchant_management).

## Request online payment capabilities [#request-online-payment-capabilities]

`POST /integrator/merchant/onboarding` requires `capability`. Use the same capability when validating the business profile:

| Value | Capability | Channel details                                                         |
| ----- | ---------- | ----------------------------------------------------------------------- |
| `1`   | Both       | Supply `terminal` and `online`. Each channel requires its own approval. |
| `2`   | Terminals  | Supply `terminal` for in-store payments.                                |
| `3`   | Checkout   | Supply `online` for online payments. No terminal is required.           |

For Checkout, add the following top-level fields alongside the merchant's identity, address, shared `business`, and KYB data. The same channel fields apply to `POST /integrator/merchant/onboarding/validate/business`:

```json
{
	"capability": 3,
	"online": {
		"mcc": "5411",
		"statementDescriptor": "ACME CORP",
		"productDescription": "Groceries sold online",
		"averageItemValue": 2500,
		"expectedMonthlyTurnover": 500000,
		"url": "https://www.acme.example.com",
		"purchaseChargeTiming": 1,
		"averageDeliveryDays": 2,
		"topCountries": [{ "countryId": 1, "percentage": 100 }]
	}
}
```

When onboarding the online payment gateway, `online.url` is required for Checkout or Both (`capability=3` or `capability=1`).

Amounts are in minor currency units. The online website must use HTTP or HTTPS and its hostname must contain `www`. `statementDescriptor` is 5 to 22 characters. `purchaseChargeTiming` is `1` for order placed, `2` for shipped, or `3` for received. `averageDeliveryDays` is 0 to 999. Supply one to four unique `topCountries` whose percentages total 100.

Keep shared support and financial details in `business`. In channel-section mode, put MCC, statement descriptor, product description, and transaction estimates in the relevant `terminal` or `online` object. Validate the payload before submitting onboarding, and resolve the returned channel-specific field errors.

## Invite a Merchant to Complete Hosted Onboarding [#invite-a-merchant-to-complete-hosted-onboarding]

Use this flow when Tapaya should host the KYB form, but you still want to control merchant creation from your
backend.

<Callout title="Recommended when you own merchantToken" type="info">
  If your system owns the merchant identifier used later by the SDK or your back office, first create the merchant
  shell with `POST /merchant/auth/register` or `POST /integrator/merchant`, then call
  `POST /integrator/merchant/send-registration-invite` with the same `merchantToken`. This keeps the hosted
  onboarding attached to that merchant instead of creating a second one.
</Callout>

The recommended sequence is:

1. Create the merchant shell:
   * `POST /merchant/auth/register`, or
   * `POST /integrator/merchant`
2. Send the hosted onboarding invite with `POST /integrator/merchant/send-registration-invite`
3. Share the returned `registrationUrl` with the merchant if needed, and let them complete the Tapaya-hosted form
4. Poll merchant readiness through `GET /integrator/merchant/{merchantId}/status`

**Endpoint:** `POST /integrator/merchant/send-registration-invite`

<CodeBlockTabs defaultValue="curl" groupId="http-client">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      cURL
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/send-registration-invite' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: REPLACE_ME' \
    -d '{
            "email": "admin@acme.com",
            "merchantToken": "unique_merchant_id_from_your_db"
        }'
    ```
  </CodeBlockTab>
</CodeBlockTabs>

**Parameters:**

| Field                  | Type       | Required | Description                                                                                                                                                                                                                                                      |
| ---------------------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`                | `string`   | ✓        | Email address that should receive the hosted onboarding link.                                                                                                                                                                                                    |
| `merchantToken`        | `string`   |          | Existing merchant token to bind the invite to. Use this when you already created the merchant shell and want the hosted onboarding to fill that same merchant. If omitted, completing the invite creates a new merchant.                                         |
| `capability`           | `integer`  |          | Optional: 1 offers either or both channels, 2 terminals only, 3 Checkout only. Omit it to leave the channel choice unrestricted. This does not grant processor approval.                                                                                         |
| `commissionProfileIds` | `string[]` |          | Select one or two distinct profiles owned by your organization, at most one per pricing type. Omit both profile fields to use the organization default.                                                                                                          |
| `commissionProfileId`  | `string`   |          | <Badge variant="warning">Will be deprecated</Badge> Use `commissionProfileIds` for new integrations. The existing single-profile field remains supported. Do not send it together with the profile array. An existing merchant shell keeps its assigned profile. |

**Responses:**

| Code  | Description                                         |
| ----- | --------------------------------------------------- |
| `200` | Invite created. Response includes `registrationUrl` |
| `400` | Request validation error                            |
| `401` | Unauthorized                                        |
| `404` | Organization or merchant not found                  |
| `409` | Conflict                                            |

**Response body:**

```json
{
    "registrationUrl": "https://platform.tapaya.com/invite-merchant?token=...&merchantToken=unique_merchant_id_from_your_db"
}
```

Tapaya also attempts to email this link. Email delivery is best-effort, so always treat the returned
`registrationUrl` as the source of truth for your UI and support tooling.

<Callout title="Do not confuse this with merchant-user invite" type="warn">
  `POST /integrator/merchant/{merchantId}/invite` is a different flow. It invites a platform user to access an
  already-existing merchant account. It does **not** start KYB onboarding and does not create or update a merchant
  profile.
</Callout>

## Submit Onboarding through the API [#submit-onboarding-through-the-api]

If you want to collect onboarding information in your own product instead of sending merchants to the Tapaya Platform, submit it directly. Validate each section as the merchant fills it in with the `validate/*` endpoints below, then submit everything in one call, which creates the merchant and its onboarding profile together, and registers it with your organization's preferred payment processor. To check approval and finish with the processor afterwards, see [Check Approval and Finish with the Processor](#check-approval-and-finish-with-the-processor).

<Callout title="Merchant consent and privacy notice" type="warn">
  Before submitting onboarding details through the API, you must obtain the merchant's consent to the
  [Tapaya Integrators Terms and Conditions](https://tapaya.com/terms) and
  [Tapaya Privacy Policy](https://tapaya.com/privacy). Add a checkbox to your onboarding form that links to
  both documents, or link to the Tapaya documents from the terms text to which the merchant consents. You must also
  list Tapaya as a data processor in your own privacy policy.
</Callout>

`POST /integrator/merchant/onboarding` creates the merchant **and** submits onboarding in a single call. If the
onboarding data is invalid, it returns `422` with field-level errors and **no merchant is created**; there is no
partially-onboarded merchant to clean up or resume.

<div className="fd-steps [&_h3]:fd-step">
  ### Validate Identity [#validate-identity]

  **Endpoint:** `POST /integrator/merchant/onboarding/validate/identity`

  <CodeBlockTabs defaultValue="curl" groupId="http-client">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="curl">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="curl">
      ```bash
      curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/identity' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: REPLACE_ME' \
      -d '{
              "legalName": "Acme Corp s.r.o.",
              "businessTypeId": 2,
              "email": "admin@acme.com",
              "registrationNumber": "12345678",
              "vatNumber": "CZ12345678",
              "incorporationDate": "2018-04-01"
          }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  **Parameters:**

  | Field                | Type     | Required | Description                                                                             |
  | -------------------- | -------- | -------- | --------------------------------------------------------------------------------------- |
  | `legalName`          | `string` | ✓        | Legal name of the business or individual account holder.                                |
  | `businessTypeId`     | `int`    | ✓        | Type of business entity (`BusinessTypeEnum`).                                           |
  | `email`              | `string` | ✓        | Contact email address.                                                                  |
  | `registrationNumber` | `string` | ✓        | Official business registration number. Checked for duplicates within your organization. |
  | `vatNumber`          | `string` |          | VAT registration number, if applicable.                                                 |
  | `incorporationDate`  | `date`   |          | Date the business was legally incorporated (`YYYY-MM-DD`).                              |

  **Response body:**

  ```json
  {
      "valid": true,
      "errors": []
  }
  ```

  A `registrationNumber` already used by another merchant in your organization comes back as a `valid: false`
  error with `code: "DUPLICATE_REGISTRATION_NUMBER"` rather than a `409`; this endpoint always returns `200`.

  ### Validate Address [#validate-address]

  **Endpoint:** `POST /integrator/merchant/onboarding/validate/address`

  <CodeBlockTabs defaultValue="curl" groupId="http-client">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="curl">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="curl">
      ```bash
      curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/address' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: REPLACE_ME' \
      -d '{
              "line1": "Wenceslas Square 1",
              "city": "Prague",
              "postalCode": "11000",
              "countryId": 1
          }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  **Parameters:**

  | Field        | Type     | Required | Description                                       |
  | ------------ | -------- | -------- | ------------------------------------------------- |
  | `line1`      | `string` | ✓        | First line of the street address.                 |
  | `line2`      | `string` |          | Second line of the street address, if applicable. |
  | `city`       | `string` | ✓        | City name.                                        |
  | `postalCode` | `string` | ✓        | Postal or ZIP code.                               |
  | `state`      | `string` |          | State or region, if applicable.                   |
  | `countryId`  | `int`    | ✓        | Country (`CountryEnum`).                          |

  **Response body:** same `{valid, errors}` shape as [Validate Identity](#validate-identity).

  ### Validate Business Profile [#validate-business-profile]

  **Endpoint:** `POST /integrator/merchant/onboarding/validate/business`

  <CodeBlockTabs defaultValue="curl" groupId="http-client">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="curl">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="curl">
      ```bash
      curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/business' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: REPLACE_ME' \
      -d '{
              "capability": 2,
              "mcc": "5411",
              "url": "https://acme.example.com",
              "supportPhone": "+420123456789",
              "statementDescriptor": "ACME CORP"
          }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  **Parameters:**

  | Field                     | Type     | Required | Description                                                                                                                                                                                                                              |
  | ------------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `capability`              | `int`    | ✓        | Use the capability you will submit for onboarding. For Checkout or Both, supply the [channel details](#request-online-payment-capabilities).                                                                                             |
  | `mcc`                     | `string` | ✓        | Four-digit Merchant Category Code. In channel-section mode, use `terminal.mcc` or `online.mcc`.                                                                                                                                          |
  | `url`                     | `string` |          | Business website URL for requests without channel sections. Required for online payments. For terminal-only onboarding, provide either `url` or `productDescription`. With channel sections, provide the online website in `online.url`. |
  | `productDescription`      | `string` |          | Description of products or services. In terminal-only requests without channel sections, either `url` or `productDescription` is required.                                                                                               |
  | `supportPhone`            | `string` | ✓        | Customer support phone number, in E.164 format.                                                                                                                                                                                          |
  | `statementDescriptor`     | `string` | ✓        | Text shown on customer bank statements (1–22 characters).                                                                                                                                                                                |
  | `averageItemValue`        | `long`   |          | Average transaction value, in minor currency units.                                                                                                                                                                                      |
  | `expectedMonthlyTurnover` | `long`   |          | Expected monthly revenue, in minor currency units.                                                                                                                                                                                       |
  | `numberOfEmployees`       | `int`    |          | Number of employees at the business.                                                                                                                                                                                                     |
  | `annualTurnover`          | `long`   |          | Annual revenue, in minor currency units.                                                                                                                                                                                                 |
  | `balanceSheetTotal`       | `long`   |          | Total balance sheet value, in minor currency units.                                                                                                                                                                                      |

  **Response body:** same `{valid, errors}` shape as [Validate Identity](#validate-identity).

  ### Validate KYB [#validate-kyb]

  **Endpoint:** `POST /integrator/merchant/onboarding/validate/kyb`

  Provide exactly one of `individual` (sole trader / self-employed) or `company`. For a `company`, list every
  owner, director, and authorized signatory in `people`.

  <CodeBlockTabs defaultValue="curl" groupId="http-client">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="curl">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="curl">
      ```bash
      curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/kyb' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: REPLACE_ME' \
      -d '{
              "businessTypeId": 2,
              "bankAccount": {
                  "iban": "CZ6508000000192000145399",
                  "bic": "GIBACZPX",
                  "currencyId": 1,
                  "beneficiaryName": "Acme Corp s.r.o."
              },
              "company": {
                  "name": "Acme Corp s.r.o.",
                  "registrationNumber": "12345678",
                  "people": [
                      {
                          "email": "jane@acme.com",
                          "firstName": "Jane",
                          "lastName": "Doe",
                          "role": {
                              "isOwner": true,
                              "isAuthorizedSignatory": true
                          }
                      }
                  ]
              }
          }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  **Parameters:**

  | Field            | Type     | Required | Description                                                                                                                                                                  |
  | ---------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `businessTypeId` | `int`    |          | Type of business entity (`BusinessTypeEnum`); determines whether `individual` or `company` fields are required.                                                              |
  | `bankAccount`    | `object` |          | Legacy single settlement account. Used when `bankAccounts` is absent.                                                                                                        |
  | `bankAccounts`   | `array`  |          | Settlement accounts. Exactly one entry must have `isPrimary: true`. Takes precedence over `bankAccount`.                                                                     |
  | `individual`     | `object` |          | Individual owner details, for sole traders. Mutually exclusive with `company`.                                                                                               |
  | `company`        | `object` |          | Company details, including a `people` array of owners, directors, and authorized signatories, plus an optional `verificationDocument`. Mutually exclusive with `individual`. |

  Each `bankAccounts` entry accepts account number or `iban`, `bic`, `currencyId`, `beneficiaryName`, bank details, and `isPrimary`. The Platform form permits one account per available pricing currency. Select exactly one primary account. Onboarding updates do not delete saved accounts by omission.

  Each person in `people` (and `individual`) carries `role.isOwner` / `isDirector` / `isRepresentative` /
  `isAuthorizedSignatory` flags, plus optional identity fields (`dateOfBirth`, `nationalityCountryId`,
  `officialIdType`/`officialIdNumber`, `address`, `ownershipPercentage`, `verificationDocuments`). A person entry
  must be either invite-only or fully detailed; partially filled people are rejected. There are two ways to submit
  a person:

  * **Invite-only:** Submit only `email` and `role`. The person receives an email link to complete their details and upload their own documents.
  * **Fully detailed:** Submit the person's details and [upload their documents](#upload-a-persons-id-document).

  Documents are uploaded after the merchant exists, because the [document upload
  endpoint](#upload-a-persons-id-document) needs the `merchantId` returned by [Create Merchant with
  Onboarding](#create-merchant-with-onboarding). Each person's upload is matched to them by
  `relatedOfficialIdNumber`. The optional `verificationDocuments.identityDocument`,
  `verificationDocuments.additionalDocument`, and `company.verificationDocument` fields each take a
  `{frontFileId, backFileId}` object and can only reference files that were already uploaded, so omit them when
  creating a new merchant.

  Upload [proof of bank account](#upload-the-company-document) for the merchant regardless of how you submit the stakeholders' details.

  **Response body:** same `{valid, errors}` shape as [Validate Identity](#validate-identity).

  ### Create Merchant with Onboarding [#create-merchant-with-onboarding]

  Submits everything from the previous four steps in one call, creates the merchant, and registers it with your
  organization's preferred payment processor.

  **Endpoint:** `POST /integrator/merchant/onboarding`

  <CodeBlockTabs defaultValue="curl" groupId="http-client">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="curl">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="curl">
      ```bash
      curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: REPLACE_ME' \
      -d '{
              "name": "Acme Corp",
              "capability": 2,
              "merchantToken": "unique_merchant_id_from_your_db",
              "identity": {
                  "legalName": "Acme Corp s.r.o.",
                  "businessTypeId": 2,
                  "email": "admin@acme.com",
                  "registrationNumber": "12345678",
                  "vatNumber": "CZ12345678"
              },
              "address": {
                  "line1": "Wenceslas Square 1",
                  "city": "Prague",
                  "postalCode": "11000",
                  "countryId": 1
              },
              "business": {
                  "mcc": "5411",
                  "url": "https://acme.example.com",
                  "supportPhone": "+420123456789",
                  "statementDescriptor": "ACME CORP"
              },
              "kyb": {
                  "bankAccount": {
                      "iban": "CZ6508000000192000145399",
                      "bic": "GIBACZPX",
                      "currencyId": 1,
                      "beneficiaryName": "Acme Corp s.r.o."
                  },
                  "company": {
                      "people": [
                          {
                              "email": "jane@acme.com",
                              "firstName": "Jane",
                              "lastName": "Doe",
                              "role": {
                                  "isOwner": true,
                                  "isAuthorizedSignatory": true
                              }
                          }
                      ]
                  }
              }
          }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  **Parameters:**

  | Field           | Type     | Required      | Description                                                                                                                    |
  | --------------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
  | `capability`    | `int`    | ✓             | `1` for Both, `2` for Terminals, or `3` for Checkout. See [online payment capabilities](#request-online-payment-capabilities). |
  | `terminal`      | `object` | By capability | Terminal channel details for Terminals or Both.                                                                                |
  | `online`        | `object` | By capability | Online channel details for Checkout or Both.                                                                                   |
  | `name`          | `string` | ✓             | The name of the merchant.                                                                                                      |
  | `merchantToken` | `string` |               | A unique, stable identifier from your system. If not provided, a random token is generated.                                    |
  | `identity`      | `object` | ✓             | Same shape as [Validate Identity](#validate-identity).                                                                         |
  | `address`       | `object` | ✓             | Same shape as [Validate Address](#validate-address).                                                                           |
  | `business`      | `object` | ✓             | Same shape as [Validate Business Profile](#validate-business-profile).                                                         |
  | `kyb`           | `object` | ✓             | Same shape as [Validate KYB](#validate-kyb).                                                                                   |

  **Responses:**

  | Code  | Description                                                        |
  | ----- | ------------------------------------------------------------------ |
  | `201` | Merchant created and onboarding submitted                          |
  | `422` | Onboarding data invalid, see `errors`; merchant is **not** created |

  **Response body (`201`):**

  ```json
  {
      "merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e",
      "merchantToken": "unique_merchant_id_from_your_db",
      "name": "Acme Corp",
      "email": "admin@acme.com",
      "processors": [
          {
              "processorId": 5,
              "registered": true,
              "onboardingUrl": null
          }
      ]
  }
  ```

  `onboardingUrl` is populated when the processor requires the merchant to complete an additional hosted
  onboarding flow (e.g. identity verification) before it can process live payments.

  **Response body (`422`):**

  ```json
  {
      "errors": [
          {
              "step": "identity",
              "field": "registrationNumber",
              "message": "A merchant with this registration number is already onboarded under this integrator (merchantId: 018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e).",
              "code": "DUPLICATE_REGISTRATION_NUMBER"
          }
      ]
  }
  ```

  ### Stakeholder documents [#upload-a-persons-id-document]

  Collect an identity document and proof of address (`documentType=3`, `Address`) for each stakeholder. The proof of address must be a utility bill issued within the last six months, such as an electricity, gas, or water bill. When you upload proof of address through the integrator API, include the stakeholder's `relatedOfficialIdNumber`. People added by invitation upload their documents through the link in their email.

  The upload examples use an online Checkout merchant with `capability=3` and `paymentProcessorId=6`. Use the same ID for `GET /integrator/merchant/{merchantId}/processor`.

  **Endpoint:** `POST /integrator/merchant/{merchantId}/document`

  Request body is `multipart/form-data`, not JSON.

  <CodeBlockTabs defaultValue="curl" groupId="http-client">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="curl">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="curl">
      ```bash
      curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/document' \
      -H 'Authorization: REPLACE_ME' \
      -F 'paymentProcessorId=6' \
      -F 'documentType=2' \
      -F 'relatedOfficialIdNumber=123456789' \
      -F 'frontFile=@./jane-doe-id-front.jpg' \
      -F 'backFile=@./jane-doe-id-back.jpg'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  **Parameters:**

  | Field                     | Type      | Required | Description                                                                                                                                                                |
  | ------------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `paymentProcessorId`      | `int`     | ✓        | Use the merchant's `processors[].processorId` from the onboarding response or onboarding status. For these channels, `5` is for terminals and `6` is for online Checkout.  |
  | `documentType`            | `int`     | ✓        | Type of document (`DocumentTypeEnum`: `1` Other, `2` Id, `3` Address, `4` Company, `5` BankStatement, `6` Passport, `7` RecentFinancials).                                 |
  | `frontFile`               | `file`    | ✓        | Front side of the document image.                                                                                                                                          |
  | `backFile`                | `file`    |          | Back side of the document image, if applicable.                                                                                                                            |
  | `relatedOfficialIdNumber` | `string`  |          | The person's `officialIdNumber` from [Validate KYB](#validate-kyb). Required only when `documentType` is individual-bound (e.g. Id, Passport, Address); ignored otherwise. |
  | `submitMerchant`          | `boolean` |          | Set to `true` only if this is the final upload.                                                                                                                            |

  **Response body (`200`):**

  ```json
  {
      "frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h",
      "backFileId": "file_1NqtHp2eZvKYlo2CRTg9Xm3k",
      "uploadedAt": "2026-07-17T12:00:00Z"
  }
  ```

  ### Company documents [#upload-the-company-document]

  * **Required:** Proof of bank account (`documentType=5`, `BankStatement`).
  * **Optional:** Company registration or incorporation document (`documentType=4`, `Company`).

  The example uploads the bank statement last with `submitMerchant=true`.

  **Endpoint:** `POST /integrator/merchant/{merchantId}/document`

  Request body is `multipart/form-data`, not JSON.

  <CodeBlockTabs defaultValue="curl" groupId="http-client">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="curl">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="curl">
      ```bash
      curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/document' \
      -H 'Authorization: REPLACE_ME' \
      -F 'paymentProcessorId=6' \
      -F 'documentType=5' \
      -F 'frontFile=@./acme-bank-statement.pdf' \
      -F 'submitMerchant=true'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  **Parameters:**

  | Field                | Type      | Required | Description                                                                                                                                                                                                                                                                                                                                                   |
  | -------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `paymentProcessorId` | `int`     | ✓        | Use the merchant's `processors[].processorId` from the onboarding response or onboarding status. For these channels, `5` is for terminals and `6` is for online Checkout.                                                                                                                                                                                     |
  | `documentType`       | `int`     | ✓        | `5` for proof of bank account or `4` for an optional company document.                                                                                                                                                                                                                                                                                        |
  | `frontFile`          | `file`    | ✓        | The document file.                                                                                                                                                                                                                                                                                                                                            |
  | `submitMerchant`     | `boolean` |          | Set `submitMerchant=true` on the final document upload. Tapaya checks whether the merchant has provided all required onboarding information and documents. A `200 OK` response confirms that the file was uploaded. To check whether onboarding advanced or whether anything is still missing, use `GET /integrator/merchant/{merchantId}/onboarding/status`. |

  **Response body (`200`):**

  ```json
  {
      "frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h",
      "backFileId": null,
      "uploadedAt": "2026-07-17T12:00:00Z"
  }
  ```
</div>

## Check Approval and Finish with the Processor [#check-approval-and-finish-with-the-processor]

After you submit onboarding, the payment processor reviews the merchant. Check the result, then send anything the
processor still asks for. Merchants onboarded through the API or the Tapaya Platform are registered with your
organization's preferred processor automatically. `paymentProcessorId` values are listed in the
[Swagger documentation](https://api.tapaya.com/openapi/index.html).

<Accordions type="multiple">
  <Accordion title="Check processor status" id="check-processor-status">
    **Use it to** find out whether a merchant is approved: whether it can take payments and receive payouts with each processor.

    <CodeBlockTabs defaultValue="curl" groupId="http-client">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="curl">
          cURL
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="curl">
        ```bash
        curl "https://api.tapaya.com/integrator/merchant/$MERCHANT_ID/onboarding/status" \
        -H 'Authorization: REPLACE_ME'
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    ```json
    {
        "submitted": true,
        "processors": [
            {
                "processorId": 5,
                "processorMerchantId": "acct_0042",
                "registered": true,
                "chargesEnabled": true,
                "payoutsEnabled": false,
                "pastDueRequirements": [],
                "rejectedAt": null,
                "rejectedMsg": null,
                "registeredAt": "2026-10-20T09:15:00Z"
            }
        ]
    }
    ```

    **Good to know:**

    * `submitted` is `true` once the merchant has sent their onboarding profile.
    * A merchant can take payments when `chargesEnabled` is `true`, and receives money when `payoutsEnabled` is `true`.
    * A rejected account has `rejectedAt` and the processor's reason in `rejectedMsg`.

    **Returns:** for each processor in `processors`:

    | Field                              | Description                                                     |
    | ---------------------------------- | --------------------------------------------------------------- |
    | `processorId`                      | The processor this entry is for.                                |
    | `processorMerchantId`              | The account ID at the processor, or `null` before registration. |
    | `registered`, `registeredAt`       | Whether and when the merchant was registered.                   |
    | `chargesEnabled`, `payoutsEnabled` | Whether the account can take payments and send payouts.         |
    | `pastDueRequirements`              | Overdue items blocking the account. Empty when nothing is due.  |
    | `rejectedAt`, `rejectedMsg`        | When and why the processor rejected the account, or `null`.     |
  </Accordion>

  <Accordion title="Retrieve a processor account" id="retrieve-a-processor-account">
    **Use it to** see the details the processor holds and what it still needs from the merchant.

    <CodeBlockTabs defaultValue="curl" groupId="http-client">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="curl">
          cURL
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="curl">
        ```bash
        curl "https://api.tapaya.com/integrator/merchant/$MERCHANT_ID/processor?paymentProcessorId=$PROCESSOR_ID" \
        -H 'Authorization: REPLACE_ME'
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    **Good to know:**

    * Use the merchant's `processors[].processorId` from the onboarding response or [onboarding status](#check-processor-status) as the required `paymentProcessorId` query parameter.
    * Returns `404` if the merchant is not registered with that processor.
    * Requirement lists contain the processor's own requirement names. Show them to your support team, not to
      automation.

    **Returns:**

    | Field                                                                     | Description                                                 |
    | ------------------------------------------------------------------------- | ----------------------------------------------------------- |
    | `chargesEnabled`, `payoutsEnabled`                                        | Whether the account can take payments and send payouts now. |
    | `pendingRequirements`                                                     | What the processor needs now.                               |
    | `pastDueRequirements`                                                     | What is overdue and blocking the account.                   |
    | `eventuallyDueRequirements`                                               | What will be needed later, not blocking yet.                |
    | `disabledReasonRequirements`                                              | What caused a capability to be disabled.                    |
    | `requirementsDeadlineTimestamp`                                           | When the pending requirements are due, or `null`.           |
    | `mcc`, `url`, `productDescription`, `supportPhone`, `statementDescriptor` | Business details on file.                                   |
    | `bankAccount`, `individual`, `company`                                    | Payout account and the people and company on file.          |
    | `updatedAt`                                                               | When the record last changed.                               |
  </Accordion>

  <Accordion title="Update a processor account" id="update-a-processor-account">
    **Use it to** send the business details the processor asks for, such as the payout bank account or the company's
    owners.

    <CodeBlockTabs defaultValue="curl" groupId="http-client">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="curl">
          cURL
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="curl">
        ```bash
        curl -X PUT "https://api.tapaya.com/integrator/merchant/$MERCHANT_ID/processor" \
        -H 'Authorization: REPLACE_ME' \
        -H 'Content-Type: application/json' \
        -d '{
                "paymentProcessorId": '"$PROCESSOR_ID"',
                "capability": 1,
                "supportPhone": "+420123456789",
                "terminal": {
                    "mcc": "5812",
                    "statementDescriptor": "ACME CAFE"
                },
                "bankAccount": { "accountNumber": "CZ6508000000192000145399" },
                "final": true
            }'
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    **Good to know:**

    * Send `final: true` on the last submission, which sends the KYB email. With `false` or no value, no email is
      sent, so you can submit in several steps.
    * `capability` is the channel to enable: `1` both, `2` terminals, `3` online Checkout.
    * Put channel details in `terminal` or `online`. The top-level `mcc`, `productDescription`, and `statementDescriptor`
      are deprecated.
    * Returns `409` on a conflicting update.

    **Parameters:**

    | Field                | Description                                                                                                                                                                                           |
    | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `paymentProcessorId` | Required. The processor account to update.                                                                                                                                                            |
    | `capability`         | Required. `1` both, `2` terminals, `3` online Checkout.                                                                                                                                               |
    | `supportPhone`       | Required. The merchant's customer support phone.                                                                                                                                                      |
    | `terminal`           | In-store details: `mcc`, `statementDescriptor` (5 to 22 characters), `productDescription`, `averageItemValue`, `expectedMonthlyTurnover`, `maximumTransactionValue`, `numberOfTerminals` (1 to 9999). |
    | `online`             | Online details: the same fields, plus `url`, `purchaseChargeTiming`, `averageDeliveryDays` (0 to 999), and `topCountries` (one to four countries totalling 100%).                                     |
    | `url`                | The merchant's website or social media page.                                                                                                                                                          |
    | `bankAccount`        | Payout account: `accountNumber` (IBAN), with `bic`, `bankName`, `beneficiaryName`, and `currencyId` where the processor asks for them.                                                                |
    | `individual`         | The owner, for an individual business.                                                                                                                                                                |
    | `company`            | Legal `name`, `registrationNumber`, `address`, `vatNumber`, and `people` (owners, directors, representative).                                                                                         |
    | `final`              | `true` on the last submission.                                                                                                                                                                        |

    **Returns:** the account status: `chargesEnabled`, `payoutsEnabled`, the four requirement lists,
    `isFullyRequirementsSatisfied`, `isOperational` (charges and payouts enabled, nothing blocking), `summary` (a
    readable status for logs), and `submittedAt`.
  </Accordion>

  <Accordion title="Register a processor account" id="register-a-processor-account">
    **Use it to** open a processor account for a merchant. A merchant needs one before it can take payments through that
    processor.

    <CodeBlockTabs defaultValue="curl" groupId="http-client">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="curl">
          cURL
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="curl">
        ```bash
        curl -X POST "https://api.tapaya.com/integrator/merchant/$MERCHANT_ID/processor" \
        -H 'Authorization: REPLACE_ME' \
        -H 'Content-Type: application/json' \
        -H 'Idempotency-Key: register-merchant-42-processor' \
        -d "{ \"paymentProcessorId\": $PROCESSOR_ID }"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    **Good to know:**

    * Tapaya tells you which `paymentProcessorId` to use for your organization.
    * Send an `Idempotency-Key` so a retried request does not register twice.
    * When `directManagementSupported` is `false`, send the merchant to `onboardingUrl` to finish with the processor.
      When it is `true`, send the details with [Update a processor account](#update-a-processor-account).

    **Returns:**

    | Field                       | Description                                                                             |
    | --------------------------- | --------------------------------------------------------------------------------------- |
    | `directManagementSupported` | `true` if you can send the merchant's details through the API.                          |
    | `onboardingUrl`             | The processor's own onboarding page for the merchant, or `null` when the API is enough. |
  </Accordion>
</Accordions>

| Code  | Description                                                                                          |
| ----- | ---------------------------------------------------------------------------------------------------- |
| `400` | The request failed validation. The body lists the invalid fields.                                    |
| `401` | The Server Secret Token is missing or invalid.                                                       |
| `404` | The merchant does not exist, belongs to another organization, or has no account with that processor. |
| `409` | The update conflicts with the account's current state.                                               |
