Skip to main content
Submit a payee workbook to TRACES and retrieve the verification report with the returned token number. You manage the deductor access token and decide when to check for the report.

​
Before you start

  • Obtain a Sandbox access token using the Quickstart guide.
  • Keep the deductor’s TAN and TRACES password ready.
  • Save your PANs in a payee workbook named payee_workbook.json.
The examples use sample tokens and a fictional token number. Replace these values with your own.

​
Submit PANs and download the report

1

Authenticate the deductor

Call Authenticate a TRACES deductor with the TAN and TRACES password. Use your Sandbox access token in the Authorization header.Save data.access_token as deductor_access_token and data.refresh_token as deductor_refresh_token. Check the returned token expiry timestamps before sending requests.Use deductor_access_token in the Authorization header for both PAN verification endpoints. The token identifies the TAN, so PAN requests do not contain tan.
2

Submit the payee workbook

Call Submit PANs for TRACES verification. Send the workbook directly in the request body.
Save data.token_number. This is the TRACES token number for the submission. Sandbox sends each distinct PAN string once and preserves the submitted PAN text.
3

Check the token number

Call Get TRACES PAN verification status with the token number.
While the report is unavailable, data contains token_number, the TRACES status array, and rejection_remarks. Check again later if TRACES is still processing the submission. Review any rejection remarks before submitting another workbook.When the report is available, data contains only output_json_url.
4

Download the result workbook

Download the PAN verification workbook from data.output_json_url within 24 hours. Generated files are retained for 30 days.
Omit the Sandbox authentication headers for this download. The signed URL authorizes the request.The workbook contains sr_no, pan, and pan_status. Rows follow the TRACES report order, with serial numbers starting at 1. PANs absent from the report are omitted, and PAN statuses retain the source text.

​
Refresh the deductor tokens

When the deductor access token expires, call Refresh a TRACES deductor session. Send deductor_refresh_token in the Authorization header and your Sandbox API key in x-api-key. This request has no body. Replace both saved deductor tokens with the returned values. If refresh fails because the token is expired or rejected, authenticate again. PAN verification requests do not refresh tokens or log in automatically. A rejected TRACES session retains its HTTP 401 or 403 response. See the API error guide for other errors. For verification with stored credentials, file uploads, and completion webhooks, use the enriched bulk PAN verification workflow.