Get Quotation

Returns a quotation with fee (total SaaS fee in USD), percentage_fee, fixed_fee, amount_usd (USD notional for the quoted amount), and exchange_rate (USD per one unit of the transaction currency for this quotation) for a PENDING transaction (the getQuotation HTTP handler).

A transaction that has already been passed to executePayout is no longer PENDING and returns 400 TRANSACTION_NOT_PENDING (with current_status). Read its result with getTransaction instead of quoting it again.

Authentication

• REQUIRED: Basic Auth Authorization: Basic base64(client_id:client_secret). Body-based credentials are deprecated and not supported.

• exchange_app_id in the JSON body is ignored; the app id always comes from authentication (a mismatch is logged as a warning only).

Request validation (order)

• tx_id (string, required).

• customer_id (string, required)

• be provided in request body,

• not contain /,

• exist under your account’s registered_customers, and

• match the customer_id bound to the transaction.

• amount (optional): when sent, must be > 0 (400 INVALID_AMOUNT / “amount must be greater than 0 when provided”).

• 401 if authentication fails (AUTHENTICATION_REQUIRED).

Transaction checks

• Loads transactions/{tx_id} (404 TRANSACTION_NOT_FOUND if missing).

• 403 TRANSACTION_NOT_OWNED if the transaction’s exchange_app_id does not match the authenticated app, or if customer_id does not match the transaction’s bound customer_id.

• 400 TRANSACTION_NOT_PENDING if status is not PENDING.

Effective amount

• If the transaction already has a saved amount > 0, that value is used and the request amount is ignored.

• Otherwise the request must supply amount > 0; otherwise 400 INVALID_AMOUNT (“amount must be greater than 0 (provide in request or ensure transaction has amount saved)”).

Pricing

• Currency is taken from stored qr_data.currency (fallback USD if absent).

• Country hint: qr_data.country_code is passed into computePayoutPricingFromAccountRates with the account’s rate rows.

• 400 INVALID_CURRENCY if pricing cannot be computed (bad amount / missing exchange rate for currency).

partner_transaction_id

• Optional. If the transaction has no partner id yet, the first non-empty value sets it on the transaction.

• If a partner id is already stored, omit the field or send the same value; a different value returns 400 INVALID_REQUEST with: partner_transaction_id cannot be changed after it was set (for example in decodeQr). Omit the field or send the same value as stored.

Persistence

• Updates the transaction with amount, amount_usd, fee, percentage_fee, fixed_fee, exchange_rate, currency, quotation_expires_at (30 minutes from quotation time), and updated_at.

Response (200 JSON)

• tx_id, amount, currency

• exchange_rate: 10 decimal places in JSON (formatExchangeRateForApiResponse)

• amount_usd, fee, percentage_fee, fixed_fee: 2 decimal places in JSON (formatUsdForApiResponse; banker-style rounding per apiMoneyFormatting)

• expires_at: ISO 8601 string

• The HTTP response uses rounded values; Firestore may retain higher precision on the transaction document.

Use case: decodeQr → getQuotation (lock amount/fees before executePayout).

Precision: See the collection overview tables for currency input versus USD and exchange-rate field formatting.Corridor amount limits: Quoted local amount must fall within min/max for the transaction corridor (see collection overview). Returns 400 when out of range.

LATAM note: Lock codes from decode expire quickly; executePayout re-locks with the confirmed amount at payout time.