KYC
Before a customer can hold a card, NAS verifies who they are. You collect their details and images, send them through this API, and read the result.
NAS does not accept verification share tokens from other identity providers. Send the real personal data and the real document and selfie images through this API. The image fields take file ids from the upload call and nothing else.
How it works
- Upload the ID document images and a selfie. You get a file id for each.
- Submit the customer's details with those file ids.
- Read the result, by webhook or by polling.
- Create the cardholder when the result is
PASSED.
Each account is verified for one person. Later submissions on the same account must name the same person. NAS refuses a submission that names someone else (NB40310), and one that names a person already verified on another account (NB40311).
Step 1 — Upload the images
Call Upload files. It takes multipart/form-data with the accountId and one or more files.
| Rule | Limit |
|---|---|
| Files per call | 1 to 10 |
| Size of one file | 10 MB |
| Size of one call | 25 MB |
| File types | jpg, jpeg, png, gif, bmp, svg, ico, webp, pdf, doc, docx, xls, xlsx, ppt, pptx, txt, zip, rar, 7z, tar, gz |
| File names | Letters, digits, spaces and . _ - ( ) only. Up to 200 characters. Not starting with a dot. |
| Empty files | Refused |
Send ID documents and selfies as jpg or png. A call that breaks a rule is refused with NB40002 and a message that names the problem. A file over the size limit is refused the same way.
curl -X POST "https://sandbox-api.nas.cards/open-api/v3/files/upload" \
-H "x-access-token: $ACCESS_TOKEN" \
-F "accountId=$ACCOUNT_ID" \
-F "files=@id-front.jpg"
{
"code": "000000",
"message": "success",
"data": [
{ "id": "1234567890", "accountId": "ba0a5c6d-ee96-4c44-82f1-dc306d325d8e", "createTime": "1754994030000" }
]
}
Upload one image per call. The answer holds only the file id, so one image per call is the way to know which id is which.
Image rules
Poor images are the most common reason a review fails.
Selfie
- The applicant takes it themselves, and it matches the ID document.
- The whole face is clear, in focus and well lit, and neither too close nor too far from the camera.
- No masks or hats. Avoid glasses where you can.
- Do not send edited, filtered, composited or generated images, or a photo taken by someone else. NAS checks the image itself, so a still taken from a screen or a gallery can fail.
ID document
- Show the whole document, valid and not expired, in a clear, straight-on photo.
- Do not send a photo of a printed copy or a screenshot.
- Do not cover or mark any part of the document.
Step 2 — Submit the details
Call Submit account KYC with the accountId in the path.
| Field | Notes |
|---|---|
firstName, lastName | As printed on the document. English letters only. |
dateOfBirth | YYYY-MM-DD. |
gender | M or F. |
nationality | Two-letter country code (ISO 3166-1 alpha-2). |
nationalId | The ID number on the document. |
idType | One of PASSPORT, CN-RIC, HK-HKID, DLN, Government-Issued ID Card, EU Residency Permit, UAE Residency Permit. The country must support the document type you pick. |
issueDate, expiryDate | YYYY-MM-DD. The document must not be expired. |
address | addressLine1, city, state, country, postalCode required. English letters, digits and common symbols. For the US and Canada, state is the two-letter code. |
idFrontId | File id of the front of the ID. |
idBackId | File id of the back. Not needed for a passport. |
selfie | File id of the selfie. |
phoneCountryCode, phoneNumber | Dialling code without +, and the number without the code. |
ssn | Nine digits, for customers in the US where the card programme asks for it. |
sourceType | Always api. |
Optional fields: occupation, annualSalary, accountPurpose, expectedMonthlyVolume.
curl -X POST "https://sandbox-api.nas.cards/open-api/v3/accounts/$ACCOUNT_ID/kyc" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"firstName": "Alex",
"lastName": "Example",
"dateOfBirth": "1990-01-01",
"gender": "M",
"nationality": "US",
"nationalId": "X1234567",
"idType": "PASSPORT",
"issueDate": "2020-05-10",
"expiryDate": "2030-05-10",
"address": {
"addressLine1": "1 Example Street",
"city": "New York",
"state": "NY",
"country": "US",
"postalCode": "10001"
},
"idFrontId": "1234567890",
"selfie": "1234567892",
"phoneCountryCode": "1",
"phoneNumber": "2025550123",
"sourceType": "api"
}'
{
"code": "000000",
"message": "success",
"data": {
"caseId": "cae9efe2-b577-4632-8c57-8822ddb8542a",
"accountId": "053b4288-7f47-4dc5-bf59-402a5bebf44c",
"createTime": "1755498145103",
"status": "PENDING",
"reason": ""
}
}
Name checks are strict. The name you send must match the name on the document. If it does not, the review fails.
You get a small number of tries. Currently an account can be submitted twice in 24 hours. Check the images and details before you submit.
Some countries and regions are restricted and cannot be verified. The restricted list differs between card BINs. Ask NAS for the current list for the BIN you plan to use.
Step 3 — Read the result
Either wait for the KYC.UPDATED webhook event (the cardholder's own status also arrives as CARDHOLDER.UPDATED), or poll Get KYC and KYB verification result.
curl "https://sandbox-api.nas.cards/open-api/v3/accounts/cdd/detail/$ACCOUNT_ID" \
-H "x-access-token: $ACCESS_TOKEN"
{
"code": "000000",
"message": "success",
"data": {
"kyc": {
"caseId": "cae9efe2-b577-4632-8c57-8822ddb8542a",
"accountId": "053b4288-7f47-4dc5-bf59-402a5bebf44c",
"createTime": "1755498145103",
"status": "PASSED",
"reason": "ok"
},
"kyb": []
}
}
Result states
| Status | Meaning | What to do |
|---|---|---|
PENDING | Under review. | Wait. |
AWAIT_ADDITIONAL | NAS needs more information from the customer. | Read reason, collect what is missing and submit again. |
CHECK_ADDITIONAL | You sent the extra information and it is being reviewed. | Wait. |
REQUEST | Part of the submission must be sent again. | Read reason, fix that part and submit again. |
CANCELED | The submission is rejected. Everything must be sent again. | Read reason, collect fresh details and images, and submit again. |
PASSED | Verified. | Create the cardholder. |
BLACKLISTED | The person cannot be verified, now or later. | Stop. Do not submit again. |
Every state except PENDING carries a reason. Show your customer a clear message, not the raw reason.
Step 4 — Create the cardholder
When the result is PASSED, create the cardholder. A NAMED_INDIVIDUAL cardholder repeats the identity fields and takes the same image file ids. The firstName and lastName together, with a space between, can be at most 23 characters, because the name is printed on the card. A cardholder holds at most five cards.
A new cardholder is PENDING. When it becomes ACTIVE, you can issue cards. Read it with Get cardholder, or listen for CARDHOLDER.UPDATED.
Business customers
Businesses are verified with KYB instead. See Submit account KYB and Get KYB verification result.
Testing KYC in the sandbox
Use the simulator to set the outcome of a review. You do not need real documents for it.
curl -X POST "https://sandbox-api.nas.cards/open-api/v3/vcc/simulate/kyc/review" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"accountId": "<account-id>", "status": "Canceled", "message": "Test rejection"}'
status is Passed or Canceled. See Sandbox testing.
Errors
| Code | HTTP status | What happened |
|---|---|---|
NB40002 | 400 | The upload or the identity fields are malformed. The message names the problem. |
NB40310 | 403 | The details name a different person from the one first submitted on this account. |
NB40311 | 403 | The person is already verified on another account. |
NB40301 | 403 | The account is not yours. |
See Errors for every code.