Obter uma coleção de cotações

Antes de poder criar um pagamento, você solicita uma coleção de cotações: um conjunto de cotações precificadas para uma transferência proposta. Com /v3/quotes, a coleção contém uma cotação para cada payment rail disponível para o corredor. Cada cotação tem a sua própria taxa de câmbio e o seu próprio detalhamento das tarifas, e todas as cotações da coleção expiram ao mesmo tempo. Revise as condições e escolha uma cotação antes de se comprometer com um pagamento.

Este guia abrange:

1. Criar uma coleção de cotações, cotando pelo valor de origem ou de destino.
2. Ler a resposta e escolher uma cotação.
3. Tratar o caso em que a cotação expira.
4. Solicitar uma cotação para apenas um payment rail.
5. Recuperar uma coleção de cotações ou uma cotação individual após a criação.

Para o embasamento conceitual, consulte Cotações.

Para seguir este guia, você precisa de:

• Acesso ao ambiente UAT da API do Payments Direct.
• Um token de acesso OAuth2 válido com o escopo quote_collection:quote:create para criar coleções de cotações e os escopos quote_collection:quote:read e quote:quote:read para recuperá-las. Consulte Solicitar um token de acesso.
• As moedas e os países de origem e de destino do pagamento proposto.
• Um payinCategory que corresponda ao seu modelo de financiamento (PRE_FUNDING, CREDIT_FUNDING ou JIT_FUNDING). Consulte Métodos de financiamento.
• Identidades criadas com as operações de identidade v3, exigidas por /v3/quotes. Esta versão da API documenta apenas essas operações, portanto você já atende a esse requisito, a menos que tenha integrado com uma versão anterior. Consulte Criar e gerenciar identidades.

POST /v3/quotes/quote-collection

Uma requisição de coleção de cotações especifica o corredor e o valor que você quer precificar. A resposta contém uma cotação para cada payment rail disponível para esse corredor, exceto os que a Ripple não consegue precificar. Nem todos os payment rails de um corredor estão disponíveis com /v3/quotes.

Em um payout de stablecoin, o payment rail de cada cotação é uma rede blockchain, como ETHEREUM, e as cotações são retornadas apenas para as redes habilitadas para a sua conta. Não inclua destinationCountry: com ele, nenhum payment rail corresponde, e a requisição falha com SYS_017, ou com USR_024 se você também tiver enviado paymentRail. Se você solicitar uma rede que não esteja habilitada para a sua conta, a requisição falha com SYS_017. Um pagamento criado a partir de uma cotação de stablecoin registra a rede em destination.selectedPaymentRail e não tem valor em destination.destinationBlockchainNetwork.

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

Uma requisição bem-sucedida retorna HTTP 201 com uma coleção de cotações. O quoteCollectionId de nível superior identifica a coleção, e o array quotes contém uma cotação para cada payment rail que a Ripple precificou. O exemplo mostra dois payment rails com tarifas diferentes e, portanto, valores de destino diferentes.

{
  "quoteCollectionId": "11111111-aaaa-2222-bbbb-222222222222",
  "quotes": [
    {
      "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
      "quoteStatus": "ACTIVE",
      "quoteAmountType": "SOURCE_AMOUNT",
      "sourceAmount": 1000.00,
      "destinationAmount": 915.95,
      "sourceCurrency": "USD",
      "destinationCurrency": "EUR",
      "destinationCountry": "DE",
      "payinCategory": "PRE_FUNDING",
      "paymentRail": "SEPA_INSTANT",
      "adjustedExchangeRate": {
        "adjustedRate": 0.9238
      },
      "fees": [
        {
          "totalFee": 8.50,
          "feeCurrency": "USD",
          "feeBreakdown": [
            {
              "calculatedFee": 0.50,
              "feeName": "Fixed service fee",
              "feeDescription": "Fixed service fee for payment rail SEPA_INSTANT.",
              "paymentRail": "SEPA_INSTANT"
            },
            {
              "calculatedFee": 8.00,
              "feeName": "Variable service fee",
              "feeDescription": "Variable service fee for payment rail SEPA_INSTANT.",
              "paymentRail": "SEPA_INSTANT"
            }
          ]
        }
      ],
      "createdAt": "2025-11-02T18:26:00.000Z",
      "expiresAt": "2025-11-02T18:41:00.318Z"
    },
    {
      "quoteId": "9fb4500d-2345-6789-ae9f-e431fb517741",
      "quoteStatus": "ACTIVE",
      "quoteAmountType": "SOURCE_AMOUNT",
      "sourceAmount": 1000.00,
      "destinationAmount": 918.95,
      "sourceCurrency": "USD",
      "destinationCurrency": "EUR",
      "destinationCountry": "DE",
      "payinCategory": "PRE_FUNDING",
      "paymentRail": "SEPA_STANDARD",
      "adjustedExchangeRate": {
        "adjustedRate": 0.9238
      },
      "fees": [
        {
          "totalFee": 5.25,
          "feeCurrency": "USD",
          "feeBreakdown": [
            {
              "calculatedFee": 0.25,
              "feeName": "Fixed service fee",
              "feeDescription": "Fixed service fee for payment rail SEPA_STANDARD.",
              "paymentRail": "SEPA_STANDARD"
            },
            {
              "calculatedFee": 5.00,
              "feeName": "Variable service fee",
              "feeDescription": "Variable service fee for payment rail SEPA_STANDARD.",
              "paymentRail": "SEPA_STANDARD"
            }
          ]
        }
      ],
      "createdAt": "2025-11-02T18:26:00.041Z",
      "expiresAt": "2025-11-02T18:41:00.318Z"
    }
  ]
}

Cada cotação da coleção é para um payment rail e tem a sua própria taxa de câmbio e as suas próprias tarifas. Todas as cotações da coleção expiram ao mesmo tempo. Revise as cotações e escolha a mais adequada ao pagamento. O pagamento registra o payment rail da cotação escolhida em destination.selectedPaymentRail. Quando presente, payoutExecutionDetails.paymentRailUsed informa o rail usado no payout, que pode ser diferente. Para ver a velocidade de entrega de cada payment rail, consulte Referência de payment rails.

Se a Ripple não conseguir precificar um payment rail para a requisição, a coleção não inclui uma cotação para ele. Se nenhum payment rail puder ser precificado, a requisição falha, geralmente com SYS_018, ou com USR_013 quando o valor da cotação não é suficiente para cobrir as tarifas da transação.

As cotações são válidas por tempo limitado (15 minutos por padrão). Antes de criar um pagamento, verifique se o quoteStatus da cotação escolhida é ACTIVE.

• Se quoteStatus for ACTIVE, a cotação pode ser usada para criar um pagamento.
• Se quoteStatus for EXPIRED, a cotação não pode mais ser usada. Solicite uma nova coleção de cotações, que reflete a taxa de câmbio e as tarifas atuais.

Use expiresAt para implementar uma lógica de atualização no cliente, por exemplo, pedindo a confirmação do usuário antes que a cotação expire, ou recotando automaticamente quando o tempo restante ficar abaixo de um limite.

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

Todas as cotações de uma coleção têm o mesmo expiresAt. Recotar gera um novo quoteCollectionId e novos valores de quoteId.

Se você já sabe qual payment rail quer usar, inclua paymentRail na requisição para receber uma coleção com uma única cotação. Isso simplifica o tratamento da resposta quando a sua integração sempre usa o mesmo payment rail.

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

A resposta contém um array quotes com uma cotação, para o payment rail SPEI. Se o corredor não oferecer o payment rail, a requisição falha com USR_024, e a descrição do erro lista os payment rails que /v3/quotes oferece para o corredor. Se o corredor oferecer o payment rail, mas não com /v3/quotes, a requisição falha com USR_026.

Para ver os valores válidos de paymentRail, consulte Referência de payment rails.

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

Use este endpoint para recuperar uma coleção de cotações criada anteriormente, por exemplo em um fluxo assíncrono em que você armazenou o quoteCollectionId e está verificando o status da cotação antes de iniciar um pagamento.

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

O schema da resposta é idêntico ao da resposta do POST. Verifique o quoteStatus da cotação que você quer usar antes de prosseguir, porque ela pode ter expirado desde que foi criada.

GET /v3/quotes/{quote-id}

Use este endpoint para recuperar uma cotação específica por ID.

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

A resposta contém os mesmos campos de uma entrada única do array quotes, sem o invólucro quoteCollectionId.

Os erros de cotação retornam uma resposta estruturada com um status e um array errors. Cada erro inclui code, title, type, description e timestamp.

Os códigos de erro usam três prefixos:

Valores de payinCategory descontinuados (USR_025): /v3/quotes não aceita FUNDED nem T_PLUS_ONE. Use PRE_FUNDING no lugar de FUNDED e CREDIT_FUNDING no lugar de T_PLUS_ONE.

Payment rail não oferecido (USR_024): o corredor não oferece o paymentRail que você enviou. A descrição do erro lista os payment rails que /v3/quotes oferece para o corredor.

Não disponível com /v3/quotes (USR_026): se você enviou paymentRail, tente novamente sem ele, porque um payment rail que não está disponível com /v3/quotes retorna USR_026 mesmo quando outros payment rails do corredor estão disponíveis. Caso contrário, solicite a cotação desse corredor por meio de /v2/quotes, documentado em API do Payments Direct v2026.03.

destinationCountry ausente (USR_017): uma requisição de payout em moeda fiduciária precisa incluir destinationCountry. Uma requisição de payout de stablecoin não pode incluí-lo.

Códigos de moeda ou de país inválidos: sourceCurrency e destinationCurrency precisam ter de 3 a 5 caracteres alfabéticos. sourceCountry e destinationCountry precisam ser códigos ISO 3166-1 alfa-2 (exatamente 2 caracteres).

Para ver todos os códigos de erro, consulte Erros da API.

Depois que você tiver uma cotação ACTIVE e tiver escolhido um quoteId, estará pronto para criar um pagamento.

Consulte Criar um pagamento para ver o passo a passo completo da etapa de criação do pagamento, incluindo como informar o quoteId junto com os IDs da identidade do beneficiário e do instrumento financeiro.