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

# Payments

> Choose a payment shape, estimate at checkout, and create one merchant order.

The Partner API is semantic: specify what the end user pays and receives,
the amount mode, and the final recipient. AgentBank owns routing and any
intermediate transfers. Follow the [Quickstart](./quickstart) for the full
integration sequence.

Do not send intent IDs, quote IDs, route agreement IDs, hop lists, callback
URLs, registered-recipient IDs, or recipients for internal hops.

## Choose the payment shape

| Shape | Final recipient |
| - | - |
| On-ramp: fiat to crypto | A crypto address on the destination chain |
| Off-ramp: crypto to fiat | A supported fiat payout instrument, such as a QR or bank account |
| Fiat-to-fiat: `on_ramp -> off_ramp` | Only the final fiat recipient; AgentBank supplies the intermediate crypto recipient |

For an on-ramp, put the crypto address in `recipient_fields.address`.

Fiat-to-fiat supports this two-hop shape only. Do not create a separate merchant
payment for the intermediate transfer or request identical source and destination
assets.

Discover live instruments through
[List fiat payment capabilities](./reference/discovery/fiat-payment-capabilities),
not a static currency list alone. Before a fiat payout, use
[Parse QR recipient](./reference/partner/parse-qr-recipient) or
[Verify bank recipient](./reference/partner/verify-bank-recipient), as applicable,
and carry the returned canonical `recipient_fields` into payment creation.

## Estimate before commitment

[Estimate payment](./reference/partner/estimate-payment) owns the quote request
and response examples, including `preferred_rails`. Send the end user and the
supported `on_ramp` or `off_ramp` direction with exactly one of `amount_in` or
`amount_out`.

An estimate filters by end-user readiness but is non-binding. It does not
reserve a route or authorize funds to move. Request it near checkout, then
create the payment when the customer commits.

## Create one commercial order

[Create payment](./reference/partner/create-payment) owns the complete request
and response contract. Supply the merchant end user, your request correlation
ID, durable `merchant_payment_reference`, source and destination assets, amount
mode, and final recipient.

Choose `exact_source` when the payer fixes how much to spend; put that amount in
`source`. Choose `exact_destination` when the customer fixes how much must
arrive; put that amount in `destination`. Amounts are strings.

For a QR recipient, country is normally derived from `qr_content`; an optional
country constraint must match. A direct bank recipient requires `country`.
Never add a client-selected internal rail. Recipient validation happens again
when the payment is created, without using a saved recipient book.

Use one payment reference per economic order and reuse the same body and
reference after an uncertain request. See
[Payment idempotency](./errors-and-idempotency#payment-idempotency).

## Follow the returned payment

The server-generated `payment_instruction` is the funding authority;
`next_action` tells the customer whether to fund or wait. Preserve the issued
amount, asset, destination, chain, memo, reference, calldata, and expiry.
[Funding and tracking](./funding-and-tracking) explains how to present the
instruction and reconcile webhooks with current payment state.

Use [Get payment](./reference/partner/get-payment) for the full current view
and [List payments](./reference/partner/list-payments) for merchant history and
its supported filters. Portal JWT holders can also
[read](./reference/portal/get-payment) and [list](./reference/portal/list-payments)
payments, but cannot create or cancel them.

## Cancellation and active-payment limits

[Cancel payment](./reference/partner/cancel-payment) applies before funding
where the current settlement state permits it. Do not report success until
the returned or subsequently read payment is terminal with `status: "cancelled"`.

Each end user may have only one non-terminal B2B payment, regardless of direction
or hop count. Complete, cancel, or let it reach a terminal state before creating
another. Internal fiat-to-fiat hops are not separate merchant orders.