> ## 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.

# Overview

> Integrate Cadana's payment infrastructure to simplify international payroll across 100+ countries

Cadana's Payments API lets you pay employees and contractors through local payment rails and SWIFT across a broad network of countries.

***

## Features

<CardGroup cols={2}>
  <Card title="FX Rate Retrieval" icon="arrows-rotate">
    Access real-time foreign exchange rates and lock quotes before sending payments.
  </Card>

  <Card title="Beneficiary Management" icon="user-plus">
    Create and manage reusable payment destinations to streamline repeat payouts.
  </Card>

  <Card title="Payment Processing" icon="paper-plane">
    Initiate payouts to bank accounts and mobile wallets with built-in compliance checks.
  </Card>

  <Card title="Payment Tracking" icon="radar">
    Monitor the status of every payment in real-time via API polling or webhooks.
  </Card>

  <Card title="Global Coverage" icon="globe">
    Send payments in multiple currencies through local rails and SWIFT across a broad network of countries.
  </Card>
</CardGroup>

***

## How It Works

Every payout follows four steps:

```mermaid theme={null}
flowchart LR
    S1["Discover Requirements
       GET /v1/payment-requirements
       GET /v1/providers"] --> S2["Create Beneficiary
       POST /v1/files/upload-url
       POST /v1/beneficiaries"]
    S2 --> S3["Create Payout
       GET /v1/balances
       POST /v1/fx/quotes
       POST /v1/payouts"]
    S3 --> S4["Track Status
       GET /v1/payouts/:id
       Webhooks: transaction.*"]
    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
```

<Steps>
  <Step title="Discover requirements">
    Call [`GET /v1/payment-requirements`](/api-reference/payments/resources/payment-corridor-requirements) to get the required fields for a country and payment method. Call [`GET /v1/providers`](/api-reference/payments/resources/get-payout-providers) to list supported banks and mobile money providers.
  </Step>

  <Step title="Create a beneficiary">
    Store the recipient's payment details with [`POST /v1/beneficiaries`](/api-reference/payments/beneficiaries/create). Beneficiaries are reusable — create once, pay many times.

    <Note>
      KYC documents (e.g., a government-issued ID) are required for beneficiaries. Upload documents via [`POST /v1/files/upload-url`](/api-reference/payments/beneficiaries/create-upload-url) before creating the beneficiary. See [Making a Payment](/payments/making-a-payment) for the full flow.
    </Note>
  </Step>

  <Step title="Send a payout">
    Check your balance, lock an FX rate with [`POST /v1/fx/quotes`](/api-reference/payments/fx/create-fx-quote), then execute the payout with [`POST /v1/payouts`](/api-reference/payments/payouts/create) using the returned quote `id`.
  </Step>

  <Step title="Track the payment">
    Poll [`GET /v1/payouts/:id`](/api-reference/payments/payouts/get) or subscribe to [webhooks](/reference/events#transactions) for real-time status updates.
  </Step>
</Steps>

***

## API Endpoints

### Beneficiaries

| Method | Endpoint                                                                 | Description          |
| :----- | :----------------------------------------------------------------------- | :------------------- |
| POST   | [`/v1/beneficiaries`](/api-reference/payments/beneficiaries/create)      | Create a beneficiary |
| GET    | [`/v1/beneficiaries`](/api-reference/payments/beneficiaries/list)        | List beneficiaries   |
| GET    | [`/v1/beneficiaries/{id}`](/api-reference/payments/beneficiaries/get)    | Get a beneficiary    |
| DELETE | [`/v1/beneficiaries/{id}`](/api-reference/payments/beneficiaries/delete) | Delete a beneficiary |

### Payouts

| Method | Endpoint                                                  | Description       |
| :----- | :-------------------------------------------------------- | :---------------- |
| POST   | [`/v1/payouts`](/api-reference/payments/payouts/create)   | Create a payout   |
| GET    | [`/v1/payouts`](/api-reference/payments/payouts/list)     | List payouts      |
| GET    | [`/v1/payouts/{id}`](/api-reference/payments/payouts/get) | Get payout status |

### FX

| Method | Endpoint                                                      | Description     |
| :----- | :------------------------------------------------------------ | :-------------- |
| POST   | [`/v1/fx-quotes`](/api-reference/payments/fx/create-fx-quote) | Get an FX quote |

### Balances

| Method | Endpoint                                                                              | Description                              |
| :----- | :------------------------------------------------------------------------------------ | :--------------------------------------- |
| GET    | [`/v1/balances`](/api-reference/payments/balances/get-account-balances)               | Get wallet balances                      |
| GET    | [`/v1/funding-details`](/api-reference/payments/balances/get-account-funding-details) | Get funding instructions for your wallet |

### Discovery

| Method | Endpoint                                                                                      | Description                        |
| :----- | :-------------------------------------------------------------------------------------------- | :--------------------------------- |
| GET    | [`/v1/payment-requirements`](/api-reference/payments/resources/payment-corridor-requirements) | Get required fields for a corridor |
| GET    | [`/v1/providers`](/api-reference/payments/resources/get-payout-providers)                     | List supported banks and providers |
| GET    | [`/v1/payment-methods`](/api-reference/payments/resources/get-payment-methods)                | List available payment methods     |

***

## Webhook Events

Subscribe to these events to track payment lifecycle changes:

| Event                   | Description                                                                                                            |
| :---------------------- | :--------------------------------------------------------------------------------------------------------------------- |
| `transaction.initiated` | Payout created and compliance checks in progress                                                                       |
| `transaction.succeeded` | Delivered to recipient                                                                                                 |
| `transaction.failed`    | Payment failed. If `isReturned` is `true`, the payment was previously successful but returned by the recipient's bank. |

See [Webhooks](/reference/webhooks) to configure your endpoint.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Making a Payment" icon="route" href="/payments/making-a-payment">
    Step-by-step integration guide
  </Card>

  <Card title="Payment Methods & Requirements" icon="list-check" href="/payments/payment-requirements">
    Supported methods and required fields per corridor
  </Card>

  <Card title="RFI & Compliance" icon="shield-check" href="/payments/rfi-compliance">
    Handling compliance holds and document requests
  </Card>
</CardGroup>