Payments - Onstacks

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.