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

# Sending payments

> Pay a recipient, in their currency or yours, and track the outcome.

A payment sends money from one of your [accounts](https://docs.talescria.com/guides/accounts.md) to one of a [recipient's destinations](https://docs.talescria.com/guides/recipients.md).

Scopes: `payments:write` to send and quote, `payments:read` to check. `payments:write` moves money: give it only to the service that needs it.

## Same currency

When the account and the destination hold the same currency, send the amount directly.

```bash curl theme={null}
curl https://api.talescria.com/v1/transfers \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: payout-invoice-4821" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAccountId": "acct_01M2P8GP7RSDXN81CXRFM2HFV7",
    "recipientId": "rcp_01M2Q0…",
    "destinationId": "dst_01M2Q1…",
    "minorUnits": "2550",
    "currency": "GBP",
    "reason": "professional_business_services",
    "narration": "Invoice 4821"
  }'
```

```python Python theme={null}
resp = requests.post(
    "https://api.talescria.com/v1/transfers",
    headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "payout-invoice-4821"},
    json={
        "fromAccountId": account_id,
        "recipientId": recipient_id,
        "destinationId": destination_id,
        "minorUnits": "2550",
        "currency": "GBP",
        "reason": "professional_business_services",
        "narration": "Invoice 4821",
    },
    timeout=30,
)
transfer = resp.json()["transfer"]
```

| Field | Notes |
| - | - |
| `minorUnits` | The amount as an integer string: `"2550"` is £25.50. |
| `reason` | Why you're paying them, from [List payment reasons](https://docs.talescria.com/api-reference/payments/list-payment-reasons.md) (for example `goods_purchased`, `professional_business_services`). Some destinations require one, so always send it. |
| `narration` | Up to 200 characters the recipient sees on their statement, where their bank shows one. |

The amount is reserved as soon as the payment is accepted, so it leaves your `available` balance at once.

## Different currencies

To pay an NGN bank account from a GBP account, lock a rate first with an FX quote, then send with it.

**1. Quote**

Fix the side you care about. Usually that's what the recipient receives:

```bash theme={null}
curl https://api.talescria.com/v1/fx-quotes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fromAccountId": "acct_…GBP", "toCurrency": "NGN", "amountToMinorUnits": "5000000"}'
```

```json theme={null}
{
  "quote": {
    "quoteId": "fxq_…",
    "from": "GBP",
    "to": "NGN",
    "amountFromMinorUnits": "2882",
    "amountToMinorUnits": "5000000",
    "rateMicro": 1735328951,
    "status": "active",
    "validForSeconds": 179,
    "expiresAt": 1763130000000
  }
}
```

Show the person `amountFromMinorUnits` ("you send £28.82") and the rate. To spend an exact amount instead, send `amountFromMinorUnits` and leave out `amountToMinorUnits`.

**2. Send with the quote**

Send the **source** side: `minorUnits` and `currency` must match the quote's `amountFromMinorUnits` and `from`.

```json theme={null}
{
  "fromAccountId": "acct_…GBP",
  "recipientId": "rcp_…",
  "destinationId": "dst_…NGN",
  "minorUnits": "2882",
  "currency": "GBP",
  "fxQuoteId": "fxq_…",
  "reason": "professional_business_services"
}
```

* **Use the quote's amounts, never the rate.** Multiplying by `rateMicro` won't reliably reproduce the quoted amounts.
* **Quotes expire.** Read `validForSeconds` rather than assuming a lifetime; it varies by currency pair. Fetch a new quote when it runs out.
* **Quotes are single-use.** Once a payment uses one, it can't be used again, even if that payment then fails. Get a new quote to retry with a new idempotency key.

## Track the outcome

**A `201` means the payment was accepted, not that it has arrived.** Read `status`:

| `status` | Meaning | Final? |
| - | - | - |
| `pending` | Accepted, waiting to be sent. | No |
| `processing` | On its way. | No |
| `successful` | The money left your account. | Yes |
| `failed` | It didn't go. The reserved amount is back in `available`. `failureReason` says why. | Yes |
| `reversed` | It left and came back, for example because the receiving bank returned it. The returned money arrives in your account. | Yes |

Poll until the status is final:

```python theme={null}
import time

def wait_for_payment(token, transfer_id):
    while True:
        resp = requests.get(
            f"https://api.talescria.com/v1/transfers/{transfer_id}",
            headers={"Authorization": f"Bearer {token}"},
            timeout=30,
        )
        transfer = resp.json()["transfer"]
        if transfer["status"] not in ("pending", "processing"):
            return transfer
        time.sleep(5)
```

> [!NOTE]
>
> Webhooks for payment outcomes are coming. Until then, poll `GET /v1/transfers/{id}` while a payment is `pending` or `processing`.

## When a payment is refused

Nothing is reserved or sent when a payment is refused.

| Response | Meaning | What to do |
| - | - | - |
| `402 INSUFFICIENT_FUNDS` | Not enough `available` balance. | Add money or send less. |
| `403 BLOCKED` | Compliance screening refused the destination. | Don't retry. |
| `409 REVIEW` | Compliance wants a person to look at it. | Contact support. |
| `409 NOT_VERIFIED` | Your account isn't verified. | Finish onboarding. |
| `422 REJECTED` | The payment network rejected the recipient's or destination's details; `message` says which. | Fix the recipient, then send with a new idempotency key. |
| `422 UNSUPPORTED` | It can't work as asked, for example a currency mismatch without a quote, or a used or expired quote. | Read `message`. |

A `202` means one of your approval policies holds the payment. The amount is set aside and nothing is sent until it's approved in the dashboard; if it's rejected or expires, the amount is released.

A `200` (rather than `201`) means you sent an idempotency key that already named a payment. That payment is returned and nothing is sent again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.