Skip to main content
POST
/
cardholders
/
{id}
/
kyc
Submit KYC Documents
curl --request POST \
  --url https://api.fyatu.com/api/v3/cardholders/{id}/kyc \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentType": "PASSPORT",
  "documentNumber": "AB123456",
  "idFrontUrl": "https://storage.example.com/documents/id_front.jpg",
  "idBackUrl": "https://storage.example.com/documents/id_back.jpg",
  "selfieUrl": "https://storage.example.com/documents/selfie.jpg"
}
'
{
  "success": true,
  "status": 200,
  "message": "KYC documents submitted successfully",
  "data": {
    "id": "ch_1a2b3c4d5e6f7890abcdef1234567890",
    "kycStatus": "PENDING",
    "message": "KYC documents submitted successfully. Verification is pending."
  }
}

​
Overview

Submit KYC (Know Your Customer) verification documents for a cardholder. This will update the KYC status to PENDING while documents are reviewed. Once verified, the status will change to VERIFIED.

​
Path Parameters

ParameterTypeDescription
idstringUnique cardholder identifier

​
Request Fields

FieldTypeRequiredDescription
documentTypestringYesDocument type (PASSPORT, NATIONAL_ID, DRIVER_LICENSE)
documentNumberstringYesDocument identification number
idFrontUrlstringYesURL to the front image of the ID document
idBackUrlstringNoURL to the back image (optional for passports)
selfieUrlstringNoURL to a selfie photo holding the ID document

​
Document Requirements

​
Supported Document Types

TypeDescriptionBack Required
PASSPORTInternational passportNo
NATIONAL_IDGovernment-issued national ID cardYes
DRIVER_LICENSEDriver’s licenseYes

​
Image Requirements

  • Format: JPEG, PNG, GIF, or WebP only
  • Maximum size: 5MB per image
  • Accessibility: URLs must be publicly accessible (no authentication required)
  • Quality: Clear, readable, not blurry
  • Lighting: Well-lit, no glare or shadows
Images are downloaded from the provided URLs and securely stored on FYATU’s servers. The original URLs are not stored - only the processed copies hosted by FYATU.

​
Example Usage

<?php
$cardholderId = 'ch_1a2b3c4d5e6f7890abcdef1234567890';

$data = [
    'documentType' => 'PASSPORT',
    'documentNumber' => 'AB123456',
    'idFrontUrl' => 'https://storage.example.com/documents/id_front.jpg',
    'idBackUrl' => 'https://storage.example.com/documents/id_back.jpg',
    'selfieUrl' => 'https://storage.example.com/documents/selfie.jpg'
];

$response = file_get_contents(
    "https://api.fyatu.com/api/v3/cardholders/{$cardholderId}/kyc",
    false,
    stream_context_create([
        'http' => [
            'method' => 'POST',
            'header' => [
                'Authorization: Bearer ' . $accessToken,
                'Content-Type: application/json'
            ],
            'content' => json_encode($data)
        ]
    ])
);

$result = json_decode($response, true);
echo "KYC Status: " . $result['data']['kycStatus'] . "\n";

​
Example Response

{
  "success": true,
  "status": 200,
  "message": "KYC documents submitted successfully",
  "data": {
    "id": "ch_1a2b3c4d5e6f7890abcdef1234567890",
    "kycStatus": "PENDING",
    "message": "KYC documents submitted successfully. Verification is pending."
  },
  "meta": {
    "requestId": "req_kyc123abc",
    "timestamp": "2026-01-08T17:00:00+00:00"
  }
}

​
KYC Status Flow

UNSUBMITTED → PENDING → VERIFIED
      ↑              ↘ REJECTED
      └────────────────┘
StatusDescriptionCan Submit
UNSUBMITTEDNo documents submitted yetYes
PENDINGDocuments submitted, awaiting reviewNo
VERIFIEDVerification completed successfullyNo
REJECTEDVerification failed - may resubmitYes

​
Error Responses

​
Already Verified (409)

{
  "success": false,
  "status": 409,
  "message": "KYC is already verified for this cardholder",
  "error": { "code": "KYC_ALREADY_VERIFIED" }
}

​
Already Pending (409)

{
  "success": false,
  "status": 409,
  "message": "KYC documents are already pending review",
  "error": { "code": "KYC_PENDING" }
}

​
Invalid URLs (400)

{
  "success": false,
  "status": 400,
  "message": "Validation failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      { "field": "idFrontUrl", "message": "The idFrontUrl field must contain a valid URL." }
    ]
  }
}

​
Invalid Image (400)

{
  "success": false,
  "status": 400,
  "message": "Validation failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      { "field": "idFrontUrl", "message": "URL must point to a valid image (JPEG, PNG, GIF, or WebP)" }
    ]
  }
}

​
Image Too Large (400)

{
  "success": false,
  "status": 400,
  "message": "Validation failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      { "field": "idFrontUrl", "message": "Image size (7.5MB) exceeds maximum allowed (5MB)" }
    ]
  }
}
Once KYC is verified, you cannot resubmit documents. If you need to update verification documents, contact support.
Use a cloud storage service (AWS S3, Google Cloud Storage, etc.) to host your document images and provide publicly accessible URLs.

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