Skip to main content
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: Set the 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

​
Address Line 2

Identity and address sentinels can be combined in a single request to control each verification independently. Sentinel values are case-insensitive. These sentinels work with both initial submission (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.
Initial submission: Resubmission (after rejection):

​
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

​
Principal SSN

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.