SZNDSZND
Get Started
IntroductionAuthenticationCollectionsPayoutsWalletsQuotesWebhooksPlayground

Create and Accept Quotes

Use this page when you need the operational details behind the quote lifecycle: creating a quote, accepting it, reading it back, and understanding when payment instructions are returned.

What This Page Covers

This page documents the quote-first flow used by pricing-sensitive transactions such as:

  • EXCHANGE
  • WITHDRAWAL
  • TRANSFER
  • SWAP
  • DIRECT_EXCHANGE
  • some explicit DEPOSIT flows

It also explains where deposit flows behave differently, because not every deposit starts with a client-created quote.

All examples use the Business API (POST /api/v1/client/* with x-api-key / x-timestamp / x-signature). The same shape is used for POST /api/v1/quotes/v2 (Bearer) but this page is written for the client integration.

The Main Endpoints

Use these client endpoints for quote-driven flows:

  • POST /api/v1/client/quotes — create a quote
  • POST /api/v1/client/quotes/{id}/accept — accept and execute
  • GET /api/v1/client/quotes/{id} — read back latest quote state

Typical Quote-First Flow

The normal sequence is:

  1. create the quote
  2. inspect pricing, fees, and expiry (timeline.valid_until)
  3. accept the quote before expiry
  4. collect payment_details or continue fulfillment for wallet/internal flows
  5. track the resulting transaction by webhook or GET /api/v1/client/transactions/v2/{id}

In many corridors, quote acceptance is the point where the platform returns the payment details the payer must use.

Create A Quote

Send a POST /api/v1/client/quotes request with the pricing intent.

Required Fields (Client API)

FieldTypeNotes
source_currencystringSource currency or stablecoin token (e.g. USD, NGN, USDC)
target_currencystringPayout/converted currency
source_amountstringDecimal string, must be >= 0.01. Invalid → 400 invalid source amount
quote_typestringOne of EXCHANGE, WITHDRAWAL, DEPOSIT, SWAP, DIRECT_EXCHANGE, TRANSFER
tzstringIANA timezone for limits/pricing windows
origin_referencestring max:40Required for POST /api/v1/client/quotes. Must be unique — duplicate → 400 duplicate quote, origin_reference already exists. Your idempotency/reconciliation key.
on_behalf_ofstringRequired for Business API — "self" (business owner) or a customer UUID. The beneficiary_id you pass must belong to this same customer.

Commonly Used Fields

  • beneficiary_id Required for most payout-style flows (EXCHANGE, DIRECT_EXCHANGE, fiat WITHDRAWAL).

  • narration Free-text description for the payout. Returned as narration in the quote response.

  • payment_method oneof=FIAT CRYPTO Optional — inferred from currencies when omitted. If you send it, it must match inference or you get 400 payment_method does not match currency pair; expected FIAT/CRYPTO. Stablecoin source requires DEPOSIT/DIRECT_EXCHANGE; stablecoin target requires WITHDRAWAL.

  • payment_network (ETH, SOL, BSC, MATIC) Required for crypto-funded flows.

  • payment_address Wallet address — required when target is a crypto withdrawal.

  • user_tag Used only for TRANSFER — recipient's handle instead of beneficiary_id.

Conditional / Rail-Specific Fields

  • payer_email string,email Required when rail: "INTERAC_REQUEST". CAD DEPOSIT/DIRECT_EXCHANGE pull collection (money request). Capped at 1500 CAD per request. Does not register a user.

  • payer_name string Required when rail: "INTERAC_REQUEST". Name printed on the Interac request email (the person being asked to pay). Max 120 characters. Does not register a user or start KYC.

  • bank_code / phone_number Mobile Money rails (MOBILE_MONEY) and ZAR_BANK_ACCOUNT. phone_number must be international format without + (e.g. 255712345678). Use operator code from GET /api/v1/client/banks/{country}?type=momo as bank_code.

  • rail Optional rail override. Validated per quote_type + currency:

    • ACH / WIRE / SWIFT — USD DIRECT_EXCHANGE, EXCHANGE, WITHDRAWAL (USD target)
    • INTERAC_REQUEST — CAD DEPOSIT/DIRECT_EXCHANGE source
    • EFT — CAD DIRECT_EXCHANGE/WITHDRAWAL/EXCHANGE target
    • MOBILE_MONEY / ZAR_BANK_ACCOUNT — mobile money / ZAR corridors Invalid rail → 400 rail is only supported for ....

Quote Types And What They Usually Mean

  • EXCHANGE — standard conversion with external beneficiary
  • WITHDRAWAL — money-out from wallet/balance to payout destination
  • DEPOSIT — money-in flow (often funds-first, see below)
  • SWAP — internal or near-instant conversion (internal ledger, no external payout)
  • DIRECT_EXCHANGE — payment-in plus payout in one flow, often with funding instructions
  • TRANSFER — user-to-user using user_tag (internal ledger)

Transfer Quotes And user_tag

For TRANSFER quotes, the destination is identified by user_tag instead of beneficiary_id.

Practical rules:

  • send quote_type: "TRANSFER", source_currency == target_currency (same-ledger move)
  • provide recipient's user_tag
  • do not reuse your own handle as destination
  • keep tag lowercase and alphanumeric
  • on_behalf_of still owns the quote; the receiver is resolved from the tag

Example:

json
{  "source_currency": "USD",  "target_currency": "USD",  "source_amount": "50.00",  "quote_type": "TRANSFER",  "tz": "UTC",  "origin_reference": "TRANSFER-2026-000045",  "on_behalf_of": "self",  "user_tag": "recipient123"}

CAD Interac Money Request

By default, CAD deposits collect with Interac e-Transfer Auto Deposit (INTERAC): the payer sends funds to the email in payment_details.interac_payment_info.

To pull instead, create the quote with rail: "INTERAC_REQUEST". After accept, the platform sends an Interac money request to payer_email. The email greeting uses payer_name (the person being asked to pay). The payer approves it in their banking app. Settlement credits the quote owner's wallet — for a business using on_behalf_of: "self", that is the business wallet. payer_email and payer_name do not register a customer or start KYC.

Use this rail for:

  • quote_type: "DEPOSIT" with source_currency: "CAD" (wallet collection)
  • quote_type: "DIRECT_EXCHANGE" with CAD source (collect CAD, then pay out the target)

Rules

  • payer_email is required
  • payer_name is required (max 120 characters). It is the name on the Interac email, not a registered user
  • source_amount must be 1500.00 CAD or less
  • omit rail (or do not set INTERAC_REQUEST) if you want the default Auto Deposit flow
  • amounts above 1500 CAD must use Auto Deposit (INTERAC), not money request

Sample Request: CAD Deposit

POST /api/v1/client/quotes

json
{  "source_currency": "CAD",  "target_currency": "CAD",  "source_amount": "200.00",  "quote_type": "DEPOSIT",  "payment_method": "FIAT",  "tz": "UTC",  "rail": "INTERAC_REQUEST",  "payer_email": "yuri.petrov@example.com",  "payer_name": "Yuri Petrov",  "origin_reference": "CAD-IR-2026-000200",  "on_behalf_of": "self"}

Sample Request: CAD Direct Exchange

Same rail, payer_email, and payer_name, plus a beneficiary_id for the payout destination:

json
{  "source_currency": "CAD",  "target_currency": "NGN",  "source_amount": "500.00",  "quote_type": "DIRECT_EXCHANGE",  "payment_method": "FIAT",  "tz": "UTC",  "rail": "INTERAC_REQUEST",  "payer_email": "yuri.petrov@example.com",  "payer_name": "Yuri Petrov",  "beneficiary_id": "123e4567-e89b-12d3-a456-426614174000",  "origin_reference": "CAD-IR-DX-2026-000500",  "on_behalf_of": "123e4567-e89b-12d3-a456-426614174000"}

Create still only prices the quote. The money request is sent when you accept:

  • POST /api/v1/client/quotes/{id}/accept

Sample Accept Response

json
{  "quote_id": "123e4567-e89b-12d3-a456-426614174000",  "transaction_id": "123e4567-e89b-12d3-a456-426614174001",  "transaction_reference": "C1AZWXMuKc5A",  "payment_details": {    "quote_id": "123e4567-e89b-12d3-a456-426614174000",    "type": "interac_request_payment_info",    "interac_request_payment_info": {      "email": "payer@example.com",      "reference": "REQREF001",      "expires_at": "2026-08-10T00:00:00Z",      "payment_instructions": "We sent an Interac money request for CAD200.00 to payer@example.com. Approve it in your banking app to complete this payment."    }  },  "total_payable": "207.00",  "timeline": {    "created_at": "2026-05-03T01:10:53Z",    "valid_until": "2026-05-03T02:10:53Z"  },  "status": "AWAITING_PAYMENT"}

Show the payer payment_instructions and the email the request was sent to. Track completion with transaction webhooks; do not assume the payer has approved until the webhook confirms it.

Deposit Quotes: Explicit Vs Implicit

Explicit Deposit Quotes

Some corridors behave like normal quote-first flows:

  1. you create the quote
  2. you accept it
  3. the platform returns funding instructions
  4. the user sends funds

This pattern is common when the platform needs to generate or confirm deposit instructions before money arrives.

Implicit Deposit Quotes

Other corridors are effectively funds-first:

  1. the user sends money to an assigned account or address
  2. the deposit confirmation arrives
  3. the platform creates the internal deposit quote and transaction
  4. your system tracks the result through transactions and webhooks

This means a missing client-side POST /api/v1/client/quotes call does not always mean “no quote exists.” In some deposit flows, the platform creates the quote internally after the money movement starts. For the Business API, deposits via POST /api/v1/client/virtual-wallets + webhooks are more common than client DEPOSIT quotes.

Create Quote Example

This example shows a quote-first request for a payout-style flow:

json
{  "source_currency": "USD",  "target_currency": "NGN",  "source_amount": "1000.00",  "beneficiary_id": "123e4567-e89b-12d3-a456-426614174000",  "quote_type": "DIRECT_EXCHANGE",  "tz": "UTC",  "origin_reference": "ORDER-2026-000123",  "on_behalf_of": "self",  "narration": "Vendor payment",  "payment_method": "FIAT"}

Create Quote Response (201)

json
{  "quote_id": "123e4567-e89b-12d3-a456-426614174000",  "status": "CREATED",  "type": "DIRECT_EXCHANGE",  "source": { "currency": "USD", "amount": "1000.00" },  "target": { "currency": "NGN", "amount": "1500000.00" },  "rate": "1500.00",  "fees": {    "processing_fee": "10.00",    "deposit_fee": "5.00",    "payout_fee": "2.50",    "total_fees": "17.50",    "fee_currency": "USD"  },  "total_payable": "1017.50",  "narration": "Vendor payment",  "timeline": {    "created_at": "2026-05-03T01:10:00Z",    "valid_until": "2026-05-03T01:40:00Z"  },  "beneficiary": {    "id": "123e4567-e89b-12d3-a456-426614174000",    "first_name": "John",    "last_name": "Doe",    "bank_name": "Access Bank",    "currency_code": "NGN",    "country_code": "NG",    "email": "john@example.com"  },  "funding_method": { "id": 0, "name": "", "description": "", "display_name": "", "speed": "" }}

Expiry is 30 minutes (90 minutes for INTERAC). At this stage, the quote is priced but not yet committed. Fees are in fee_currency == source_currency.

Validation you will hit often: 422 insufficient wallet balance, 422 amount outside limit bounds, 429 same CAD payout amount/beneficiary ... wait at least 2 minutes, 422 customer KYC is incomplete for CAD/GBP/EUR when on_behalf_of customer not verified.

Accept A Quote

Once the pricing is accepted, call:

  • POST /api/v1/client/quotes/{id}/accept

Inside a transaction the platform re-checks valid_until, reserves/deducts wallet funds, creates holds/ledger legs and may call the payout rail. Expired quotes are terminal — 422 quote has expired.

Acceptance may:

  • reserve or deduct wallet funds
  • return bank transfer / ACH / wire / Interac instructions
  • return blockchain funding details for crypto withdrawals
  • immediately complete for internal flows (TRANSFER/SWAP → is_internally_completed: true)

Accept Quote Response (200)

json
{  "quote_id": "123e4567-e89b-12d3-a456-426614174000",  "transaction_id": "123e4567-e89b-12d3-a456-426614174001",  "transaction_reference": "C1AZWXMuKc5A",  "payment_details": {    "quote_id": "123e4567-e89b-12d3-a456-426614174000",    "type": "ACH",    "provider_reference": "TX-789012",    "is_internally_completed": false,    "ach_payment_info": {      "bank_account_number": "9876543210",      "bank_routing_number": "021000021",      "bank_beneficiary_name": "Example Inc",      "bank_name": "Bank of America",      "payment_instructions": "Please initiate ACH transfer using the account details above. Use your quote ID as reference."    }  },  "total_payable": "1017.50",  "timeline": {    "created_at": "2026-05-03T01:10:53Z",    "valid_until": "2026-05-03T01:40:53Z"  },  "status": "AWAITING_PAYMENT"}

For checkout-style corridors, fee_bearer / merchant_amount / fees_amount may be present.

Read A Quote Back

Use GET /api/v1/client/quotes/{id} to retrieve the latest quote state — same shape as create, with timeline.deposit_confirmed_at / completed_at populated as the quote progresses. Useful for refreshes, recovery, and reconciliation.

Quote Statuses You Should Expect

The main states you will see via client:

  • CREATED — quote exists and can still be accepted
  • AWAITING_PAYMENT — accepted, waiting for payer to fund
  • PAYMENT_CONFIRMED — funding leg confirmed
  • PROCESSING_PAYOUT — payout/delivery leg running
  • COMPLETED — quote-driven transaction finished
  • EXPIRED — not accepted in time (valid_until is authoritative)
  • FAILED — quote or follow-on transaction could not complete
  • PENDING_COMPLIANCE_REVIEW / REVERSED — compliance hold / reversed (you may see these on cross-border corridors)

Use GET /api/v1/client/quotes/{id} status plus timeline for polling, but prefer webhooks for final state.

Limits, Fees And Expiry

  • valid_until is 30m (USD/CAD/EFT etc.) and 90m when funding method is INTERAC. Respect it — old quotes should be recreated, not reused.
  • rate is spread-adjusted and rounded; target_amount = source_amount * rate rounded to 2 decimals. Fees use ceiling rounding to 2 decimals.
  • Per-corridor min/max enforced; outside → 422.
  • Wallet check is done optimistically then authoritatively under lock → 422 insufficient wallet balance if available_balance < total_payable.

Practical Rules For Integrators

  1. Treat origin_reference as required for POST /api/v1/client/quotes (max 40, unique). Persist it — it is your idempotency key.
  2. on_behalf_of for Business API must be "self" or a customer UUID that owns beneficiary_id; otherwise 401/422.
  3. Always persist quote_id and transaction_reference from accept; transaction_id is the GET /api/v1/client/transactions/v2/{id} key.
  4. Do not assume all deposits are explicit quote-first — many are funds-first via virtual wallets/webhooks.
  5. Read payment_details.type before deciding how to render funding instructions; handle all cases above, especially INTERAC_REQUEST vs INTERAC.
  6. Prefer webhooks for final state changes instead of polling alone.
  7. Respect valid_until; do not retry accept on expired — create a new quote.
  8. For CAD pull, send rail: INTERAC_REQUEST + payer_email + payer_name and keep source_amount at or below 1500 CAD. on_behalf_of: "self" credits the business wallet without registering the payer.

Related Pages