Cadana’s sandbox environment lets you test your integration without processing real financial transactions. The sandbox APIs mirror production, so transitioning to live is as simple as updating the host and API key.
Sandbox host: https://dev-api.cadanapay.com
Use an API key generated for the sandbox environment. Production API keys will not work with the sandbox host.
The sandbox sends real emails — user invites, contract signature requests, and other notifications are delivered to the addresses you provide, and user accounts are real login accounts. Use inboxes you control (e.g., plus-addressing on your own domain), and pass suppressWelcomeEmail / suppressNotification where available.
Funding Your Wallet
Use the sandbox deposit endpoint to add test funds to your wallet:
Testing Payrolls
To run a payroll through its full lifecycle without waiting, save it with a payrollDate in the past — it completes immediately on approval. This is the recommended way to test payslip downloads end-to-end, since payslips exist only for Completed payrolls. Payrolls with a future payrollDate disburse on that date.
Simulated Payment Failures
To test your error handling, use specific accountName values when creating a beneficiary to trigger simulated payment failures:
| Account Name | Simulated Failure |
|---|
FAILURE_SIM_001 | Invalid account |
FAILURE_SIM_002 | Bank unavailable |
FAILURE_SIM_003 | Rejected by compliance |
FAILURE_SIM_004 | Returned by bank |
accountName in the beneficiary’s bank payment details:
When the payout is processed, it will fail with the corresponding error message — in this case, “Rejected by compliance”.
Virtual Account Auto-Approval
When creating a virtual account in sandbox, use 99999900 as the customIdentification.number to automatically approve the account. The type (SSN or BVN) does not matter.
KYC Testing
Use these test values when submitting KYC in sandbox to simulate different verification outcomes.
Identity Document Number
| Value | Result |
|---|
auto-approve | Identity verification automatically approved |
auto-reject | Identity verification automatically rejected |
Address Line 2
| Value | Result |
|---|
auto-approve | Address verification automatically approved |
auto-reject | Address verification automatically rejected |
POST) and resubmission (PATCH).
The examples below include document file IDs to show the full request shape. When a sentinel is used, frontFileId, selfieFileId, and addressProofFileId can be omitted — no file upload is needed. If you do pass them, they must reference files you actually uploaded; made-up IDs are rejected with a 404. Always use a sentinel when testing KYC in sandbox. A submission without one is not auto-approved — it stays unresolved, and since resubmission is only allowed after a rejection, the user cannot complete KYC. To recover, delete the sandbox user and re-invite. Without a sentinel, document file IDs are also required, as in production.
Resetting Sandbox Users
Delete a sandbox user to start over — for example, after a KYC submission that can’t be resubmitted. The linked Person record is preserved, so you can re-invite the same person with POST /v1/users/invite.
Returns 204 on success. This endpoint only exists in the sandbox environment.
KYB Testing
Use these test values when submitting KYB information in sandbox to simulate different outcomes.
Tax Identification Number
| Tax ID | Result |
|---|
000-CAD-AUTO-APPROVE | KYB automatically approved |
000-CAD-AUTO-REJECT | KYB automatically rejected (terminal) |
000-CAD-AUTO-FLAG | Status set to needs-additional-info — flags tax ID as incorrect and requests all business documents |
Principal SSN
| SSN | Result |
|---|
000-11-2222 | Status set to needs-additional-info — requires identity (front and back) and address files for the principal |
000-11-3333 | Status set to needs-additional-info — principal receives email to complete KYC via provider |
You can’t combine 000-CAD-AUTO-APPROVE with a sentinel SSN in the same submission — the request returns 400 cannot combine auto-approve tax ID with auto-feedback principal presets.
All sandbox test values are ignored silently in production.
