KYC / Identity Verification
Individual end-users must verify their identity before they can trade. Coinify runs the verification itself: you start an identification attempt, send the end-user to Coinify's verification flow, and find out the result once it is processed.
Using the Trade Widget or SDK? The widget handles identity verification for the end-user, so there is nothing to implement. This page applies to Full API Integration →.
Corporate users don't go through KYC. They complete a KYB document review instead, which Coinify triggers by email. See Mandatory User Information →.
How it works
- Initiate an identification attempt for the authenticated end-user.
- Redirect the end-user to the
redirectUrlreturned in the response. - The end-user completes verification on Coinify's side and is returned to your
returnUrl. - Wait for the final result, which arrives as a webhook (or can be fetched via API).
KYC is the last step of the individual onboarding sequence. The end-user's address must already be provided, along with the other mandatory information →, before you initiate an attempt.
Step 1: Initiate the identification attempt
Call Initiate identification attempt → with the end-user's access token:
POST https://app-api.sandbox.coinify.com/kyc/identification-attempts
Authorization: Bearer <access_token>{
"returnUrl": "https://yourapp.com/kyc-complete",
"deviceType": "desktop"
}| Parameter | Description |
|---|---|
returnUrl | Required. Where the end-user is sent after completing (or failing) verification. |
deviceType | Optional: android, ios or desktop. Helps Coinify tailor the experience. If omitted, it is detected from the request's User-Agent header. |
If you call this endpoint from your backend rather than from the end-user's device, pass
deviceTypeexplicitly, because theUser-Agentyour server sends won't reflect the end-user's device.
The response is an identification attempt → object containing the attempt's id, its state, the redirectUrl, and the expireTime after which the link is no longer valid.
Step 2: Redirect the end-user
Send the end-user to the redirectUrl. This is where they actually verify their identity. Nothing happens until they visit it.
Identification attempts expire. Once an attempt has expired, its
redirectUrlcan no longer be used to complete verification. If the end-user comes back after that, call Initiate identification attempt → again to get a new attempt and a freshredirectUrl.
Camera access is required. Identity verification uses the end-user's device camera. We recommend a full-page redirect (or opening the redirectUrl in the device's browser) and handling the return via returnUrl. If you use an in-app webview or iframe, make sure it has camera permission.
Step 3: Handle the return
When the end-user finishes, Coinify redirects them to your returnUrl with a result query parameter appended:
result | Meaning |
|---|---|
submitted | The end-user submitted their documents. |
failed | The end-user failed to submit their identification. |
For example, https://yourapp.com/kyc-complete becomes https://yourapp.com/kyc-complete?result=submitted. Any query parameters already on your returnUrl are preserved.
result=submitteddoes not mean the end-user is approved. It only means the documents were handed over. Verification is processed afterwards, so show a "verification in progress" screen rather than letting them trade.
Step 4: Get the final result
An identification attempt moves through these states:
| State | Type | Meaning |
|---|---|---|
pending | Starting | The attempt was initiated and is waiting for the end-user to complete verification. |
approved | Final | The attempt was approved. Also used when a manual review ended in approval. |
rejected | Final | The attempt was rejected. The rejectReason field says why. |
Rather than polling, listen for the webhook events identification-attempt.approved and identification-attempt.rejected. See Webhook Events →. You can also fetch the current state with Get identification attempt info →, or see all of an end-user's attempts with List identification attempts →.
Rejection reasons
rejectReason | Meaning |
|---|---|
DENIED_UNSUPPORTED_ID_COUNTRY | The ID document was issued in a country Coinify doesn't support. |
MANUAL_REVIEW | The attempt is under manual review by Coinify compliance. This is not a final decision. |
Other reasons may also be returned. See all Reject reasons →.
Manual review can take 1-3 days. Coinify emails the end-user the final decision and sends the corresponding webhook to your endpoint. Tell the end-user their verification is under review, and don't present it as a rejection.
Testing in sandbox
You can approve an identification attempt instantly without going through the process itself in Sandbox environment. See Skipping KYC in sandbox → on the Sandbox & Testing page.
Next steps
- Trade Quotes → for what an approved end-user can do next
- Webhook Events → to receive the KYC result
- Sandbox & Testing → to skip KYC while building
Updated about 1 month ago
