Skip to main content

KYC

Every access token acts for one user, and that user must be KYC-verified before they can transact. Order reviews and order creation reject an unverified user with USER_KYC_VERIFICATION_REQUIRED.

You run the identity check with your own verification provider, then submit the result to us.

Status​

StatusMeaning
NONENo submission has been made for this user.
PROGRESSINGA submission is under review. The user still cannot transact.
VERIFIEDThe user can transact.
REJECTEDThe submission was rejected. rejectReason on the profile says why.

Get KYC status returns just the status — it is the cheap call to poll. Get KYC profile returns the full profile, including rejectReason, once a submission exists.

Submitting​

Submit KYC takes the user's identity fields, their document images, a selfie, and the verification report your provider produced. Images and the report are base64 data URLs rather than links to files:

data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...

Malformed ones are rejected with KYC_DOCUMENT_FORMAT_INVALID.

Almost every field is required. The exceptions:

  • address and phone are optional as a whole — but if you send an address, only line 2 within it is optional.
  • backImage is not required for passports, which have no back side.

After you submit​

The submission returns the resulting status, usually PROGRESSING. Poll Get KYC status until it settles on VERIFIED or REJECTED.

A second submission while one is in review returns USER_KYC_UNDER_PROCESSING, and a national ID that already belongs to a verified profile returns KYC_DOCUMENT_ALREADY_REGISTERED.

Supplementing a profile​

Supplement KYC adds to or corrects a profile that has already been submitted. It takes the same fields as the submission, all of them optional. The fields you send replace the stored values and the rest stay as they are, so you can send an address on its own. The KYC status does not change, which means a verified user keeps transacting.

An address is sent complete, with line 1, city, state and postal code; line 2 stays optional. A user who has not submitted KYC yet returns REQUESTED_INFO_NOT_FOUND; submit it first.

Other checks for verified users​

A verified user's transactions also go through these checks:

  • HIGHER_KYC_LEVEL_REQUIRED — the service needs a higher level than the user holds.
  • NATIONALITY_NOT_SUPPORTED — the nationality is not supported for that service.
  • HIGH_RISK_USER — the user is flagged by risk screening.

These checks apply per service and per currency, so eligibility can differ from one currency to another.

Markets that need extra profile fields​

Scan-to-Pay in BRL, ARS and PEN needs the user's address and gender when the user pays in the currency of their own nationality: a Brazilian user paying in BRL, an Argentine user in ARS, or a Peruvian user in PEN. If any of them is missing, order reviews and order creation return KYC_EXTRA_INFO_REQUIRED_FOR_LATAM_LOCAL_USER, and the message names the fields to add:

Additional KYC information is required for payments in your local currency. Missing: address, gender. Please update your profile and try again.

The fields after Missing: are comma-separated and named as in the submission. Send them with the KYC submission to avoid this. For a user who is already verified, add them with Supplement KYC and retry the order. While we complete the user's verification for that market, the order returns KYC_PROFILE_UNDER_REVIEW; retry it after a few minutes.

On this page