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
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.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. Abank_debit_authorizationnames its account inbank_account.
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.
3. Create the Legal Entity
The legal entity is the company or sole trader the merchant is. A merchant has one."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_TOTAL_EXCEEDED gives what’s left in details, as available_percent. Quidkey doesn’t take documents through the API.
5. Start Each Identity Check
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 theirhosted_link.url. They complete the check on that page. Person.
7. Follow the Checks
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:bank_debit_authorization on your page, as in step 2. Person. Then add the account:
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 aspay_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 readsnot_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 itscodenames.LEGAL_ENTITY_INCOMPLETEmeansPATCH /legal-entities/{id}, with the fieldsfieldsnames, on the legal entity intarget.AGREEMENT_ACCEPTANCE_REQUIREDandBANK_DEBIT_AUTHORIZATION_REQUIREDmean recording an acceptance, as in step 2.person: someone acts in Console, or on the page inhosted_link.quidkey: there’s nothing for you to do.
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.