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.
• 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.

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.

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, FUNDED, T_PLUS_ONE)
• 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/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": "FUNDED",
    "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": "FUNDED",
      "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"
    }
  ]
}