> ## 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.
# Submit to a BIN
> Register a cardholder on one BIN. POST /cardholders/{id}/submit. Requires cardholders:write scope.
## 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 in [`programEligibility`](/v3.20/api-reference/cardholders/get) is given per BIN.
## When to call this
Read the cardholder and look at `programEligibility[].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 |
A BIN reading `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, with `programEligibility` 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 |
A submission that reaches a reviewer usually comes back `IN_REVIEW`; the outcome arrives on the
`cardholder.updated` webhook rather than on this response.
## Example
```bash cURL theme={null}
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" }'
```
```javascript Node.js theme={null}
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"
```
```python Python theme={null}
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:
```javascript theme={null}
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 |
## OpenAPI
````yaml v3.20/openapi.json POST /cardholders/{id}/submit
openapi: 3.1.0
info:
title: FYATU CaaS API v3.20
description: >-
FYATU Cards-as-a-Service API — API key authentication, Cardholder
lifecycle, Card issuance, Transactions, Webhooks, and Programs.
version: 3.20.0
contact:
name: FYATU Support
url: https://fyatu.com
email: support@fyatu.com
servers:
- url: https://api.fyatu.com/api/v3.20
description: >-
FYATU CaaS API — the environment (LIVE or SANDBOX) is determined by the
API key, not the URL
security:
- BearerAuth: []
tags:
- name: Meta
description: Liveness, account info, and supported event types
- name: Account
description: Account-level balance and funding status
- name: Programs
description: Read card program configuration
- name: Cardholders
description: Create and manage cardholder profiles
- name: Cards
description: Issue, fund, freeze, and terminate virtual cards
- name: Transactions
description: Read-only card transaction history
- name: Webhooks
description: Manage webhook endpoints for real-time event delivery
- name: Products
description: Read card product configurations
paths:
/cardholders/{id}/submit:
post:
tags:
- Cardholders
summary: Submit a cardholder to a BIN
description: >-
Registers this 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 too.
`programEligibility` on GET /cardholders/{id} reports where each BIN
stands and marks the ones this can act on with `canSubmit`.
operationId: submitCardholderToBin
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The cardholder ID (prefix `chl_`)
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- binCode
properties:
binCode:
type: string
description: >-
The BIN to register this cardholder on, as given in
`programEligibility[].bins[].binCode`.
example: HK-MC-V-01
responses:
'200':
description: >-
Submitted. The cardholder carries the recomputed eligibility, and
`submission` says what this BIN did.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Cardholder submitted
data:
type: object
properties:
submission:
type: object
properties:
binCode:
type: string
example: HK-MC-V-01
submitted:
type: boolean
description: >-
Whether the BIN was written to. False with a
message is a submission that was stopped or did
not land.
example: true
verificationStatus:
type: string
enum:
- NOT_SUBMITTED
- IN_REVIEW
- REJECTED
- VERIFIED
example: IN_REVIEW
message:
type: string
description: What happened, and what to do next.
example: >-
Submitted. Verification is under review for this
BIN and usually completes within a day.
'400':
description: '`binCode` is required'
'404':
description: Cardholder not found
'409':
description: >-
The cardholder is terminated, or has not completed verification with
us yet (`KYC_NOT_APPROVED`)
'422':
description: This BIN is not available on your products (`BIN_NOT_AVAILABLE`)
security:
- BearerAuth: []
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
API key from the FYATU CaaS portal. Pass as `Authorization: Bearer
`.
````