`api.quotes.accept` & `api.quotes.acceptBest`

Two methods, one endpoint. Use acceptBest when you trust the server's ranking. Use accept to pin a specific quote (e.g. the one the user picked in your UI). Both take the same trailing opts. A paymentReason is required; the remaining options supply execution and audit details.

// Accept the server's best pick. A payment reason is always required.
await ..("9d8c…", { : "purchase_of_goods" });
 
// Or pick a specific entry by its id.
await ..("9d8c…", "q_9e4d…", {
  : "purchase_of_goods",
});
 
// Supply the sending wallet at execution time when an inline blockchain
// source did not include it at quote creation.
await ..("9d8c…", {
  : "purchase_of_goods",
  : "0x52908400098527886E0F7030069857D2E4169EE7",
});
 
// With reconciliation fields + safe retry.
await ..("9d8c…", "q_9e4d…", {
  : "purchase_of_services",
  : "invoice-2026-04-001",
  : "Off-ramp for Acme March payroll",
  : .(),
});
 
// Destinations that require a payment-purpose document (see Options)
// attach it as a base64 data URI.
await ..("9d8c…", {
  : "purchase_of_goods",
  : [{ : "invoice", : `data:application/pdf;base64,${}` }],
});
 
// Opt into flexible destination amounts on quote expiry, only when the
// quote supports it (see Options).
const  = await ..("9d8c…");
const  = .[0];
if (
  ..(
    "flexible_destination_amount",
  )
) {
  await ..("9d8c…", ., {
    : "purchase_of_services",
    : "flexible_destination_amount",
  });
}

`acceptBest(id, opts)`

Argument	Type	Notes
`id`	string	Snapshot id.
`opts`	`AcceptQuoteOpts`	See Options below. Required — it carries the mandatory `paymentReason`.

`accept(id, quoteId, opts)`

Argument	Type	Notes
`id`	string	Snapshot id.
`quoteId`	string	Must be one of the quote ids in `snapshot.quotes`.
`opts`	`AcceptQuoteOpts`	See Options below. Required — it carries the mandatory `paymentReason`.

Options

type PaymentReason =
  | "charitable_contributions"
  | "education_fees"
  | "employee_salaries_or_wages"
  | "gifts"
  | "investments"
  | "dividend"
  | "purchase_of_goods"
  | "purchase_of_services"
  | "personal_transfers"
  | "rent"
  | "loans"
  | "utility_bills"
  | "family_support"
  | "friends_support"
  | "real_estate"
  | "insurance"
  | "intercompany_transfer"
  | "taxes"
  | "travel";
 
type SourceOfFunds =
  | "salary"
  | "savings"
  | "business_revenue"
  | "company_capital"
  | "investment_returns"
  | "inheritance"
  | "trust"
  | "gift"
  | "grant"
  | "sale_of_assets"
  | "real_estate"
  | "loan"
  | "private_capital"
  | "marital"
  | "winnings"
  | "other";
 
type TransactionDocumentType =
  | "invoice"
  | "purchase_order"
  | "delivery_slip"
  | "contract"
  | "customs_declaration"
  | "bill_of_lading"
  | "other";
 
interface SupportingFile {
  type: TransactionDocumentType;
  file: string; // data:<mime>;base64,<contents>
}
 
interface AcceptQuoteOpts {
  paymentReason: PaymentReason;
  sourceOfFunds?: SourceOfFunds;
  reference?: string;
  comment?: string;
  idempotencyKey?: string;
  files?: (SupportingFile | string)[]; // bare strings deprecated, rejected from 2026-11-01
  fromAddress?: string;
  returnAddress?: string;
  sourceAccountNumber?: string;
  expiredQuoteBehavior?:
    | "refund_payment"
    | "flexible_destination_amount"
    | "flexible_source_amount";
  expiredQuoteToleranceBps?: number;
}

Field	Notes
`paymentReason`	Required. Why the payment is being made — settlement networks require one of the fixed `PaymentReason` categories, and banks key compliance decisions off it. Not shown to the recipient.
`sourceOfFunds`	Where the money being sent came from. Defaults to the source of funds recorded on the sender's verification profile; set it to declare a different one for this payment only — the profile is left unchanged. Settlement networks require one of the fixed `SourceOfFunds` categories, so a payment with neither is declared as `other`.
`reference`	Message to be included in the transaction. Commonly set to invoice IDs. Echoed back on `RampOrder.reference`. At most `ACCEPT_REFERENCE_MAX_LENGTH` (128) characters, limited to letters, numbers, spaces, dashes, and colons — check ids against the exported `ACCEPT_REFERENCE_PATTERN`, or see Reference format.
`comment`	Free-form note. Echoed on `RampOrder.comment`.
`idempotencyKey`	Sent as the `Idempotency-Key` header. Replays of the same `(id, idempotencyKey)` resolve to the same order instead of throwing `AlreadyAccepted`. Recommended for any caller doing automatic retries.
`fromAddress`	Sending wallet for a blockchain-sourced payment with no attached source account. Overrides the source address captured when the quote was created. Required when neither the quote nor an attached account identifies the source; rejected for fiat sources and attached source accounts.
`returnAddress`	Refund address for stablecoin-sourced payments. If the payment fails or expires, the funds are returned to this address on the source chain. When omitted, it defaults to the sending wallet when one is known. Only valid when the source leg is a stablecoin.
`sourceAccountNumber`	Bank account number the payment will be funded from. Required when the source leg is PHP, IDR, or VND with no attached source account — those networks need the originating account declared before funds are sent. Rejected on payments where it doesn't apply.
`files`	Compliance attachments documenting the purpose of the payment, each a `SupportingFile`: a `type` (one of the supporting document types, exported as `TransactionDocumentType`) and a `file`, the document as a base64 data URI: `data:<mime>;base64,<contents>`. A bare data-URI string is still accepted but deprecated: from November 1, 2026, every file needs a `type`. Check the chosen quote's `acceptance_requirements?.files_required` and attach at least one document when `true`. Additional documents may be requested during processing. Detect the rejection with `acceptRequiresFiles` and retry. The recipient never sees these files. PDF / JPEG / PNG. Minimum 200×200 px for images, max 5 MB per file (`ACCEPT_FILE_MAX_BYTES`), at most 4 files (`ACCEPT_MAX_FILES`). To get an oversized scan under the limit, see Preparing documents before upload.
`expiredQuoteBehavior`	What happens to a payment funded after the quote expired. Defaults to `"refund_payment"`; the `"flexible_*"` values re-quote at the market rate and settle with the destination or source amount recalculated. Only valid when the chosen quote's `supported_expired_quote_behaviors` includes the value. Check it pre-flight. Otherwise the accept throws a typed `expired_quote_behavior` violation. See Expired-quote behavior.
`expiredQuoteToleranceBps`	With `refund_payment`: how far, in basis points (0–500) of what the recipient receives after fees, a payment priced again after the quote expired may fall short of the accepted amount and still be sent. Omit it to use the org's `expired_quote_tolerance_bps`. See Expired-quote behavior.

Returns: Promise<AcceptQuoteResult>, the full order: { id, status, source, destination, funding_instructions?, reference?, comment?, payment_reason?, idempotency_key, created_at }. Read AcceptQuoteResult for the field-level shape.

Throws: ApiError. See the accept endpoint for the full code enum (QuoteIdInvalid, QuoteNotFound, AlreadyAccepted, QuoteNotReady, QuoteExpired, NoNamedQuote).

Document required

Read quote.acceptance_requirements?.files_required before accepting the selected quote. When true, collect a supporting document and pass it in the files option. The field is optional in the SDK for compatibility with older servers; absence means the requirement is unknown. See Quote acceptance requirements and the preflight example.

Keep handling acceptRequiresFiles for additional requirements encountered during processing. When a required document is absent, the accept throws an ApiError carrying a typed violation (field: "files", reason: "missing"). The exported acceptRequiresFiles helper checks for exactly that pair. Use it instead of matching the error text:

try {
  await ..("9d8c…", { : "purchase_of_goods" });
} catch () {
  if (()) {
    const  = await ();
    await ..("9d8c…", {
      : "purchase_of_goods",
      : [{ : "invoice", :  }],
    });
  } else {
    throw ;
  }
}

The snapshot stays acceptable after the rejection. Retry the same accept with files populated before the quote expires.

REST endpoint: POST /quotes/:id/accept.

api.quotes.accept & api.quotes.acceptBest

acceptBest(id, opts)

accept(id, quoteId, opts)

Options

Document required

`api.quotes.accept` & `api.quotes.acceptBest`

`acceptBest(id, opts)`

`accept(id, quoteId, opts)`