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

# Transfers

> Confirm a quote, track your payment and see what happened to your funds.

Create a transfer to carry out a [quote](https://docs.ledig.io/guides/quotes.md). The quote supplies the amounts, fees and destination, so review those details before sending this request.

## Create a transfer

Replace `QUOTE_ID` with the ID returned when you created the quote:

```http theme={null}
POST /v1/transfers
Content-Type: application/json
```

```json theme={null}
{
  "quoteId": "QUOTE_ID",
  "reference": "order-1042"
}
```

`quoteId` is required. `reference` is optional and can contain up to 64 characters. Use a reference that identifies this payment in your system.

The quote must belong to your business, be pending and unexpired, and pass the current payment checks. Your available balance must cover `totalSourceDebitAmount`, including fees.

HTTP `201` means the request was accepted; processing can still fail later. Top-level `replayed: false` identifies a new transfer, and `replayed: true` identifies the original transfer returned without another payment. Save its ID and read `GET /v1/transfers/{id}` to check its current status. Conversions, external payouts and payments to Ledig businesses use this same flow.

## Processing status

| Status | Meaning |
| - | - |
| `pending` | Your transfer is waiting to be processed. |
| `processing` | Your transfer is being processed. |
| `completed` | Processing has completed. |
| `failed` | The transfer could not complete. Read the explanation and funds status. |
| `reversed` | The transfer has been reversed. Check the funds status for the return. |

For a failed transfer, read `failureReason` for the explanation and `balanceImpact` for the funds status. When returned, use `customerPresentation.label`, `message` and `actionRequired` to explain progress in your interface. `approval` can indicate that a payment is awaiting review.

The top-level `status` is the current result. Earlier `events` describe stages the transfer has already reached.

## What happened to the funds

A failed transfer does not always mean the funds have already been returned. Use `balanceImpact` when it is returned:

| `balanceImpact` state | Meaning |
| - | - |
| `not_started` | No payment effect has been recorded yet. |
| `on_hold` | Funds are held for this payment. |
| `deducted` | Funds have been deducted. |
| `hold_released` | The hold has been released. |
| `returned` | Funds have been returned. |
| `return_pending` | The return is being processed. |
| `finishing_completion` | The final balance update is being completed. |
| `still_checking` | The funds status is not yet confirmed. |

Its `lines` give the amounts and currencies affected. If `balanceImpact` is missing, check your [balances](https://docs.ledig.io/guides/balances.md) and contact support when you need help confirming the outcome.

## Follow payment progress

Poll `GET /v1/transfers/{id}`, leaving a delay between requests and increasing it while the payment remains pending. Honour `Retry-After` if you are rate limited.

Use the read endpoint instead of submitting the transfer again just to check its status. Use [Transactions](https://docs.ledig.io/guides/transactions.md) to list payment history.

A response may include receipt details or a crypto transaction hash. Use the transfer status and `balanceImpact` to confirm progress and the effect on your funds.

## Retries

Transfers use `quoteId` and `reference` to recognise retries. This endpoint does not use the `Idempotency-Key` header.

After a timeout, retry with the **same quote ID and original reference**, using a fresh signature and timestamp. This returns the original transfer when one already exists. Do not create a new quote just to retry a payment whose outcome is unknown.

| Identifiers sent | Result |
| - | - |
| Existing quote ID, with no reference or the original reference | Returns the original transfer. |
| Existing reference with a new quote ID | Returns the original transfer; the new quote remains unused. |
| Existing quote ID with a new, unused reference | Returns the original transfer; the new reference is not saved for that transfer. |
| Quote ID and reference belong to different existing transfers | Returns `409 IDEMPOTENCY_CONFLICT`. |
| New quote ID and an unused reference, or no reference | Creates a new transfer if the payment checks pass. |

Retry recognition applies within the same business account. You still need valid authentication and an active business. An existing transfer can be retrieved through a retry even after its quote expires.

If the original outcome remains unclear, contact [support@ledig.io](mailto:support@ledig.io) with the transfer ID, quote ID and your reference. Keep those identifiers so support can find the original payment.


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