Skip to main content
POST
Submit KYC Documents

Overview

Submit identity documents for a cardholder on their behalf using Shared KYC. This endpoint is only available to businesses that have completed FYATU’s Shared KYC onboarding process. The endpoint responds immediately with kycStatus: PENDING. Documents are processed in the background and a cardholder.kyc_approved webhook is dispatched when complete.
This endpoint returns 403 SHARED_KYC_NOT_ENABLED if your business does not have Shared KYC enabled. To apply, reach out to FYATU through your dedicated Slack channel. Enabling Shared KYC requires a due diligence review and the use of a recognised KYC provider (e.g. Sumsub, Persona, Onfido).

Endpoint

Scope required: cardholders:write

Path Parameters

Request Fields

Image Requirements

  • Format: JPEG, PNG, GIF, or WebP
  • Maximum size: 5MB per image
  • Accessibility: URLs must be publicly accessible

How It Works

  1. Your app sends document URLs to this endpoint
  2. FYATU responds immediately with PENDING status
  3. FYATU processes the documents in the background
  4. On success, kycStatus is set to ACCEPTED and a cardholder.kyc_approved webhook is dispatched with the final document URLs
  5. On failure, kycStatus is set to REJECTED — you can re-submit

Prerequisites

  • Business must have Shared KYC enabled (contact FYATU via your dedicated Slack channel)
  • Cardholder kycStatus must be UNSUBMITTED or REJECTED
  • All image URLs must be publicly accessible

Example Usage

Example Response

Success (200)

The final approved state arrives via webhook once background processing completes:

Error Responses

Shared KYC Not Enabled (403)

Already Accepted (409)

Already Processing (409)

Validation Error (400)

You can also submit KYC documents at cardholder creation time by including a kyc object in the POST /cardholders request body. See the Create Cardholder endpoint for details.

Authorizations

Authorization
string
header
required

JWT access token obtained from /auth/token

Path Parameters

id
string
required

Unique cardholder identifier

Body

application/json
documentType
enum<string>
required

Type of identification document

Available options:
PASSPORT,
NATIONAL_ID,
DRIVER_LICENSE
documentNumber
string
required

Document identification number

Required string length: 3 - 50
idFrontUrl
string<uri>
required

URL to the front image of the ID document

Maximum string length: 500
idBackUrl
string<uri>

URL to the back image of the ID document (optional for passports)

Maximum string length: 500
selfieUrl
string<uri>

URL to a selfie photo holding the ID document

Maximum string length: 500

Response

KYC documents submitted successfully

success
boolean
Example:

true

status
integer
Example:

200

message
string
Example:

"KYC documents submitted successfully"

data
object