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. Cada cotação fixa uma taxa de câmbio, o detalhamento das tarifas e uma janela de validade, para que você possa revisar as condições 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.
3. Tratar o caso em que a cotação expira.
4. 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_collections:write. 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.
• Um payoutCategory igual a BANK ou CRYPTO.

POST /v2/quotes/quote-collection

Uma requisição de coleção de cotações especifica o corredor, a categoria de payout e o valor que você quer precificar. Uma coleção de cotações normalmente contém uma única cotação.

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"
  }'

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; o array quotes contém a cotação retornada.

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

As cotações são válidas por tempo limitado (15 minutos por padrão). Antes de criar um pagamento, verifique se quoteStatus é 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 refletirá 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

Recotar gera um novo quoteCollectionId e novos valores de quoteId.

GET /v2/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/v2/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 antes de prosseguir; ela pode ter expirado desde que foi criada.

GET /v2/quotes/{quote-id}

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

curl -i -X GET \
  https://api.test.ripple.com/v2/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:

payoutCategory ausente: o endpoint v2 exige payoutCategory. Omiti-lo retorna um erro de validação USR_.

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

Valores de payinCategory obsoletos: FUNDED e T_PLUS_ONE ainda são aceitos no endpoint v2, mas estão obsoletos. Use PRE_FUNDING no lugar de FUNDED e CREDIT_FUNDING no lugar de T_PLUS_ONE. Consulte Métodos de financiamento.

Corredor não compatível: se o par de moedas não estiver configurado para o seu tenant, a API retorna um erro CFG_. Entre em contato com o seu representante Ripple se o erro persistir.

Assim que você tiver uma cotação ACTIVE e tiver selecionado 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.