Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cadanapay.com/llms.txt

Use this file to discover all available pages before exploring further.

Workers can send funds from their wallet to saved beneficiaries — bank accounts, mobile money, e-wallets, cards, and more across 100+ countries.

​
Payment Methods & Requirements

Before adding a beneficiary, check which payment methods are available for the destination country and what fields are required.

​
List available payment methods

Response: 
{
  "country": "BR",
  "paymentMethods": [
    { "type": "bank", "currency": "BRL", "status": "active" },
    { "type": "proxy", "currency": "BRL", "status": "active" },
    { "type": "swift", "currency": "BRL", "status": "active" }
  ]
}

​
Get field requirements for a corridor

Each country + currency + payment method combination has specific field requirements. Use the payment requirements endpoint to get the JSON schema for the paymentDetails object. This returns a JSON Schema describing which fields are required, valid values for enums (e.g. bank codes), and validation rules.

​
Get payout providers

For countries with multiple bank or mobile money providers, retrieve the list of supported providers.

​
Supported payment methods

MethodDescriptionUse case
bankLocal bank transferMost countries
momoMobile moneyAfrica (M-Pesa, MTN, etc.)
achACH transferUnited States
swiftSWIFT/wire transferInternational
walletCadana walletUser-to-user transfers
cryptoCrypto walletBTC, USDC, ETH, etc.
proxyProxy paymentUPI (India), etc.

​
Beneficiaries

A beneficiary is a saved payment destination. Each beneficiary has a payment method and is scoped to a specific user.

​
Add a beneficiary

Response: 
{
  "id": "7a7f80a6-1665-4f64-9ef3-d5f90f8f309b"
}

​
Manage beneficiaries

OperationEndpoint
ListGET /v1/users/{userId}/beneficiaries
GetGET /v1/users/{userId}/beneficiaries/{beneficiaryId}
DeleteDELETE /v1/users/{userId}/beneficiaries/{beneficiaryId}

​
Check Fees, Timelines & Limits

Before creating a transaction, look up the fees, delivery timeline, and transfer limits that apply to the user’s corridor.

​
Fetch the payout catalog

Pass sourceCurrency to quote every corridor’s fee in that currency. It defaults to USD when omitted. To quote the catalog in a different currency:

​
Get a concrete estimate

Supply paymentMethod and destinationCurrency to receive an estimate block alongside the catalog — a per-transaction fee, delivery ETA, and transfer limits for the requested corridor. Add destinationCountry when several countries share a currency (e.g. USD sent to Ecuador vs. USD sent to El Salvador) so the estimate resolves to the right country, and sourceAmount to resolve percentage-based fees into a concrete amount. Response: 
{
  "data": {
    "sourceCurrency": "USD",
    "payouts": [
      {
        "paymentMethod": "bank",
        "destinationCurrency": "AUD",
        "destinationCountry": "AU",
        "fee": { "type": "fixed", "value": 1, "min": 0, "max": 0 },
        "feeCurrency": "USD",
        "timeline": { "minDays": 1, "maxDays": 2, "businessDaysOnly": true }
      }
    ],
    "estimate": {
      "paymentMethod": "bank",
      "destinationCurrency": "AUD",
      "destinationCountry": "AU",
      "fee": { "value": "1.00", "currency": "USD" },
      "timeline": {
        "minDays": 1,
        "maxDays": 2,
        "businessDaysOnly": true,
        "estimatedArrival": "Apr 24, 2026 (excluding holidays)"
      },
      "limits": { "min": "2", "max": "20000", "currency": "AUD" }
    }
  }
}
data.payouts is always the full, unfiltered catalog — query parameters only shape the estimate block. fee.type is either fixed (denominated in feeCurrency) or percentage (a rate, e.g. 1.5 = 1.5%).

​
Get an FX Quote

Before creating a transaction, get an FX quote to lock in the conversion rate. Quotes are temporary — use the returned id as the quoteId when creating the transaction. Response: 
{
  "id": "57c74c5d-38a0-41e7-a19e-161f16dc4898",
  "from": "USD",
  "to": "PHP",
  "rate": "56.1234",
  "expirationTimestamp": "2025-05-29T21:42:52Z"
}
Quotes expire — check expirationTimestamp and request a new quote if the previous one has expired.

​
Create a Transaction

Send funds from the user’s wallet to a beneficiary. You can specify either a destination amount or a source amount — Cadana handles FX conversion using the quote rate.

​
Send a specific destination amount

Send exactly 500 PHP to the beneficiary. Cadana deducts the equivalent USD from the wallet.

​
Send a specific source amount

Send 10 USD worth of the destination currency to the beneficiary. Response: 
{
  "id": "d0137ede-7df1-4a54-8206-b3ab7b03876f"
}

​
Transaction fields

FieldRequiredDescription
typeYespayout
beneficiaryIdYesThe beneficiary to send to
quoteIdYesFX quote ID from POST /v1/fx-quotes
amount + sourceCurrencyOne ofDestination amount — send exactly this amount in the destination currency
sourceAmountOne ofSource amount — deduct exactly this amount from the wallet
referenceYesYour unique reference for idempotency

​
Track the Transaction

Response: 
{
  "id": "d0137ede-7df1-4a54-8206-b3ab7b03876f",
  "type": "payout",
  "beneficiaryId": "c871b333-e129-409c-aabd-7cfb55a967cc",
  "quoteId": "57c74c5d-38a0-41e7-a19e-161f16dc4898",
  "amount": { "value": "500.00", "currency": "PHP" },
  "sourceAmount": { "value": "9.00", "currency": "USD" },
  "feeAmount": { "value": "0.10", "currency": "USD" },
  "fxRate": "56.1234",
  "reference": "3f70be8e-426f-4e89-b883-9c97a1c334d5",
  "status": "succeeded",
  "createdTimestamp": 1748478276,
  "lastUpdatedTimestamp": 1748478276
}

​
Transaction statuses

StatusDescription
initiatedTransaction created, processing has started
processingFunds are being sent to the beneficiary
succeededFunds delivered
failedTransaction failed

​
List all transactions

Filter by reference or type using query parameters.

​
Webhook Events

Subscribe to transaction events for real-time status updates:
EventDescription
transaction.initiatedTransaction created and processing has started
transaction.succeededFunds delivered to the beneficiary
transaction.failedTransaction failed
See Events for webhook payloads and Webhooks to configure your endpoint.

​
Next Steps

Global Wallets

Wallet product overview

Virtual Accounts

Fund wallets via dedicated ACH accounts

Wallets API Reference

Full API documentation