https://dev-api.cadanapay.com
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 apayrollDate 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 specificaccountName 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, use99999900 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.Reviewing KYC Directly
There are two ways to get a user toapproved in sandbox. Which one you want depends on what you are testing.
Sentinels are the shortcut. Put auto-approve in the ID number field and Cadana decides the result on the spot. It never opens your uploaded files — it doesn’t even need them. Use this when you just want an approved user so you can move on to testing something else, like payments.
Review KYC is the full path. You send exactly what your production code would send: real names, real document details, real file IDs. Cadana stores the documents and passes them on for verification, same as production. But sandbox has no real reviewer, so no result ever comes back and the user sits at pending. This endpoint is how you decide the outcome yourself:
Returns
204. Each call decides one check, so a user who needs both identity and address approved takes two calls. It works no matter what state the user is in, and it keeps the details and documents already on file. A user.kyc.updated webhook fires, exactly as it would for a real verification result.
Journey 1: I just need an approved user
You are testing payouts and you need a worker who can receive money. You don’t care how they got verified.1
Submit KYC with a sentinel
Call
POST /v1/users/{userId}/kyc with idDetails.number set to auto-approve. You can leave out frontFileId and selfieFileId — no files are needed.2
Check the status
GET /v1/users/{userId}/kyc returns identity: "approved" straight away. The user can now be paid.Journey 2: I need to prove my document upload works
You are building the upload part of your integration and you want to confirm your files really reach Cadana and get attached to the right user.1
Upload the documents
Upload the front of the ID and the selfie using the file upload flow. Keep the
fileId each upload returns.2
Submit KYC with real values
Call
POST /v1/users/{userId}/kyc with a real ID number and the fileId values from the previous step. Do not use a sentinel anywhere in this request — a sentinel would skip the document handling you are trying to test.3
Confirm the documents landed
GET /v1/users/{userId}/kyc shows identity moving to processing and then settling at pending. That is the expected end state in sandbox, and it means your documents were accepted and passed on for verification.4
Decide the outcome yourself
Call
POST /v1/sandbox/users/{userId}/kyc/review with {"action": "approve", "type": "identity"}. Use "action": "reject" instead if you want to test how your app handles a rejection.5
Check the result
GET /v1/users/{userId}/kyc now returns identity: "approved", and your webhook endpoint receives user.kyc.updated.Journey 3: My test user is stuck
You submitted without a sentinel, the user is sitting atpending, and PATCH refuses with identity can only be resubmitted when status is Rejected. That error is correct — resubmission is only for fixing a rejection, so it cannot rescue a pending user.
You have two ways out:
- Keep the user. Call Review KYC to approve or reject them. Everything they submitted stays as it is.
- Start over. Delete the sandbox user and re-invite the same person.
This endpoint exists only in sandbox. In production, KYC results come from the verification provider and this path is not available.
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 withPOST /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.