> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quidkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard a Merchant

> For partners: create a merchant, describe its business, verify its people, add its bank account and take it live

A partner onboards each of its merchants with its own credential. The people at the merchant accept agreements and verify their identity on pages the partner shows them, and the partner records what they accepted. Quidkey reviews the merchant and puts it live.

A merchant's own credential can do these steps too, apart from creating the merchant, starting identity checks and requesting capabilities, which only its partner's credential does.

| # | Step | Who |
| - | - | - |
| 1 | Create the merchant, with the person's consent to the agreements every merchant accepts | API |
| 2 | A person accepts each agreement on your page | **Person** |
| 3 | Create the legal entity, with the `nacha_acknowledgment` | API |
| 4 | Add its owners and directors | API |
| 5 | Start each person's identity check | API |
| 6 | Each person completes their check | **Person** |
| 7 | Follow the checks | API, polling |
| 8 | A person accepts the `bank_debit_authorization`, and you add the bank account | **Person**, then API |
| 9 | Quidkey reviews the merchant and signs it off, once every agreement is accepted | **Quidkey** |
| 10 | Request each capability once it reads `ready` | API, polling |
| 11 | Follow the onboarding until it's live | API, polling |

Identity checks, capabilities and onboarding send no events, so poll them. The merchant going live sends `merchant.active` to your [webhook endpoint](https://docs.quidkey.com/api-v1/journeys/partner-webhooks.md).

## 1. Create the Merchant

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/partners/p_1/merchants' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Idempotency-Key: "3b9d6c1e-5f2a-4e8b-9c7d-0a1b2c3d4e5f"' \
  -H 'Content-Type: application/json' \
  -d '{
    "brand_name": "Example Store",
    "website_url": "https://shop.example.com",
    "category_code": "5732",
    "country": "GB",
    "account_owners": [{ "full_name": "Jane Doe", "email": "jane@example.com" }]
  }'
```

The answer is 201, with the merchant at `status: pending`. `category_code` is the four-digit ISO 18245 merchant category code. `country` is set here, and can't be changed later. A website belongs to one merchant, so a second merchant with it answers 409 `MERCHANT_ALREADY_EXISTS`.

The create can carry a person's acceptance of the agreements every merchant accepts, in `consent`, as step 2 describes. `consent.agreements` then names the current version of all seven. Leave `consent` out to record each acceptance later.

## 2. Get Consent on Your Own Page

A merchant accepts agreements before Quidkey signs it off. A person at the merchant accepts each one on your own page. You record who accepted it, when, from which IP address, and the exact wording they saw, and attest that consent to Quidkey.

```bash theme={null}
curl 'https://api.quidkey.com/v1/agreements?kind=nacha_acknowledgment'
```

`GET /agreements` needs no token. It lists the current version of each kind, with its `id` and `document_url`. Show or link the document, and keep the `id`: a consent names the version the person accepted.

| Agreement | Who accepts it | With which create |
| - | - | - |
| `merchant_terms`, `privacy_notice`, `data_processing_addendum`, `prohibited_use_policy`, `pricing_plan`, `third_party_services` and `banking_partner_authorization` | Every merchant | The merchant's |
| `nacha_acknowledgment` | A merchant with a legal entity, in every country | The legal entity's |
| `bank_debit_authorization` | Each active `owned` bank account | The bank account's |
| The ones a capability lists in `required_agreements` | A merchant requesting that capability | None |

There are two ways to record an acceptance, and Quidkey treats both the same:

* **With the create.** Send the consent in the create's `consent`. It's optional.
* **Later.** Record it on its own with `POST /merchants/{id}/agreement-acceptances`, as below. A `bank_debit_authorization` names its account in `bank_account`.

The merchant's onboarding lists each agreement still to accept in `required_actions`: `AGREEMENT_ACCEPTANCE_REQUIRED` with the agreement's current version in `target`, and `BANK_DEBIT_AUTHORIZATION_REQUIRED` with the bank account in `target`. Quidkey won't sign the merchant off until every one is accepted. A merchant Quidkey has already signed off isn't asked.

### Record an Acceptance Later

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/merchants/m_1/agreement-acceptances' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "agreement": { "id": "agr_bank_debit" },
    "bank_account": { "id": "ba_1" },
    "is_accepted": true,
    "accepted_at": "2026-11-02T10:10:00.000Z",
    "accepted_by": { "full_name": "Jane Doe", "email": "jane@example.com" },
    "accepted_ip": "203.0.113.7",
    "wording": "THE WORDING THE PERSON SAW",
    "locale": "en-GB"
  }'
```

`is_accepted` is required and must be `true`, as in a `consent`: `false` answers 400 `CONSENT_NOT_ACCEPTED`. The answer is 201, and a version already on file answers 200 with the acceptance there, so a repeat is safe. For a `bank_debit_authorization`, that's the same version for the same account. Leave `bank_account` out for any other agreement. A `nacha_acknowledgment` or a `bank_debit_authorization` needs the merchant's legal entity first. The details you attest are never returned.

## 3. Create the Legal Entity

The legal entity is the company or sole trader the merchant is. A merchant has one.

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/merchants/m_1/legal-entities' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "company",
    "legal_name": "Example Store Ltd",
    "registration_number": "01234567",
    "legal_structure": "private_limited_company",
    "country_of_incorporation": "GB",
    "registered_address": {
      "line1": "1 Example Street",
      "city": "London",
      "postal_code": "EC1A 1AA",
      "country": "GB"
    },
    "contact_full_name": "Jane Doe",
    "contact_email": "jane@example.com",
    "contact_phone": "+442071234567",
    "consent": {
      "is_accepted": true,
      "accepted_at": "2026-11-02T09:58:00.000Z",
      "accepted_by": { "full_name": "Jane Doe", "email": "jane@example.com" },
      "accepted_ip": "203.0.113.7",
      "wording": "THE WORDING THE PERSON SAW",
      "locale": "en-GB",
      "agreements": [{ "id": "agr_nacha" }]
    }
  }'
```

A sole trader is `"type": "individual"`, with `first_name`, `last_name`, `email`, `phone`, `date_of_birth`, `country_of_citizenship` and `residential_address` instead. `GET /countries/{id}` lists a country's legal structures and its field rules: see [Bank account identifiers](https://docs.quidkey.com/api-v1/reference/bank-account-identifiers.md#other-country-rules).

This create takes no `Idempotency-Key`. If its answer is lost, it answers 503 `OUTCOME_UNKNOWN`: list `GET /merchants/{id}/legal-entities` before trying again.

`consent` is optional: leave it out to record the acknowledgment later, as in step 2. A consent naming an old version of the agreement answers 400 `CONSENT_AGREEMENT_STALE`, with the current version in `details`. Show the person the current one, and send their new consent.

## 4. Add Owners and Directors

Add each person or company connected to the legal entity: its directors, and anyone holding 25% or more.

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/legal-entities/le_1/parties' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Idempotency-Key: "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "individual",
    "party_roles": ["owner", "director"],
    "ownership_percent": "100.00",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "+447700900123",
    "date_of_birth": "1990-04-21",
    "country_of_citizenship": "GB",
    "residential_address": {
      "line1": "2 Example Road",
      "city": "London",
      "postal_code": "N1 1AA",
      "country": "GB"
    }
  }'
```

Ownership can't add up to more than 100%: `OWNERSHIP_TOTAL_EXCEEDED` gives what's left in `details`, as `available_percent`. Quidkey doesn't take documents through the API.

## 5. Start Each Identity Check

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/parties/pty_1:verifyIdentity' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

The answer is 200, with an `identity_verification` whose `hosted_link` is the page where the person completes the check. Partner credentials start a check, and a merchant credential gets 403 `FORBIDDEN`. `hosted_link` appears only in this answer. Calling `:verifyIdentity` again is safe: it answers the check in flight, with its link.

## 6. The Person Completes Their Check

Send each person their `hosted_link.url`. They complete the check on that page. **Person.**

## 7. Follow the Checks

```bash theme={null}
curl 'https://api.quidkey.com/v1/merchants/m_1/identity-verifications' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

The list holds each party's latest check, with its `status`. `approved` means the check passed, and `name_check_status` says whether the name on the document matched the party. A check that ends `declined`, `abandoned`, `expired` or `failed` can be started again with `:verifyIdentity`.

## 8. Add the Bank Account

Read the merchant's country to see which payment schemes an account there takes:

```bash theme={null}
curl 'https://api.quidkey.com/v1/countries/GB' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

A person accepts the current `bank_debit_authorization` on your page, as in step 2. **Person.** Then add the account:

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/merchants/m_1/bank-accounts' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Idempotency-Key: "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f"' \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": "GBP",
    "country": "GB",
    "account_holder_name": "Example Store Ltd",
    "sort_code": "112233",
    "account_number": "12345678",
    "payment_schemes": [{ "id": "faster_payments", "is_active": true }],
    "consent": {
      "is_accepted": true,
      "accepted_at": "2026-11-02T10:05:00.000Z",
      "accepted_by": { "full_name": "Jane Doe", "email": "jane@example.com" },
      "accepted_ip": "203.0.113.7",
      "wording": "THE WORDING THE PERSON SAW",
      "locale": "en-GB",
      "agreements": [{ "id": "agr_bank_debit" }]
    }
  }'
```

The account is created `active`, with `ownership_status: pending` until Quidkey verifies it's the merchant's. It needs the legal entity first. As with the legal entity, `consent` is optional. The identifiers each country needs are in [Bank account identifiers](https://docs.quidkey.com/api-v1/reference/bank-account-identifiers.md), and the scheme codes in [Payment schemes](https://docs.quidkey.com/api-v1/reference/payment-schemes.md).

## 9. Quidkey Reviews the Merchant

Quidkey reviews the legal entity, its people and its bank account, and signs the merchant off once every agreement in step 2 is accepted. There's nothing to call. **Quidkey.**

## 10. Request Each Capability

A capability is something the merchant can do, such as `pay_by_bank_uk_eu` or `virtual_accounts`. Read one until it's `ready`, then request it:

```bash theme={null}
curl 'https://api.quidkey.com/v1/merchants/m_1/capabilities/virtual_accounts' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

curl -X POST 'https://api.quidkey.com/v1/merchants/m_1/capabilities/virtual_accounts:request' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

| `status` | Meaning |
| - | - |
| `unavailable` | Not offered to this merchant. |
| `not_ready` | Something is missing, and `required_actions` says what. |
| `ready` | Request it. |
| `in_review` | Requested, and with Quidkey or a provider. |
| `active` | Done, and the merchant is live. |

A request that isn't ready answers 409 `CAPABILITY_NOT_READY`, with what's missing in `details`. One that's already requested answers 200, so a repeat is safe. While another request for the same capability is going through, it answers 503 `SERVICE_UNAVAILABLE`: repeat it to see where it stands. `OUTCOME_UNKNOWN` means it may have gone through: contact Quidkey. Until Quidkey has checked, a repeat answers `OUTCOME_UNKNOWN` again.

### Agreements a Capability Requires

A capability that needs an agreement reads `not_ready`, with `AGREEMENT_ACCEPTANCE_REQUIRED` in `required_actions` and the agreement in `required_agreements`, which the read includes by default. A person accepts it on your page, and you record it as in [Record an Acceptance Later](#record-an-acceptance-later).

> [!NOTE]
>
> `pay_by_bank_us` is requested through Quidkey: its `:request` answers 422 `CAPABILITY_NOT_REQUESTABLE`. Where it needs `virtual_accounts` first, it reads `CAPABILITY_REQUEST_REQUIRED` until you've requested that, then `QUIDKEY_SETUP_PENDING` until Quidkey completes it.

## 11. Follow the Onboarding

```bash theme={null}
curl 'https://api.quidkey.com/v1/merchants/m_1/onboarding' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

| `status` | Meaning |
| - | - |
| `setting_up` | Details are still being filled in. |
| `in_review` | With Quidkey. Nothing is needed from you. |
| `action_required` | With Quidkey, and a task is waiting on you again. |
| `live` | The merchant is live. |

Each entry in `required_actions` has an `actor`:

* `api`: make the call its `code` names. `LEGAL_ENTITY_INCOMPLETE` means `PATCH /legal-entities/{id}`, with the fields `fields` names, on the legal entity in `target`. `AGREEMENT_ACCEPTANCE_REQUIRED` and `BANK_DEBIT_AUTHORIZATION_REQUIRED` mean recording an acceptance, as in step 2.
* `person`: someone acts in Console, or on the page in `hosted_link`.
* `quidkey`: there's nothing for you to do.

When Quidkey puts the merchant live, your endpoint receives `merchant.active`. `GET /merchants/{id}` then reads `status: active`, `GET /merchants/{id}/onboarding` reads `status: live`, and `GET /merchants/{id}/capabilities` lists each capability the merchant can take payment with as `active`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.