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.

The Main Endpoints

Use these client endpoints for quote-driven flows:

  • POST /api/v1/client/quotes
  • POST /api/v1/client/quotes/{id}/accept
  • GET /api/v1/client/quotes/{id}
  • GET /api/v1/client/quotes/borderless-deposit-instructions/{id}

Typical Quote-First Flow

The normal sequence is:

  1. create the quote
  2. inspect pricing, fees, and expiry
  3. accept the quote
  4. collect funds or continue fulfillment
  5. track the resulting transaction by webhook or follow-up reads

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.

Core Inputs

These fields are the backbone of most quote requests:

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

Commonly Used Fields

  • source_currency The currency or token the flow starts from.
  • target_currency The payout or converted currency.
  • source_amount Amount to price.
  • quote_type The transaction intent.
  • tz IANA timezone used for limits and pricing windows.
  • origin_reference Your own reference for reconciliation and duplicate protection.
  • on_behalf_of The user or business entity the quote belongs to.

Optional But Important Fields

  • beneficiary_id Commonly required for payout-style flows such as EXCHANGE, DIRECT_EXCHANGE, and fiat WITHDRAWAL.
  • payment_method FIAT or CRYPTO. If omitted, the platform may infer it from the currencies involved.
  • payment_network Required for crypto-funded flows.
  • payment_address Required when the target side is a crypto withdrawal.
  • user_tag Used for TRANSFER flows.
  • bank_code Used in some KES corridors.
  • phone_number Used in some mobile money corridors.
  • rail Optional USD rail override for supported corridors, usually ACH or WIRE.

Quote Types And What They Usually Mean

  • EXCHANGE Standard conversion flow with an external beneficiary or destination.
  • WITHDRAWAL Money-out flow from wallet or account balance to a payout destination.
  • DEPOSIT Money-in flow. Some deposit corridors are explicit quote-first flows, while others are funds-first.
  • SWAP Internal or near-instant conversion flow.
  • DIRECT_EXCHANGE A payment-in plus payout flow, often involving funding instructions.
  • TRANSFER User-to-user movement using a destination user tag.

Transfer Quotes And user_tag

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

Practical rules:

  • send quote_type: "TRANSFER"
  • provide the recipient's user_tag
  • do not reuse your own user tag as the destination
  • keep the tag lowercase and alphanumeric

The current transfer validation expects a short lowercase handle rather than a free-form identifier.

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"}

Deposit Quotes: Explicit Vs Implicit

This is the part that often causes confusion.

Explicit Deposit Quotes

Some deposit corridors still 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 provider-side deposit instructions before money arrives.

Implicit Deposit Quotes

Other deposit corridors are effectively funds-first:

  1. the user sends money to an assigned account or provider address
  2. the provider webhook 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.

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": "123e4567-e89b-12d3-a456-426614174000",  "payment_method": "FIAT"}

Create Quote Response

json
{  "quote_id": "123e4567-e89b-12d3-a456-426614174000",  "source": {    "currency": "USD",    "amount": "1000.00"  },  "target": {    "currency": "NGN",    "amount": "1500000.00"  },  "exchange_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",  "valid_until": "2026-05-03T01:40:53Z",  "quote_status": "CREATED",  "type": "DIRECT_EXCHANGE"}

At this stage, the quote is priced but not yet committed.

Accept A Quote

Once the user or business accepts the pricing, call:

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

Acceptance advances the quote into execution and may do one of several things depending on corridor:

  • reserve or deduct wallet funds
  • return bank transfer instructions
  • return ACH or wire instructions
  • return blockchain funding details
  • immediately complete the transaction for internal flows such as some swaps

Accept Quote Response

The accept response usually includes:

  • quote_id
  • transaction_id
  • transaction_reference
  • payment_details
  • total_payable
  • timeline
  • status

Example:

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_name": "BORDERLESS",    "provider_reference": "BORDERLESS-789012",    "ach_payment_info": {      "account_number": "9876543210",      "routing_number": "021000021",      "account_name": "Transfaar Technologies 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"}

Payment Details You May Receive

Depending on the funding rail, payment_details.type can return different instruction shapes:

  • WALLET Internal wallet deduction or balance-based settlement.
  • NGN_PAYMENT Local bank transfer instructions.
  • INTERAC Interac e-transfer instructions.
  • ACH US ACH funding instructions.
  • WIRE or WIRE_TRANSFER Wire transfer instructions.
  • BLOCKCHAIN Funding address, network, and token details for crypto flows.

This is why the quote accept step matters: it is often where the funding instructions become concrete.

Borderless USD Deposit Instructions

For some Borderless USD deposit corridors, the full ACH or wire instructions may be read again later with:

  • GET /api/v1/client/quotes/borderless-deposit-instructions/{id}

Use this when:

  • the quote has already been created and accepted
  • the source provider is Borderless
  • you need the latest USD deposit instructions again without recreating the quote

Read A Quote Back

Use GET /api/v1/client/quotes/{id} to retrieve the latest quote state, including:

  • quoted amounts
  • fees
  • exchange rate
  • current quote status
  • expiry window

This is useful for refreshes, recovery flows, and reconciliation.

Quote Statuses You Should Expect

The exact lifecycle varies by corridor, but these are the main states you will see:

  • CREATED The quote exists and can still be accepted.
  • AWAITING_PAYMENT The quote has been accepted and the platform is waiting for the payer to fund it.
  • PAYMENT_CONFIRMED The funding leg has been confirmed.
  • PROCESSING_PAYOUT The payout or delivery leg is running.
  • COMPLETED The quote-driven transaction finished successfully.
  • EXPIRED The quote was not accepted in time.
  • FAILED The quote or follow-on transaction could not complete.

Some deposit-style flows may use AWAITING_DEPOSIT or DEPOSIT_CONFIRMED terminology in surrounding operational flows.

Practical Rules For Integrators

  1. Treat origin_reference as required in practice, even when a corridor does not technically enforce it.
  2. Always persist quote_id and transaction_reference.
  3. Do not assume all deposits are explicit quote-first transactions.
  4. Read payment_details.type before deciding how to render funding instructions.
  5. Prefer webhooks for final state changes instead of polling alone.
  6. Respect valid_until; old quotes should be recreated, not reused.

Related Pages