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"
}
}
}
'import requests
url = "https://api.fyatu.com/api/v3.20/cardholders/{id}/kyc"
payload = { "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"
}
} }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'
}
}
})
};
fetch('https://api.fyatu.com/api/v3.20/cardholders/{id}/kyc', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.fyatu.com/api/v3.20/cardholders/{id}/kyc",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.fyatu.com/api/v3.20/cardholders/{id}/kyc"
payload := strings.NewReader("{\n \"kycDocument\": {\n \"documentType\": \"PASSPORT\",\n \"documentNumber\": \"AB123456\",\n \"issuingCountry\": \"US\",\n \"dateOfBirth\": \"1990-06-15\",\n \"address\": {\n \"street\": \"123 Main St\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postalCode\": \"10001\",\n \"country\": \"US\"\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.fyatu.com/api/v3.20/cardholders/{id}/kyc")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"kycDocument\": {\n \"documentType\": \"PASSPORT\",\n \"documentNumber\": \"AB123456\",\n \"issuingCountry\": \"US\",\n \"dateOfBirth\": \"1990-06-15\",\n \"address\": {\n \"street\": \"123 Main St\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postalCode\": \"10001\",\n \"country\": \"US\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fyatu.com/api/v3.20/cardholders/{id}/kyc")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"kycDocument\": {\n \"documentType\": \"PASSPORT\",\n \"documentNumber\": \"AB123456\",\n \"issuingCountry\": \"US\",\n \"dateOfBirth\": \"1990-06-15\",\n \"address\": {\n \"street\": \"123 Main St\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postalCode\": \"10001\",\n \"country\": \"US\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"status": 201,
"message": "KYC initiated",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"firstName": "John",
"lastName": "Smith",
"email": "john.smith@example.com",
"status": "ACTIVE",
"kycStatus": "PENDING",
"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"
}
}Initiate KYC
Initiate full KYC verification for a cardholder. POST /cardholders//kyc. Requires cardholders:write scope.
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"
}
}
}
'import requests
url = "https://api.fyatu.com/api/v3.20/cardholders/{id}/kyc"
payload = { "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"
}
} }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'
}
}
})
};
fetch('https://api.fyatu.com/api/v3.20/cardholders/{id}/kyc', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.fyatu.com/api/v3.20/cardholders/{id}/kyc",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.fyatu.com/api/v3.20/cardholders/{id}/kyc"
payload := strings.NewReader("{\n \"kycDocument\": {\n \"documentType\": \"PASSPORT\",\n \"documentNumber\": \"AB123456\",\n \"issuingCountry\": \"US\",\n \"dateOfBirth\": \"1990-06-15\",\n \"address\": {\n \"street\": \"123 Main St\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postalCode\": \"10001\",\n \"country\": \"US\"\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.fyatu.com/api/v3.20/cardholders/{id}/kyc")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"kycDocument\": {\n \"documentType\": \"PASSPORT\",\n \"documentNumber\": \"AB123456\",\n \"issuingCountry\": \"US\",\n \"dateOfBirth\": \"1990-06-15\",\n \"address\": {\n \"street\": \"123 Main St\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postalCode\": \"10001\",\n \"country\": \"US\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fyatu.com/api/v3.20/cardholders/{id}/kyc")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"kycDocument\": {\n \"documentType\": \"PASSPORT\",\n \"documentNumber\": \"AB123456\",\n \"issuingCountry\": \"US\",\n \"dateOfBirth\": \"1990-06-15\",\n \"address\": {\n \"street\": \"123 Main St\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postalCode\": \"10001\",\n \"country\": \"US\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"status": 201,
"message": "KYC initiated",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"firstName": "John",
"lastName": "Smith",
"email": "john.smith@example.com",
"status": "ACTIVE",
"kycStatus": "PENDING",
"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"
}
}Overview
Cardholders are created withkycStatus: 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
kycStatusisWAIVEDorPENDING(not yet approved) - You want to move the cardholder toward
APPROVEDstatus for higher transaction limits
Request Body
All fields are optional. If you have already submittedkycDocument data during cardholder creation or a prior KYC attempt, you do not need to resend it.
| Field | Type | Required | Description |
|---|---|---|---|
kycDocument | object | No | Structured KYC data for the cardholder (ID info, address, etc.) |
kycDocument is flexible and passed through to the verification provider. Common fields:
| Field | Type | Description |
|---|---|---|
documentType | string | PASSPORT, NATIONAL_ID, or DRIVER_LICENSE |
documentNumber | string | The document’s identifier number |
issuingCountry | string | ISO 3166-1 alpha-2 country code |
dateOfBirth | string | YYYY-MM-DD format |
address | object | { 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"
}
}
}'
const resp = await fetch(
`https://api.fyatu.com/api/v3.20/cardholders/${cardholderId}/kyc`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.FYATU_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
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'
}
}
})
}
);
const body = await resp.json();
console.log('KYC status:', body.data.kycStatus); // "PENDING"
import os, requests
resp = requests.post(
f'https://api.fyatu.com/api/v3.20/cardholders/{cardholder_id}/kyc',
headers={'Authorization': f'Bearer {os.environ["FYATU_API_KEY"]}'},
json={
'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'
}
}
}
)
data = resp.json()['data']
print('KYC status:', data['kycStatus']) # PENDING
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",
"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:- The cardholder’s
kycStatusis set toPENDINGimmediately. - The submitted data is forwarded to the card provider for identity verification.
- 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
| Code | HTTP | Cause |
|---|---|---|
CARDHOLDER_NOT_FOUND | 404 | Cardholder does not exist or belongs to another business |
KYC_ALREADY_APPROVED | 409 | Cardholder’s KYC is already APPROVED — no action needed |
CARDHOLDER_TERMINATED | 422 | Cardholder has been terminated and cannot be updated |
INSUFFICIENT_SCOPE | 403 | Key lacks cardholders:write scope |
INTERNAL_ERROR | 500 | Server error |
Authorizations
API key from the FYATU CaaS portal. Pass as Authorization: Bearer <key>.
Path Parameters
Cardholder ID
Body
application/json
Structured KYC data forwarded to the verification provider. All sub-fields are optional.
Show child attributes
Show child attributes
⌘I

