Get Cardholder

Get a cardholder

curl --request GET \
  --url https://api.fyatu.com/api/v3.20/cardholders/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.fyatu.com/api/v3.20/cardholders/{id}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fyatu.com/api/v3.20/cardholders/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.fyatu.com/api/v3.20/cardholders/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "status": 200,
  "message": "Cardholder retrieved",
  "data": {
    "cardholderId": "chl_01HXYZ1234ABCDEF5678",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "phone": "+12025551234",
    "dateOfBirth": "1990-05-15",
    "nationality": "US",
    "gender": "MALE",
    "address": {
      "address": "123 Main Street, Apt 4B",
      "city": "Newark",
      "country": "US",
      "state": "Delaware",
      "postalCode": "19701"
    },
    "kycDocument": {
      "documentType": "PASSPORT",
      "documentNumber": "AB123456",
      "issuingCountry": "US",
      "issuingDate": "2019-03-04",
      "expiryDate": "2029-03-03",
      "frontUrl": "https://storage.example.com/doc-front.jpg",
      "backUrl": null,
      "selfieUrl": "https://storage.example.com/selfie.jpg"
    },
    "externalId": "usr_123456",
    "metadata": {
      "plan": "premium"
    },
    "status": "ACTIVE",
    "kycStatus": "APPROVED",
    "kycVerifiedAt": "2026-05-10T14:23:00Z",
    "kycRejectionReason": null,
    "totalCards": 2,
    "suspendedAt": null,
    "terminatedAt": null,
    "createdAt": "2026-05-01T09:00:00Z",
    "updatedAt": "2026-05-10T14:23:00Z",
    "programEligibility": [
      {
        "programCode": "FYT-USD-02",
        "programName": "USD Global Tier 2",
        "eligible": false,
        "requiresVerification": true,
        "reason": "<string>",
        "bins": [
          {
            "binCode": "SG-VISA-V-01",
            "binName": "Virtual Card - Singapore BIN",
            "bin": "49372410",
            "issuingCountry": "SG",
            "scheme": "VISA",
            "formFactor": "VIRTUAL",
            "requiresVerification": true,
            "eligible": true,
            "reason": "<string>",
            "verificationStatus": "NOT_SUBMITTED",
            "canSubmit": true,
            "verificationMessage": "<string>"
          }
        ]
      }
    ]
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6a7b8c9d0e1f2",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T15:00:00Z"
  }
}

GET

cardholders

{id}

Get a cardholder

curl --request GET \
  --url https://api.fyatu.com/api/v3.20/cardholders/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.fyatu.com/api/v3.20/cardholders/{id}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fyatu.com/api/v3.20/cardholders/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.fyatu.com/api/v3.20/cardholders/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "status": 200,
  "message": "Cardholder retrieved",
  "data": {
    "cardholderId": "chl_01HXYZ1234ABCDEF5678",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "phone": "+12025551234",
    "dateOfBirth": "1990-05-15",
    "nationality": "US",
    "gender": "MALE",
    "address": {
      "address": "123 Main Street, Apt 4B",
      "city": "Newark",
      "country": "US",
      "state": "Delaware",
      "postalCode": "19701"
    },
    "kycDocument": {
      "documentType": "PASSPORT",
      "documentNumber": "AB123456",
      "issuingCountry": "US",
      "issuingDate": "2019-03-04",
      "expiryDate": "2029-03-03",
      "frontUrl": "https://storage.example.com/doc-front.jpg",
      "backUrl": null,
      "selfieUrl": "https://storage.example.com/selfie.jpg"
    },
    "externalId": "usr_123456",
    "metadata": {
      "plan": "premium"
    },
    "status": "ACTIVE",
    "kycStatus": "APPROVED",
    "kycVerifiedAt": "2026-05-10T14:23:00Z",
    "kycRejectionReason": null,
    "totalCards": 2,
    "suspendedAt": null,
    "terminatedAt": null,
    "createdAt": "2026-05-01T09:00:00Z",
    "updatedAt": "2026-05-10T14:23:00Z",
    "programEligibility": [
      {
        "programCode": "FYT-USD-02",
        "programName": "USD Global Tier 2",
        "eligible": false,
        "requiresVerification": true,
        "reason": "<string>",
        "bins": [
          {
            "binCode": "SG-VISA-V-01",
            "binName": "Virtual Card - Singapore BIN",
            "bin": "49372410",
            "issuingCountry": "SG",
            "scheme": "VISA",
            "formFactor": "VIRTUAL",
            "requiresVerification": true,
            "eligible": true,
            "reason": "<string>",
            "verificationStatus": "NOT_SUBMITTED",
            "canSubmit": true,
            "verificationMessage": "<string>"
          }
        ]
      }
    ]
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6a7b8c9d0e1f2",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T15:00:00Z"
  }
}

Overview

Returns the full profile of a single cardholder, including address, KYC status, and which programmes can issue for it. The kycRejectionReason field is only present when kycStatus is REJECTED. The terminatedAt field is only present when status is TERMINATED.

KYC Status

Status	Meaning	Can be issued a card
`WAIVED`	Your plan does not require cardholder verification. Not verified — supply a `kycDocument` to have this cardholder verified	On programmes that require no verification
`PENDING`	Created, nothing submitted for verification yet	No
`SUBMITTED`	Sent for verification, awaiting an answer	On programmes that require no verification
`APPROVED`	Verified	On every programme
`REJECTED`	Verification was unsuccessful. `PATCH` the cardholder to correct it and it is checked again	No

A WAIVED cardholder is not a verified one. It can hold cards on programmes that ask for no cardholder verification, and adding a kycDocument starts verification so the rest open too.

Programme Eligibility

programEligibility answers whether this cardholder can be issued a card — per BIN, and summarised per programme. It is returned on this endpoint only, not on GET /cardholders. The BIN is where the decision is made. BINs on one programme do not agree about what they require: a programme can hold one BIN that issues to an unverified cardholder alongside others that do not. A programme is eligible when at least one of its BINs is.

"programEligibility": [
  {
    "programCode": "FYT-USD-01",
    "programName": "USD Virtual - Global",
    "eligible": true,
    "requiresVerification": false,
    "bins": [
      {
        "binCode": "US-VISA-V-01",
        "binName": "Virtual Card - Visa",
        "bin": "493724",
        "issuingCountry": "US",
        "scheme": "VISA",
        "formFactor": "VIRTUAL",
        "requiresVerification": false,
        "eligible": true
      }
    ]
  },
  {
    "programCode": "FYT-USD-02",
    "programName": "USD Multi-Region - Visa & Mastercard",
    "eligible": true,
    "requiresVerification": true,
    "bins": [
      {
        "binCode": "SG-VISA-V-01",
        "binName": "Virtual Card - Singapore BIN",
        "bin": "49372410",
        "issuingCountry": "SG",
        "scheme": "VISA",
        "formFactor": "VIRTUAL",
        "requiresVerification": false,
        "eligible": true
      },
      {
        "binCode": "HK-MC-V-01",
        "binName": "Virtual Card - Hong Kong BIN (Mastercard)",
        "bin": "524013",
        "issuingCountry": "HK",
        "scheme": "MASTERCARD",
        "formFactor": "VIRTUAL",
        "requiresVerification": true,
        "eligible": false,
        "reason": "Needs a verified cardholder. Add identity documents to have this one verified.",
        "verificationStatus": "NOT_SUBMITTED",
        "canSubmit": true
      }
    ]
  }
]

Field	Description
`eligible`	On a BIN, whether a card can be issued from it right now. On a programme, whether any of its BINs can
`requiresVerification`	On a BIN, whether it needs a verified cardholder. On a programme, whether any of its BINs does — a summary, which does not by itself close the programme
`bins`	Every issuable BIN on the programme, each with its own answer
`bin`	The BIN number, as printed on cards issued from it. Absent where the registry has no number recorded
`issuingCountry`	ISO 3166-1 alpha-2 country the BIN issues from
`reason`	Present only when not eligible; says what to do
`verificationStatus`	Where this BIN’s own verification stands: `NOT_SUBMITTED`, `IN_REVIEW`, `REJECTED` or `VERIFIED`. Absent on a BIN that requires no verification
`canSubmit`	Whether submitting this cardholder to this BIN would do anything now. Absent once verified, and while your own verification has not concluded
`verificationMessage`	What came back about this cardholder on this BIN — why a review failed. Absent when nothing was said

A cardholder is registered per BIN

Verification is not held once for your account. The issuers behind different BINs each keep their own record of a cardholder and run their own check, so a cardholder verified for one BIN is unknown to the next and has to be registered there too. That is why the answer is per BIN, and why verificationStatus can differ across BINs of the same programme: one VERIFIED, its neighbour NOT_SUBMITTED. A cardholder’s own kycStatus is our verification of them and answers for neither. Where canSubmit is true, POST /cardholders/{id}/submit registers them on that BIN.

What a BIN expects

A BIN that requires verification takes an APPROVED cardholder and nothing else. A BIN that requires none still defers to your account’s KYC module — what you undertook to do about your own cardholders. Each module admits strictly less than the one above it:

Your KYC module	Cardholder statuses that can be issued from a no-verification BIN
Minimal	`WAIVED`, `SUBMITTED`, `APPROVED`
Shared	`SUBMITTED`, `APPROVED`
Managed	`APPROVED`

PENDING and REJECTED are never eligible under any module: nothing has been submitted in the first case, and a failed check is not an absent one in the second.

Country restrictions are separate and are applied when a card is issued, not here. A cardholder whose nationality or country of residence is restricted on a product’s BIN is refused with 422 CARDHOLDER_COUNTRY_RESTRICTED, naming the country.

Path Parameters

Parameter	Type	Description
`id`	string	The cardholder ID (prefix `chl_`)

Example

curl https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678 \
  -H "Authorization: Bearer $FYATU_API_KEY"

const resp = await fetch(
  'https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678',
  { headers: { 'Authorization': `Bearer ${process.env.FYATU_API_KEY}` } }
);
const body = await resp.json();
const cardholder = body.data;
console.log(cardholder.kycStatus);   // "APPROVED"
console.log(cardholder.totalCards);  // 2

import os, requests

resp = requests.get(
    'https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678',
    headers={'Authorization': f'Bearer {os.environ["FYATU_API_KEY"]}'}
)
cardholder = resp.json()['data']
print(cardholder['kycStatus'])

Success Response (200)

{
  "success": true,
  "status": 200,
  "message": "Cardholder retrieved",
  "data": {
    "cardholderId":  "chl_01HXYZ1234ABCDEF5678",
    "firstName":     "John",
    "lastName":      "Smith",
    "email":         "john.smith@example.com",
    "phone":         "+12025551234",
    "dateOfBirth":   "1990-05-15",
    "nationality":   "US",
    "address": {
      "address":    "123 Main Street, Apt 4B",
      "city":       "Newark",
      "state":      "Delaware",
      "postalCode": "19701",
      "country":    "US"
    },
    "kycDocument":   null,
    "externalId":    "usr_123456",
    "metadata":      { "plan": "premium" },
    "status":        "ACTIVE",
    "kycStatus":     "APPROVED",
    "gender":        "MALE",
    "kycVerifiedAt": "2026-05-01T09:05:00Z",
    "totalCards":    2,
    "suspendedAt":   null,
    "createdAt":     "2026-05-01T09:00:00Z",
    "updatedAt":     "2026-05-01T09:05:00Z"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}

Conditional Fields

Field	Present when
`kycRejectionReason`	`kycStatus` is `REJECTED`
`kycVerifiedAt`	Set when `kycStatus` is `APPROVED` or `WAIVED` (the verification/waiver timestamp); `null` for `PENDING` and `REJECTED`
`terminatedAt`	`status` is `TERMINATED`

KYC Waived Example

Cardholders created via the API are WAIVED immediately — the cardholder has not been identity-verified but is allowed to hold cards. kycVerifiedAt carries the timestamp at which KYC was waived.

{
  "success": true,
  "status": 200,
  "message": "Cardholder retrieved",
  "data": {
    "cardholderId":  "chl_01HXYZ1234ABCDEF5678",
    "kycStatus":     "WAIVED",
    "kycVerifiedAt": "2026-05-25T10:00:00Z"
  },
  "meta": { "requestId": "req_01HXY123456ABCDEF", "platform": "Fyatu CaaS", "timestamp": "2026-05-25T10:00:00Z" }
}

KYC Rejected Example

{
  "success": true,
  "status": 200,
  "message": "Cardholder retrieved",
  "data": {
    "cardholderId":      "chl_01HXYZ1234ABCDEF5678",
    "kycStatus":         "REJECTED",
    "kycRejectionReason": "Document expired or unreadable",
    "kycVerifiedAt":     null
  },
  "meta": { "requestId": "req_01HXY123456ABCDEF", "platform": "Fyatu CaaS", "timestamp": "2026-05-22T10:00:00Z" }
}

Error Codes

Code	HTTP	Cause
`CARDHOLDER_NOT_FOUND`	404	Cardholder does not exist or belongs to another business
`INSUFFICIENT_SCOPE`	403	Key lacks `cardholders:read` scope

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

Response

Cardholder retrieved

success

boolean

Example:

true

status

integer

Example:

200

message

string

Example:

"Cardholder retrieved"

data

object

Show child attributes

Account

Products

Cardholders

Cards

Webhooks

Overview

KYC Status

Programme Eligibility

A cardholder is registered per BIN

What a BIN expects

Path Parameters

Example

Success Response (200)

Conditional Fields

KYC Waived Example

KYC Rejected Example

Error Codes

Authorizations

Path Parameters

Response

​Overview

​KYC Status

​Programme Eligibility

​A cardholder is registered per BIN

​What a BIN expects

​Path Parameters

​Example

​Success Response (200)

​Conditional Fields

​KYC Waived Example

​KYC Rejected Example

​Error Codes

Authorizations

Path Parameters

Response

Overview

KYC Status

Programme Eligibility

A cardholder is registered per BIN

What a BIN expects

Path Parameters

Example

Success Response (200)

Conditional Fields

KYC Waived Example

KYC Rejected Example

Error Codes