> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spendin.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Cross-border payouts to mobile money and bank accounts across Africa, settled in stablecoin or naira.

Spendin pays a beneficiary in another country on your behalf. You state what the
beneficiary should receive — 500 GHS to an MTN number — and we tell you what to
send us. You settle in USDT or NGN; we handle the FX, the local rail, and the
retries.

There is no Spendin balance to top up. Every payout is funded by its own
settlement, so money never sits with us between transactions.

## How a payout works

<Steps>
  <Step title="You request the payout">
    `POST /v1/payouts` with the destination and the amount the beneficiary
    receives. The payout is created with status `CREATED`.
  </Step>

  <Step title="We issue a payment instruction">
    Within seconds we lock an FX rate and return a payment instruction — a crypto
    address or a virtual account number, plus the exact amount to send and an
    expiry. The payout moves to `PENDING_PAYMENT`.
  </Step>

  <Step title="You settle">
    Send the expected amount to the account in the instruction. When it arrives
    and confirms, the payout moves to `PAYMENT_RECEIVED`.

    Miss the expiry and the payout ends at `EXPIRED` — a terminal status. Create a
    new payout to try again.
  </Step>

  <Step title="We pay the beneficiary">
    We dispatch to the local processor (`PROCESSING`) and the payout settles at
    `SUCCESSFUL` or `FAILED`. If it fails after your money arrived, we return the
    settlement to a destination you registered up front.
  </Step>
</Steps>

You never have to poll. Every transition is pushed to your
[webhook endpoint](/guides/webhooks), and the full history lives on the payout
itself as a `status_timeline`.

## Start here

<CardGroup cols={2}>
  <Card title="Get access" icon="key" href="/get-access">
    How to get a tenant, complete KYB, and receive your API key.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    A live payout end to end, including the two prerequisites people miss.
  </Card>

  <Card title="Corridors" icon="globe" href="/guides/corridors">
    What you can settle in, and where the money can land.
  </Card>

  <Card title="Payout lifecycle" icon="arrow-progress" href="/guides/payout-lifecycle">
    The seven statuses and what drives each transition.
  </Card>
</CardGroup>

## Two things to set up before your first payout

<Warning>
  Both are enforced at payout creation, and both fail the request rather than
  failing quietly later.
</Warning>

<CardGroup cols={2}>
  <Card title="A refund destination" icon="rotate-left" href="/guides/refunds">
    Because we hold no balance for you, a payout that fails after you have paid
    needs somewhere to send the money back. Register that destination first or
    payout creation returns `422 REFUND_DESTINATION_REQUIRED`.
  </Card>

  <Card title="Approved KYB" icon="shield-check" href="/get-access">
    Your compliance profile must be `APPROVED`. Until then payout creation
    returns `403 COMPLIANCE_NOT_APPROVED`.
  </Card>
</CardGroup>

## Conventions

Every field in every request and response is `snake_case` — we never transform
casing, so what you send is what we store and what you read back.

Timestamps are ISO-8601 in UTC: `2026-08-16T14:30:00.000Z`.

**Every amount travels with its currency.** `destination_amount` is meaningless
without `destination_currency`, and a single payout legitimately spans three
currencies at once — the beneficiary's, yours, and the one the fees are charged
in. Field pairs share a prefix, so `platform_fee_amount` is always denominated in
`platform_fee_currency`.

```json theme={null}
{
  "destination_amount": 500,
  "destination_currency": "GHS",
  "settlement_amount": 42.32,
  "settlement_currency": "USDT",
  "total_fee_amount": 1.41,
  "total_fee_currency": "USDT"
}
```

Never infer a currency from context. A payout priced in GHS with fees charged in
USDT is the normal case, not an edge case.