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

# Payments

> Create, read, and list payments; funding instructions.

A payment is the order. It is created by confirming a quote or by `POST /v1/ramp/payments`, and it carries everything you need to show or reconcile it.

## Fields that matter

| Field | Meaning |
| - | - |
| `reference` | Your handle for the payment in every later call and webhook. |
| `status` | `pending`, `processing`, `requires_action`, `succeeded`, `failed`, `cancelled`, `expired`. |
| `direction` and `rail` | Copied from the quote. |
| `provider` and `provider_reference` | Who is settling the fiat leg, and their id for support. |
| `source` and `destination_amount` | What was sent and what the recipient gets, after fees. |
| `funding_instructions` | Off-ramp funded externally: the deposit address and network. On-ramp: the bank account the payer must transfer to. |
| `failure_reason` | Set when `status` is `failed`. |

## Read

`GET /v1/ramp/payments/{reference}?environment=sandbox` returns the current state. `GET /v1/ramp/payments?environment=sandbox` lists payments newest first, filterable by `status` and `direction`, with cursor pagination.

## Idempotency

Send `idempotency_key` on confirm and create. A retry with the same key returns the original payment instead of creating another. Use your own order id.

## Funding an off-ramp

If the workspace wallet holds the stablecoins, Onstacks moves them when the payment is created. If the funds are coming from elsewhere, `funding_instructions` gives the deposit address; the payment stays `pending` until the deposit is confirmed, then moves to `processing`.


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