Skip to main content

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.

warning

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​

  1. Upload the ID document images and a selfie. You get a file id for each.
  2. Submit the customer's details with those file ids.
  3. Read the result, by webhook or by polling.
  4. 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.

RuleLimit
Files per call1 to 10
Size of one file10 MB
Size of one call25 MB
File typesjpg, jpeg, png, gif, bmp, svg, ico, webp, pdf, doc, docx, xls, xlsx, ppt, pptx, txt, zip, rar, 7z, tar, gz
File namesLetters, digits, spaces and . _ - ( ) only. Up to 200 characters. Not starting with a dot.
Empty filesRefused

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"
Response POST /open-api/v3/files/upload
{
"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.

FieldNotes
firstName, lastNameAs printed on the document. English letters only.
dateOfBirthYYYY-MM-DD.
genderM or F.
nationalityTwo-letter country code (ISO 3166-1 alpha-2).
nationalIdThe ID number on the document.
idTypeOne 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, expiryDateYYYY-MM-DD. The document must not be expired.
addressaddressLine1, city, state, country, postalCode required. English letters, digits and common symbols. For the US and Canada, state is the two-letter code.
idFrontIdFile id of the front of the ID.
idBackIdFile id of the back. Not needed for a passport.
selfieFile id of the selfie.
phoneCountryCode, phoneNumberDialling code without +, and the number without the code.
ssnNine digits, for customers in the US where the card programme asks for it.
sourceTypeAlways 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"
}'
Response POST /open-api/v3/accounts/{accountId}/kyc
{
"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.

note

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"
Response GET /open-api/v3/accounts/cdd/detail/{accountId}
{
"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​

StatusMeaningWhat to do
PENDINGUnder review.Wait.
AWAIT_ADDITIONALNAS needs more information from the customer.Read reason, collect what is missing and submit again.
CHECK_ADDITIONALYou sent the extra information and it is being reviewed.Wait.
REQUESTPart of the submission must be sent again.Read reason, fix that part and submit again.
CANCELEDThe submission is rejected. Everything must be sent again.Read reason, collect fresh details and images, and submit again.
PASSEDVerified.Create the cardholder.
BLACKLISTEDThe 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​

CodeHTTP statusWhat happened
NB40002400The upload or the identity fields are malformed. The message names the problem.
NB40310403The details name a different person from the one first submitted on this account.
NB40311403The person is already verified on another account.
NB40301403The account is not yours.

See Errors for every code.