Skip to main content
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 and use that environment consistently for all credentials and resources. Complete 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 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, then use its access_token to register a public HTTPS endpoint. Store the returned signing_secret immediately: it is shown only once. Implement delivery verification and deduplication 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 for active symbols and decimals.
  2. List 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 for QR, direct bank-transfer, and mobile-money fields.
  4. List 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 with a complete partner_end_user_kyc_v1 record and inline artifacts. Follow the required fields and artifact rules in 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 with the latest base_kyc_version. Do not create a second end user merely because a request timed out; follow KYC retry guidance.

​
5. Wait for the required fiat rails

Poll 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 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 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 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 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 for the supported payment shapes.

​
8. Create one payment when the customer commits

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

​
10. Track to a terminal outcome

Consume verified webhooks, deduplicate by x-agentbank-delivery-id, and use 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.