> ## 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.

# Quickstart

> The end-to-end path from merchant provisioning to a completed payment.

Use this sequence to integrate the Partner API. Endpoint links provide the
request and response examples; the steps below explain when to call them.
Keep KYC bytes, private keys, QR payloads, and webhook secrets out of prompts,
client logs, and telemetry.

## 1. Provision the merchant and authenticate

Choose the [Sandbox base URL](./environments) and use that environment
consistently for all credentials and resources. Complete [Onboarding](./onboarding):
generate an Ed25519 key pair in your backend, share only its public PEM with
AgentBank, and securely store the returned merchant ID and portal credentials.

Implement [request signing](./authentication) before calling `/v1/partner/*`.
Sign the exact bytes you send and use a fresh nonce for every request, including
signed reads. Keep the private key in your server-side secret manager.

## 2. Register a webhook

[Log in to the portal](./reference/portal/login), then use its `access_token` to
[register a public HTTPS endpoint](./reference/portal/create-webhook). Store the
returned `signing_secret` immediately: it is shown only once.

Implement [delivery verification and deduplication](./portal-and-webhooks)
before creating KYC records or payments. Portal JWTs manage webhooks and read
payment history; they do not authorize Partner API writes.

## 3. Discover available assets and recipient forms

Before rendering a payment form, read the public discovery APIs:

1. [List currencies](./reference/discovery/currencies) for active symbols and decimals.
2. [List fiat payment capabilities](./reference/discovery/fiat-payment-capabilities)
   for live directions and final fiat-recipient instruments. Only `off_ramp`
   entries carry those recipient fields; an on-ramp ends at a crypto address.
3. [Get payment instrument schemas](./reference/discovery/payment-instrument-schemas)
   for QR, direct bank-transfer, and mobile-money fields.
4. [List supported bank names](./reference/discovery/supported-bank-names)
   when the customer selects direct bank transfer.

Discovery is form metadata, not proof of an end user's readiness or a guarantee
that a quote will remain available.

## 4. Create or refresh the end user

Call [Create end user](./reference/partner/create-end-user) with a complete
`partner_end_user_kyc_v1` record and inline artifacts. Follow the required
fields and artifact rules in [End-user KYC](./end-user-kyc). Do not send an
end-user ID, merchant KYC reference, or provider user ID.

Persist the returned `end_user_id`. For a correction, read the end user and
[update KYC](./reference/partner/update-end-user-kyc) with the latest
`base_kyc_version`. Do not create a second end user merely because a request
timed out; follow [KYC retry guidance](./errors-and-idempotency#kyc-retries-and-versions).

## 5. Wait for the required fiat rails

Poll [Get end user](./reference/partner/get-end-user) or process
`end_user.rail_readiness.updated`. Continue only when the fiat currencies
required by the payment have `rail_readiness[].state: "available"`.

KYC acceptance alone is insufficient: provider forwarding is asynchronous, and
an end user can be ready for one currency but not another. See
[Rail readiness](./rail-readiness) for pending, unavailable, and expired states.

## 6. Preflight the final fiat recipient

Skip this step for an on-ramp whose final recipient is a crypto address.

* For a QR payout, call [Parse QR recipient](./reference/partner/parse-qr-recipient)
  with `qr_content`. Do not send `rail` or `end_user_id`. Supply `country` only
  as an independent constraint; a mismatch with the detected country is rejected.
* For a direct bank payout, call [Verify bank recipient](./reference/partner/verify-bank-recipient)
  with `end_user_id`, `country`, and the required bank details. Do not send `rail`.

Use the returned canonical `recipient_fields` unchanged, including resolved
recipient details. Preflight does not store a recipient, reserve liquidity, or
move funds. QR parsing does not replace the end-user readiness check.

## 7. Estimate immediately before checkout

Call [Estimate payment](./reference/partner/estimate-payment) with the same
end user and economic direction. The endpoint supports `on_ramp` and `off_ramp`
estimates and filters out rails that are not ready for that end user.

An estimate is non-binding: it neither reserves liquidity nor authorizes
settlement. See [Payments](./payments) for the supported payment shapes.

## 8. Create one payment when the customer commits

Call [Create payment](./reference/partner/create-payment) with the end user,
source and destination assets, amount mode, and final `recipient_fields`.
For fiat-to-fiat, supply only the final fiat recipient, never a crypto bridge
address or a recipient for an internal hop.

Use one durable `merchant_payment_reference` per commercial order. If a request
times out, reuse the identical body and reference with a fresh signature and
nonce; changing the body under the same reference causes an idempotency
conflict. See [Errors and idempotency](./errors-and-idempotency).

Do not request identical source and destination assets or create parallel
active payments for one end user. Complete, cancel, or wait for the existing
payment to become terminal before starting another.

## 9. Fund only as instructed

Read `next_action` and `payment_instruction` from the response. When instructed
to fund, display or execute exactly the issued asset, amount, account/address,
chain, memo, reference, QR, calldata, and expiry. Do not reconstruct an
instruction from a quote or substitute a familiar account.

When `next_action.type` is `wait`, do not ask the payer to pay again. For
fiat-to-fiat, fund only the first visible instruction; AgentBank handles the
intermediate transfer. See [Funding and tracking](./funding-and-tracking).

## 10. Track to a terminal outcome

Consume verified webhooks, deduplicate by `x-agentbank-delivery-id`, and use
[Get payment](./reference/partner/get-payment) for recovery. Render `timeline`
as observed history grouped by `hop_index`; use `next_action` for what the
customer should do now, not a prior timeline item or an inferred future event.

Close the order only when `terminal` is `true`. A completed payment with
`successful: true` is a successful finish. A terminal failure with
`funds_moved: true` needs support or recovery, not automatic recreation.