Skip to content

Quotes

Quotes let you preview the full cost and outcome of a proposed payment before you initiate it. A quote reflects the exchange rate, fees, and deliverable amount between a source and destination currency, and it is time-sensitive (quotes expire after a defined period). Quotes are central to the Ripple Payments Direct 2.0 payment flow and should be created before you call the Payments endpoint.

What a quote includes

A quote returns the key information you need to decide whether to proceed with a payment, including:

  • Source and destination amounts (sourceAmount, destinationAmount) depending on whether you request a quote by source amount or destination amount. Amounts are rounded to the number of decimal places defined by the ISO 4217 standard for the relevant currency (for example, 2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), using HALF_UP rounding.
  • Adjusted exchange rate (adjustedExchangeRate) that reflects the rate used for conversion.
  • Fees (fees) with a total fee and optional breakdown line items.
  • Taxes (taxes) when applicable (taxes apply to Ripple service fees, not principal).
  • Timestamps and validity (createdAt, expiresAt) and a status (ACTIVE or EXPIRED).

How quotes fit into the payment flow

A typical flow is:

  1. Create a quote collection for a proposed payment (usually returns a single quote).
  2. Select a quote (use the returned quoteId).
  3. Create the payment using the quote information.
Important

In Ripple Payments Direct 2.0, a quote must be accepted/used before it expires. Expired quotes are marked EXPIRED and can’t be used to create payments.

Implementation note

Internally, quote IDs are used in payment creation such that the quoteId used becomes the paymentId. Make sure your integration treats quote identifiers consistently across quote → payment steps.

Quote collections vs. quotes

The API uses “quote collection” terminology, but for Ripple Payments Direct 2.0 today a quote collection typically contains a single quote. A quote collection exists to support retrieval and traceability of the quoting event and to allow future expansion to multiple quote options.

Quote expiration and status

Quotes are time-sensitive:

  • quoteStatus=ACTIVE means the quote can be used to create a payment.
  • quoteStatus=EXPIRED means the quote is no longer valid and must be regenerated.
  • Use expiresAt to implement client-side logic (for example, refresh the quote if the expiration time is near).

Taxes in quotes (fees only)

In jurisdictions where Ripple is required to comply with consumption tax regulations (VAT/GST, etc.), quote responses can include taxes applied to Ripple service fees (fixed/variable fee components), not to the principal payment amount.

Key aspects:

  • Tax calculations provide upfront cost transparency.
  • Taxes are calculated on the fees portion, not the amount being transferred.
  • If no taxes apply (or the calculated tax is zero), the API will not include the taxes object in the response.

Endpoints

Use these endpoints to create and retrieve quotes:

  • POST /v2/quotes/quote-collection — Create a quote collection for a proposed payment.
  • GET /v2/quotes/quote-collection/{quote-collection-id} — Retrieve a previously created quote collection.
  • GET /v2/quotes/{quote-id} — Retrieve a specific quote by ID.

Funding model (payinCategory)

The payinCategory field specifies how you fund the payment. The following values are supported:

ValueDescription
PRE_FUNDINGThe payment is funded from a balance you have pre-deposited with Ripple. Use this for funded account models where you maintain a prefunded ledger balance.
CREDIT_FUNDINGThe payment is settled via an outstanding invoice. Ripple executes the payment and invoices you for the amount afterward.
JIT_FUNDINGThe payment is funded just-in-time: you must transfer the funds to your Ripple ledger account before the payment expires. See JIT-funded payments below.
FUNDEDDeprecated. Equivalent to PRE_FUNDING. Still accepted on v2 quote endpoints; migrate to PRE_FUNDING when ready.
T_PLUS_ONEDeprecated. Equivalent to CREDIT_FUNDING. Still accepted on v2 quote endpoints; migrate to CREDIT_FUNDING when ready.
Deprecation notice

FUNDED and T_PLUS_ONE are deprecated and will be removed in a future release. The v2 quote endpoint currently accepts all five values. New integrations should use PRE_FUNDING, CREDIT_FUNDING, or JIT_FUNDING.

JIT-funded payments

When you use JIT_FUNDING, the payment enters an AWAITING_FUNDING state after it is created. You must transfer the required funds to your Ripple ledger account before the jitFundingExpiresAt timestamp on the payment object. If funding is not received in time, the payment expires and you must create a new quote and payment.

For more information on payment states including AWAITING_FUNDING, see Payment states.

Required inputs for quoting

To create a quote collection, provide:

  • quoteAmount and quoteAmountType (SOURCE_AMOUNT or DESTINATION_AMOUNT)
  • sourceCurrency, destinationCurrency
  • sourceCountry, destinationCountry
  • payinCategory (for example, PRE_FUNDING, CREDIT_FUNDING, JIT_FUNDING)
  • payoutCategory (for example, BANK, CRYPTO)
  • Optional: destinationBlockchainNetwork when quoting crypto payouts.

Error handling

Quote Service errors are standardized into categories such as:

  • AUTH_xxx authorization errors (missing/invalid token)
  • USR_xxx validation errors (missing/invalid request fields)
  • SYS_xxx internal or upstream failures

Errors return a structured object with status and an errors[] array (code, title, type, description, timestamp).

Best practices

  • Use SOURCE_AMOUNT when the sender knows what they want to send.
  • Use DESTINATION_AMOUNT when the sender needs the beneficiary to receive an exact amount.

Example: Create a quote collection

Request

curl -i -X POST \
  http://127.0.0.1:4000/_mock/products/payments-direct-2/@v2026.03/api-docs/payments-direct-api/payments-direct-2-api/v2/quotes/quote-collection \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteAmount": 123.45,
    "quoteAmountType": "SOURCE_AMOUNT",
    "sourceCurrency": "USD",
    "destinationCurrency": "MXN",
    "sourceCountry": "US",
    "destinationCountry": "PH",
    "payoutCategory": "BANK",
    "payinCategory": "PRE_FUNDING",
    "destinationBlockchainNetwork": "Ethereum"
  }'

Response (excerpt)

{
  "quoteCollectionId": "11111111-aaaa-2222-bbbb-222222222222",
  "quotes": [
    {
      "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
      "quoteStatus": "ACTIVE",
      "quoteAmountType": "SOURCE_AMOUNT",
      "sourceAmount": 123.45,
      "destinationAmount": 2438.19,
      "sourceCurrency": "USD",
      "destinationCurrency": "MXN",
      "sourceCountry": "US",
      "destinationCountry": "MX",
      "payoutCategory": "BANK",
      "payinCategory": "PRE_FUNDING",
      "adjustedExchangeRate": {
        "adjustedRate": 2
      },
      "fees": [
        {
          "totalFee": 12.23,
          "feeCurrency": "USD",
          "feeBreakdown": [
            {
              "calculatedFee": 2.43,
              "feeName": "Service fee",
              "feeDescription": "The service fee charged for this transaction."
            }
          ]
        }
      ],
      "taxes": [
        {
          "totalTaxes": 5.12,
          "taxCurrency": "USD",
          "taxBreakdown": [
            {
              "taxAmount": 2.43,
              "taxName": "ISS/ VAT/ GST etc",
              "taxDescription": "The service fee tax charged for this transaction.",
              "taxRate": 5
            }
          ]
        }
      ],
      "createdAt": "2025-11-02T18:26:00.000123Z",
      "expiresAt": "2025-11-02T18:26:00.000123Z",
      "destinationBlockchainNetwork": "Ethereum"
    }
  ]
}
Previous page
Next page