Skip to main content
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. Identity checks, capabilities and onboarding send no events, so poll them. The merchant going live sends merchant.active to your webhook endpoint.

1. Create the Merchant

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. 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.
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. 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

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. The legal entity is the company or sole trader the merchant is. A merchant has one.
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. 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.
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

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

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:
A person accepts the current bank_debit_authorization on your page, as in step 2. Person. Then add the account:
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, and the scheme codes in Payment schemes.

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:
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.
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

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.