Submit a cardholder to a BIN
curl --request POST \
--url https://api.fyatu.com/api/v3.20/cardholders/{id}/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"binCode": "HK-MC-V-01"
}
'import requests
url = "https://api.fyatu.com/api/v3.20/cardholders/{id}/submit"
payload = { "binCode": "HK-MC-V-01" }
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({binCode: 'HK-MC-V-01'})
};
fetch('https://api.fyatu.com/api/v3.20/cardholders/{id}/submit', 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}/submit",
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([
'binCode' => 'HK-MC-V-01'
]),
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}/submit"
payload := strings.NewReader("{\n \"binCode\": \"HK-MC-V-01\"\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}/submit")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"binCode\": \"HK-MC-V-01\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fyatu.com/api/v3.20/cardholders/{id}/submit")
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 \"binCode\": \"HK-MC-V-01\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Cardholder submitted",
"data": {
"submission": {
"binCode": "HK-MC-V-01",
"submitted": true,
"verificationStatus": "IN_REVIEW",
"message": "Submitted. Verification is under review for this BIN and usually completes within a day."
}
}
}Cardholders
Submit to a BIN
Register a cardholder on one BIN. POST /cardholders//submit. Requires cardholders:write scope.
POST
/
cardholders
/
{id}
/
submit
Submit a cardholder to a BIN
curl --request POST \
--url https://api.fyatu.com/api/v3.20/cardholders/{id}/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"binCode": "HK-MC-V-01"
}
'import requests
url = "https://api.fyatu.com/api/v3.20/cardholders/{id}/submit"
payload = { "binCode": "HK-MC-V-01" }
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({binCode: 'HK-MC-V-01'})
};
fetch('https://api.fyatu.com/api/v3.20/cardholders/{id}/submit', 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}/submit",
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([
'binCode' => 'HK-MC-V-01'
]),
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}/submit"
payload := strings.NewReader("{\n \"binCode\": \"HK-MC-V-01\"\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}/submit")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"binCode\": \"HK-MC-V-01\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fyatu.com/api/v3.20/cardholders/{id}/submit")
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 \"binCode\": \"HK-MC-V-01\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Cardholder submitted",
"data": {
"submission": {
"binCode": "HK-MC-V-01",
"submitted": true,
"verificationStatus": "IN_REVIEW",
"message": "Submitted. Verification is under review for this BIN and usually completes within a day."
}
}
}Overview
Registers a cardholder on one 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 as well. This is why a cardholder can be issuable from one BIN of a programme and refused on its neighbour, and why the answer inprogramEligibility is given per BIN.
When to call this
Read the cardholder and look atprogramEligibility[].bins[]. A BIN you can act on carries
canSubmit: true — typically one of:
verificationStatus | What it means | What this call does |
|---|---|---|
NOT_SUBMITTED | The BIN has no record of this cardholder — commonly a BIN added to your products after the cardholder was created | Registers them and starts the review |
REJECTED | The BIN reviewed this cardholder and declined. verificationMessage says why | Sends the corrected details for a fresh review |
IN_REVIEW is already being looked at, and a VERIFIED one is done — neither carries
canSubmit, and submitting to them does nothing you want. Registering the same identity twice on
one BIN is refused by the issuer.
Your own verification comes first. A cardholder whose
kycStatus is not APPROVED is refused
here with 409 KYC_NOT_APPROVED — nothing is sent to a BIN for review until we have completed our
own check, so that a decision made there means something.Request Body
| Field | Type | Required | Description |
|---|---|---|---|
binCode | string | Yes | The BIN to register on, exactly as given in programEligibility[].bins[].binCode |
Response
The cardholder, withprogramEligibility recomputed — so one read tells you where every BIN now
stands — plus a submission object for the BIN you named.
| Field | Description |
|---|---|
submission.submitted | Whether the BIN was written to. false with a message is a submission that was stopped before it got there, or one that did not land |
submission.verificationStatus | Where that BIN stands now |
submission.message | What happened, and what to do next |
IN_REVIEW; the outcome arrives on the
cardholder.updated webhook rather than on this response.
Example
curl -X POST https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678/submit \
-H "Authorization: Bearer $FYATU_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "binCode": "HK-MC-V-01" }'
const res = await fetch(
'https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678/submit',
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.FYATU_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ binCode: 'HK-MC-V-01' }),
}
)
const { data } = await res.json()
console.log(data.submission.verificationStatus) // "IN_REVIEW"
import os, requests
res = requests.post(
"https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678/submit",
headers={"Authorization": f"Bearer {os.environ['FYATU_API_KEY']}"},
json={"binCode": "HK-MC-V-01"},
)
print(res.json()["data"]["submission"]["verificationStatus"])
Registering on every BIN that needs it
There is no “submit everywhere” call: each BIN is a separate registration and a separate review, and submitting to all of them when one is outstanding spends a review on each of the others. Walk the ones that are actually open:const { data: cardholder } = await (
await fetch(`https://api.fyatu.com/api/v3.20/cardholders/${id}`, { headers })
).json()
const pending = (cardholder.programEligibility ?? [])
.flatMap((p) => p.bins ?? [])
.filter((b) => b.canSubmit)
for (const bin of pending) {
await fetch(`https://api.fyatu.com/api/v3.20/cardholders/${id}/submit`, {
method: 'POST',
headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({ binCode: bin.binCode }),
})
}
Errors
| Status | Code | Meaning |
|---|---|---|
400 | INVALID_REQUEST | binCode is missing |
404 | CARDHOLDER_NOT_FOUND | No such cardholder on your account in this environment |
409 | KYC_NOT_APPROVED | Our own verification of this cardholder has not concluded |
409 | CARDHOLDER_TERMINATED | The cardholder is terminated |
422 | BIN_NOT_AVAILABLE | None of your products issue from that BIN |
Authorizations
API key from the FYATU CaaS portal. Pass as Authorization: Bearer <key>.
Path Parameters
The cardholder ID (prefix chl_)
Body
application/json
The BIN to register this cardholder on, as given in programEligibility[].bins[].binCode.
Example:
"HK-MC-V-01"

