Getting Started

Pre-Requisites and Usage

An active business on Cadana and an org API key is required to make payments.

Please go through the guides on API keys and authentication before you continue.

Pre‑requisites

A Cadana business account.
An Org API key.
Review the guides on API Keys & Authentication.

---
config:
  layout: dagre
---
flowchart LR
    S1["Discover Requirements<br>
       • GET /v1/payment-requirements<br>
       • GET /v1/providers"] --> S2["Onboard Beneficiary<br>
       • POST /v1/files/upload-url + PUT (Upload KYC)<br>
       • POST /v1/beneficiaries"]
    S2 --> S3["Create Payout<br>
       • GET /v1/balances<br>
       • POST /v1/fx-quotes<br>
       • POST /v1/payouts"]
    S3 --> S4["Track Status<br>
       • GET /v1/payouts/:id<br>
       • Webhook payout.updated"]
     S1:::blue
     S2:::orange
     S3:::red
     S4:::purple
    classDef blue   fill:#e6f7ff,stroke:#1890ff,color:#000
    classDef orange fill:#fff7e6,stroke:#fa8c16,color:#000
    classDef red    fill:#ffeded,stroke:#f5222d,color:#000
    classDef purple fill:#f9f0ff,stroke:#722ed1,color:#000

Step 1 – Discover Beneficiary Requirements

Before you create a beneficiary you can use the below endpoints to get the corridor specific requirements and supported bank.

Sequence	What you call	Why
1. Payment requirements	`GET /v1/payment-requirements`	Returns a JSON‑Schema describing all mandatory fields for the corridor (e.g. Colombian NIT, Mexican CLABE).
2. Supported providers	`GET /v1/providers`	Supported banks/wallets that you can make payments to

Step 2 – Create a Beneficiary

Every payout is linked to a beneficiary. KYC information is required the first time you register a beneficiary.
The creation flow consists of two api calls:

Sequence	What you call	Why
1. Upload ID document	`POST /v1/files/upload-url` → `PUT {putUrl} to upload the document`	Reserves a `fileId` and returns a PUT URL that lets the client stream a JPEG/PDF directly to cloud storage. This is required to upload the ID for the beneficiary KYC section. Depending on the ID type, you might have to
2. Create beneficiary	`POST /v1/beneficiaries`	Submit beneficiary payment and KYC information.

Step 3 – Create Payout

Check balance: GET /v1/balances
Your Cadana account must hold enough funds before a payout can be queued.
Lock the rate – POST /v1/fx-quotes
Quotes are valid for ~2 minutes.
Execute payout – POST /v1/payouts
Pass the quoteId and the beneficiaryId generated in previous steps.

Step 4 – Monitor Payout Status

Method	How
Pull	`GET /v1/payouts/{payoutId}`
Push	Subscribe to Webhooks and receive a JSON event on every state change (`processing`, `succeeded`, `failed`, `returned`).Transaction Event Type