Generate Quote Guide

CROSSFX API · QUOTES

Price the transfer and create its tracking identity.

Generate a time-limited quote for an open corridor, fixing either what the sender pays or what the beneficiary receives.

This is also where the transfer lifecycle begins. The response issues the cbtx_tracking_id used by every downstream transaction call.

Send-fixedReceive-fixedTime-limitedBeneficiary-specificTracking ID issued

How quoting works

A quote combines the corridor, beneficiary, funding configuration and one fixed amount into a priced transfer offer.

01

Choose corridor

Source → destination

→

02

Choose beneficiary

Use identifier

→

03

Fix one amount

Send or receive

→

04

Price quote

expires_at

→

05

Carry forward

cbtx_tracking_id

Send-fixed

Fix what the sender pays

Send `source_amount` and let CrossFX calculate the destination amount.

Receive-fixed

Fix what the beneficiary receives

Send `destination_amount` and let CrossFX calculate the source amount.

Time-limited

Respect expires_at

The quote is valid only until the expiry timestamp returned in the response.

Transfer identity

Store cbtx_tracking_id

The tracking ID is created here and becomes the primary transfer identifier for downstream calls.

Before you start

Authentication

Use a valid bearer token

See the Authentication Guide.

Beneficiary

Create the recipient first

Use the beneficiary `identifier` returned by the [Create Beneficiary Guide](/create-beneficiary-guide-2167568m0).

Open corridor

Validate the pair

Check the [Supported Corridors Guide](/supported-corridors-guide-2167517m0) before generating the quote.

Generate a quote

Generate Quote

Price a transfer

`POST /api/v1/transfers/quote`

Open the API Reference for the full request and response schemas and an interactive console.

REQUEST & RESPONSE

Send the corridor, beneficiary, funding source, source token type and exactly one amount.

The response returns the priced quote, expires_at and the transfer's cbtx_tracking_id.

Choose which amount to fix

The request supports two pricing modes, but they are mutually exclusive.

SOURCE FIXED

source_amount

Use this when the sender knows exactly how much they want to pay. CrossFX calculates the resulting destination amount.

DESTINATION FIXED

destination_amount

Use this when the beneficiary must receive an exact amount. CrossFX calculates what the sender must provide.

EXACTLY ONE

Send one amount field, never both.

Sending both source_amount and destination_amount, or sending neither, returns 422 VALIDATION_FAILED. Because this is a whole-request rule, the message appears under error.json._schema.

Quote configuration

Two additional values describe how the transfer is being funded and represented.

source_token_type

Currently CASH

`CASH` is the only value currently exposed.

It is matched case-sensitively.

Despite the field name, it does not determine the funding method.

funding_source

Who provides the funds

Accepted values are:

`client_funds`

`aggregator_funds`

Store the tracking ID

cbtx_tracking_id is the primary identifier for the transfer lifecycle.

PRIMARY TRANSFER IDENTIFIER

cbtx_tracking_id

Carry the exact value returned by the quote into Confirm, Deposit, Payout and status calls. A hand-written or regenerated UUID does not identify the quote and returns 404.

QUOTE

cbtx_tracking_id issued

→

CONFIRM

Create transfer

→

DEPOSIT

Fund transfer

→

PAYOUT

Disburse funds

→

STATUS

Track outcome

Quote expiry and consumption

A quote is temporary and single-use.

EXPIRES

Respect expires_at

Once the returned expiry timestamp passes, generate a new quote. Confirming an expired quote is rejected.

SINGLE USE

Confirm consumes the quote

A quote is consumed by Confirm Transfer and cannot be used as a reusable pricing instruction.

Validate the corridor before quoting

country_code and destination_currency_code must represent a valid pairing.

VALIDATE EARLY

Country and destination currency must agree.

A mismatched destination country and currency can fail later in the transfer lifecycle. Validate the pairing on your side against the supported corridor list before creating the quote.

Business rules

AMOUNT

Send exactly one

Use either source_amount or destination_amount, never both.

TRACKING

Carry the ID exactly

Use the returned cbtx_tracking_id unchanged in every downstream transfer call.

EXPIRY

Re-quote when expired

Once expires_at passes, generate a new quote rather than trying to confirm the old one.

CORRIDOR

Validate before pricing

Check that the country and currency combination is valid before generating the quote.

Errors

Every error below returns the CrossFX platform error envelope, with error first and error_id last.

SUPPORT IDENTIFIER

Keep the error_id

Quote the returned error_id when contacting CrossFX support so the request can be located in platform logs.

HTTP	`code`	Trigger	What you do
422	`VALIDATION_FAILED`	A required field is missing, null, or the wrong type, or an enum value is not allowed	Read `error.json` for the field.
422	`VALIDATION_FAILED`	The body carries a field the endpoint does not accept	Read `error.json` for the field name and remove it.
422	`VALIDATION_FAILED`	Both amounts were sent, or neither was	Send exactly one. The message arrives under `error.json._schema`.
404	`NOT_FOUND`	A currency or the country is not recognised	Check the codes against the corridor list.
404	`NOT_FOUND`	The `beneficiary_id` cannot be resolved	Use the `identifier` from the beneficiary create response.
422	`VALIDATION_FAILED`	The corridor has no active pricing configuration	Contact support with the pair.
422	`VALIDATION_FAILED`	The amount is outside the limits the corridor accepts	Quote an amount within the corridor's range.
400	`BAD_REQUEST`	The amount is too small to leave anything to deliver	Send a larger amount.
422	`PRICING_EVALUATION_FAILED`	The corridor's rate varies with the amount, so a receive-fixed quote cannot be solved	Quote by `source_amount` instead.
500	`INTERNAL_ERROR`	An unexpected internal error while quoting	Retry with backoff.
401	—	The `Authorization` header is missing, malformed, or the token has expired	Request a new token and retry. The body is `{ "message": "Unauthorized" }`.

Receive-fixed pricing failures

PRICING_EVALUATION_FAILED is specific to pricing evaluation rather than request shape.

FALLBACK

Switch to source_amount

If the corridor's pricing varies with amount and a receive-fixed quote cannot be solved, generate the quote using source_amount instead.

Create Beneficiary Guide

Create the recipient

Register the beneficiary whose `identifier` is used when generating the quote.

FX Rates Guide

Show indicative pricing

Retrieve a current effective rate without creating or consuming a quote.

Supported Corridors Guide

Validate the pair

Retrieve the source and destination currency pairs currently available for quoting.

How quoting works#

Before you start#

Generate a quote#

Choose which amount to fix#

Quote configuration#

Store the tracking ID#

Quote expiry and consumption#

Validate the corridor before quoting#

Business rules#

Errors#

Receive-fixed pricing failures#

Related#