Skip to main content
Use Sandbox’s bulk PAN verification API to check PAN statuses through TRACES and download a JSON workbook of results. Sandbox manages TRACES authentication with the credentials saved for your TAN.

​
Before you start

  • Obtain a Sandbox access token and API key using the Quickstart guide.
  • Save the TAN’s TRACES credentials in the same Sandbox workspace. Skip credential setup if valid credentials are already saved.
  • Prepare a JSON payee workbook named payee_workbook.json with your PANs. The file must be at most 5,000,000 bytes.
Replace the sample TAN with your own TAN and use the same TAN as the saved credentials. Replace placeholders with the values returned by each request.

​
Verify the PANs

1

Create a verification job

Call Create a bulk PAN verification job with the TAN.

Create job with cURL

The response has data.status: "created". Save data.job_id to check progress and data.json_url to upload the workbook.
2

Upload the payee workbook

Send the JSON file to the returned data.json_url with HTTP PUT. The payee workbook reference provides the schema and a sample.

Upload workbook with cURL

Use the signed URL within 24 hours. The URL authorizes the upload, so omit the Sandbox Authorization and x-api-key headers.Processing starts after upload. Sandbox then checks file size and the saved TRACES credentials. A successful create request does not confirm those checks have passed.
3

Check the verification job status

Call Get bulk PAN verification job status with the returned job_id.

Poll job with cURL

Continue polling while data.status is created, queued, or in_progress. If the job stays created, confirm that you uploaded the workbook successfully.Stop polling when the status is succeeded or failed. A failed job still returns HTTP 200. Read data.message for the reason.You can also configure a job status webhook before creating the job to receive completion notifications.
4

Download the verification results

When data.status is succeeded, download the result from data.output_json_url.

Download results with cURL

The download URL is valid for 24 hours. Uploaded and generated files are retained for 30 days. See the output schema and sample to read the result workbook.

​
Read the results

Read the PAN verification workbook reference for column definitions and PAN status guidance.

​
Resolve errors

If data.status is failed, read data.message before creating another job. For credential errors, check the saved TAN and TRACES password in your current Sandbox workspace. To replace saved credentials, delete the credentials, then add the correct credentials. If the file exceeds 5,000,000 bytes, reduce its size and upload it to a new job. For other workbook errors, compare the file with the input schema. If polling returns HTTP 521 with Data not found, check the job ID and confirm that you are using the workspace where you created the job. See the API error guide for request and authorization errors.