Cotações

As cotações permitem visualizar o custo total e o resultado de um pagamento proposto antes de iniciá-lo. Uma cotação reflete a taxa de câmbio, as tarifas e o valor a ser entregue entre uma moeda de origem e uma de destino, e tem prazo limitado (as cotações expiram após um período definido). As cotações são centrais no fluxo de pagamento do Payments Direct e devem ser criadas antes de você chamar o endpoint de pagamentos.

Uma cotação retorna as informações principais de que você precisa para decidir se prossegue com um pagamento, incluindo:

• Valores de origem e de destino (sourceAmount, destinationAmount), conforme você solicite a cotação pelo valor de origem ou pelo valor de destino. Os valores são arredondados para o número de casas decimais definido pela norma ISO 4217 para a moeda em questão (por exemplo, 2 para USD/EUR, 0 para JPY/KRW, 3 para BHD/KWD), com arredondamento HALF_UP.
• Taxa de câmbio ajustada (adjustedExchangeRate), que reflete a taxa usada na conversão.
• Tarifas (fees), com o total e itens de detalhamento opcionais.
• Tributos (taxes), quando aplicáveis (os tributos incidem sobre as tarifas de serviço da Ripple, não sobre o principal).
• Timestamps e validade (createdAt, expiresAt) e um status (ACTIVE ou EXPIRED).

Um fluxo típico é:

1. Criar uma coleção de cotações para um pagamento proposto (normalmente retorna uma única cotação).
2. Selecionar uma cotação (use o quoteId retornado).
3. Criar o pagamento usando as informações da cotação.

A API usa a terminologia "quote collection", mas hoje, no Payments Direct, uma coleção de cotações normalmente contém uma única cotação. A coleção existe para permitir a recuperação e a rastreabilidade do evento de cotação e para viabilizar uma expansão futura a várias opções de cotação.

As cotações têm prazo limitado:

• quoteStatus=ACTIVE significa que a cotação pode ser usada para criar um pagamento.
• quoteStatus=EXPIRED significa que a cotação não é mais válida e precisa ser gerada novamente.
• Use expiresAt para implementar uma lógica no cliente (por exemplo, atualizar a cotação se estiver perto de a cotação expirar).

Nas jurisdições em que a Ripple precisa cumprir normas de tributos sobre consumo (VAT/GST etc.), as respostas de cotação podem incluir tributos aplicados às tarifas de serviço da Ripple (componentes fixos e variáveis), e não ao valor principal do pagamento.

Aspectos principais:

• O cálculo dos tributos dá transparência de custo antecipada.
• Os tributos são calculados sobre a parcela das tarifas, não sobre o valor transferido.
• Se não houver tributos aplicáveis (ou se o tributo calculado for zero), a API não inclui o objeto taxes na resposta.

Use estes endpoints para criar e recuperar cotações:

• POST /v2/quotes/quote-collection — cria uma coleção de cotações para um pagamento proposto.
• GET /v2/quotes/quote-collection/{quote-collection-id} — recupera uma coleção de cotações criada anteriormente.
• GET /v2/quotes/{quote-id} — recupera uma cotação específica por ID.

Para um guia passo a passo sobre como solicitar e usar cotações, consulte Obter uma coleção de cotações.

O campo payinCategory especifica como você financia o pagamento. Os seguintes valores são aceitos:

Quando você usa JIT_FUNDING, o pagamento entra no estado AWAITING_FUNDING depois de criado. Você precisa transferir os recursos necessários para a sua conta de ledger da Ripple antes do timestamp jitFundingExpiresAt do objeto de pagamento. Se o financiamento não for recebido a tempo, o pagamento expira e você precisa criar uma nova cotação e um novo pagamento.

Para mais informações sobre os estados do pagamento, incluindo AWAITING_FUNDING, consulte Ciclo de vida do pagamento.

Para criar uma coleção de cotações, informe:

• quoteAmount e quoteAmountType (SOURCE_AMOUNT ou DESTINATION_AMOUNT)
• sourceCurrency, destinationCurrency
• sourceCountry, destinationCountry
• payinCategory (por exemplo, PRE_FUNDING, CREDIT_FUNDING, JIT_FUNDING)
• payoutCategory (por exemplo, BANK, CRYPTO)
• Opcional: destinationBlockchainNetwork ao cotar pagamentos em criptomoedas.

Os erros do Quote Service são padronizados em categorias como:

• AUTH_xxx erros de autorização (token ausente ou inválido)
• USR_xxx erros de validação (campos da requisição ausentes ou inválidos)
• SYS_xxx falhas internas ou upstream

Os erros retornam um objeto estruturado com status e um array errors[] (code, title, type, description, timestamp).

• Use SOURCE_AMOUNT quando o remetente sabe quanto quer enviar.
• Use DESTINATION_AMOUNT quando o remetente precisa que o beneficiário receba um valor exato.

Requisição

curl -i -X POST \
  http://127.0.0.1:4000/_mock/products/payments-direct-2/@v2026.03/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": "PRE_FUNDING",
    "destinationBlockchainNetwork": "Ethereum"
  }'

Resposta (trecho)

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