Fetch a quote collection

Before you can create a payment, you request a quote collection: a set of priced quotes for a proposed transfer. Each quote locks in an exchange rate, fee breakdown, and validity window so you can review the terms before committing to a payment.

This guide covers:

1. Creating a quote collection, quoting by source or destination amount.
2. Reading the response.
3. Handling quote expiry.
4. Retrieving a quote collection or individual quote after creation.

For conceptual background, see Quotes and exchange rates.

To follow this guide, you need:

• Access to the Payments Direct API UAT environment.
• A valid OAuth2 access token with the quote_collections:write scope. See Request an access token.
• The source and destination currencies and countries for the proposed payment.
• A payinCategory that matches your funding model (PRE_FUNDING, CREDIT_FUNDING, or JIT_FUNDING). See Funding methods.
• A payoutCategory of BANK or CRYPTO.

POST /v2/quotes/quote-collection

A quote collection request specifies the corridor, payout category, and amount you want to price. A quote collection typically contains a single quote.

curl -i -X POST \
  https://api.test.ripple.com/v2/quotes/quote-collection \
  -H "Authorization: Bearer <YOUR_JWT_HERE>" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteAmount": 10000.00,
    "quoteAmountType": "SOURCE_AMOUNT",
    "sourceCurrency": "USD",
    "destinationCurrency": "MXN",
    "sourceCountry": "US",
    "destinationCountry": "MX",
    "payinCategory": "PRE_FUNDING",
    "payoutCategory": "BANK"
  }'

A successful request returns HTTP 201 with a quote collection. The top-level quoteCollectionId identifies the collection; the quotes array contains the returned quote.

{
  "quoteCollectionId": "11111111-aaaa-2222-bbbb-222222222222",
  "quotes": [
    {
      "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
      "quoteStatus": "ACTIVE",
      "quoteAmountType": "SOURCE_AMOUNT",
      "sourceAmount": 10000.00,
      "destinationAmount": 204533.30,
      "sourceCurrency": "USD",
      "destinationCurrency": "MXN",
      "sourceCountry": "US",
      "destinationCountry": "MX",
      "payoutCategory": "BANK",
      "payinCategory": "PRE_FUNDING",
      "adjustedExchangeRate": {
        "adjustedRate": 20.4136
      },
      "fees": [
        {
          "totalFee": 14.00,
          "feeCurrency": "USD",
          "feeBreakdown": [
            {
              "calculatedFee": 2.00,
              "feeName": "Fixed service fee",
              "feeDescription": "Fixed service fee for this transaction."
            },
            {
              "calculatedFee": 12.00,
              "feeName": "Variable service fee",
              "feeDescription": "Variable service fee for this transaction."
            }
          ]
        }
      ],
      "createdAt": "2025-11-13T22:44:34.711Z",
      "expiresAt": "2025-11-13T22:59:34.711Z"
    }
  ]
}

Quotes are valid for a limited time (15 minutes by default). Before creating a payment, check that quoteStatus is ACTIVE.

• If quoteStatus is ACTIVE, the quote can be used to create a payment.
• If quoteStatus is EXPIRED, the quote can no longer be used. Request a new quote collection, which will reflect the current exchange rate and fees.

Use expiresAt to implement client-side refresh logic, for example, prompting a user to confirm before the quote lapses, or automatically re-quoting when the remaining time falls below a threshold.

remainingSeconds = expiresAt - now()
if remainingSeconds <= 0:
    request a new quote collection

Re-quoting generates a new quoteCollectionId and new quoteId values.

GET /v2/quotes/quote-collection/{quote-collection-id}

Use this endpoint to retrieve a quote collection you created earlier, for example in an async flow where you stored the quoteCollectionId and are checking quote status before initiating a payment.

curl -i -X GET \
  https://api.test.ripple.com/v2/quotes/quote-collection/11111111-aaaa-2222-bbbb-222222222222 \
  -H "Authorization: Bearer <YOUR_JWT_HERE>"

The response schema is identical to the POST response. Check the quote's quoteStatus before proceeding; the quote may have expired since it was created.

GET /v2/quotes/{quote-id}

Use this endpoint to retrieve a specific quote by ID.

curl -i -X GET \
  https://api.test.ripple.com/v2/quotes/7ea3399c-1234-5678-8d8f-d320ea406630 \
  -H "Authorization: Bearer <YOUR_JWT_HERE>"

The response contains the same fields as a single entry from the quotes array, without the quoteCollectionId wrapper.

Quote errors return a structured response with a status and an errors array. Each error includes code, title, type, description, and timestamp.

Error codes use three prefixes:

Missing payoutCategory: The v2 endpoint requires payoutCategory. Omitting it returns a USR_ validation error.

Invalid currency or country codes: sourceCurrency and destinationCurrency must be 3–5 alphabetic characters. sourceCountry and destinationCountry must be ISO 3166-1 alpha-2 codes (exactly 2 characters).

Deprecated payinCategory values: FUNDED and T_PLUS_ONE are still accepted on the v2 endpoint but are deprecated. Use PRE_FUNDING in place of FUNDED, and CREDIT_FUNDING in place of T_PLUS_ONE. See Funding methods.

Unsupported corridor: If the currency pair is not configured for your tenant, the API returns a CFG_ error. Contact your Ripple representative if the error persists.

Once you have an ACTIVE quote and have selected a quoteId, you are ready to create a payment.

See Create a payment for a complete walkthrough of the payment creation step, including how to pass the quoteId alongside beneficiary identity and financial instrument IDs.