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


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.


## 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**


```bash
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)**


```json
{
  "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"
    }
  ]
}
```