Skip to main content
POST
/
cardholders
/
{id}
/
kyc
Initiate KYC
curl --request POST \
  --url https://api.fyatu.com/api/v3.20/cardholders/{id}/kyc \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "kycDocument": {
    "documentType": "PASSPORT",
    "documentNumber": "AB123456",
    "issuingCountry": "US",
    "dateOfBirth": "1990-06-15",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  }
}
'
{
  "success": true,
  "status": 201,
  "message": "KYC initiated",
  "data": {
    "cardholderId": "chl_01HXYZ1234ABCDEF5678",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "status": "ACTIVE",
    "kycStatus": "PENDING",
    "environment": "LIVE",
    "totalCards": 1,
    "createdAt": "2026-05-22T09:00:00Z",
    "updatedAt": "2026-05-25T11:30:00Z"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-25T11:30:00Z"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Cardholders are created with kycStatus: WAIVED by default, allowing them to issue cards immediately. This endpoint upgrades a cardholder to full KYC verification — transitioning them to PENDING and submitting their data to the verification provider asynchronously. Use this when your compliance requirements demand verified identity before a cardholder can transact above certain limits, or when prompted by the card program’s terms.

​
When to Call This

  • The cardholder’s kycStatus is WAIVED or PENDING (not yet approved)
  • You want to move the cardholder toward APPROVED status for higher transaction limits

​
Request Body

All fields are optional. If you have already submitted kycDocument data during cardholder creation or a prior KYC attempt, you do not need to resend it.
FieldTypeRequiredDescription
kycDocumentobjectNoStructured KYC data for the cardholder (ID info, address, etc.)
The shape of kycDocument is flexible and passed through to the verification provider. Common fields:
FieldTypeDescription
documentTypestringPASSPORT, NATIONAL_ID, or DRIVER_LICENSE
documentNumberstringThe document’s identifier number
issuingCountrystringISO 3166-1 alpha-2 country code
dateOfBirthstringYYYY-MM-DD format
addressobject{ street, city, state, postalCode, country }

​
Example

curl -X POST "https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678/kyc" \
  -H "Authorization: Bearer $FYATU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kycDocument": {
      "documentType":   "PASSPORT",
      "documentNumber": "AB123456",
      "issuingCountry": "US",
      "dateOfBirth":    "1990-06-15",
      "address": {
        "street":     "123 Main St",
        "city":       "New York",
        "state":      "NY",
        "postalCode": "10001",
        "country":    "US"
      }
    }
  }'

​
Success Response (201)

{
  "success": true,
  "status": 201,
  "message": "KYC initiated",
  "data": {
    "cardholderId": "chl_01HXYZ1234ABCDEF5678",
    "firstName":    "John",
    "lastName":     "Smith",
    "email":        "john.smith@example.com",
    "phone":        "+12125551234",
    "status":       "ACTIVE",
    "kycStatus":    "PENDING",
    "environment":  "LIVE",
    "totalCards":   1,
    "createdAt":    "2026-05-22T09:00:00Z",
    "updatedAt":    "2026-05-25T11:30:00Z"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform":  "Fyatu CaaS",
    "timestamp": "2026-05-25T11:30:00Z"
  }
}

​
What Happens Next

The KYC submission is processed asynchronously:
  1. The cardholder’s kycStatus is set to PENDING immediately.
  2. The submitted data is forwarded to the card provider for identity verification.
  3. Once the provider responds, a webhook is dispatched:
{
  "event":      "CARDHOLDER_KYC_APPROVED",
  "eventId":    "evt_01HXY123456ABCDEF",
  "businessId": "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":  "2026-05-25T11:35:00Z",
  "data": {
    "cardholderId": "chl_01HXYZ1234ABCDEF5678",
    "kycStatus":    "APPROVED"
  }
}
Cardholders with kycStatus: WAIVED can already issue cards. KYC approval is only required if your program mandates it for higher transaction limits.

​
Error Codes

CodeHTTPCause
CARDHOLDER_NOT_FOUND404Cardholder does not exist or belongs to another business
KYC_ALREADY_APPROVED409Cardholder’s KYC is already APPROVED — no action needed
CARDHOLDER_TERMINATED422Cardholder has been terminated and cannot be updated
INSUFFICIENT_SCOPE403Key lacks cardholders:write scope
INTERNAL_ERROR500Server error

Authorizations

​
Authorization
string
header
required

API key from the FYATU CaaS portal. Pass as Authorization: Bearer <key>.

Path Parameters

​
id
string
required

Cardholder ID

Body

application/json
​
kycDocument
object

Structured KYC data forwarded to the verification provider. All sub-fields are optional.

Response

KYC initiated — cardholder kycStatus is now PENDING

​
success
boolean
Example:

true

​
status
integer
Example:

200

​
message
string
Example:

"Cardholder retrieved"

​
data
object
​
meta
object