# 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](/pt-br/products/payments-direct-2/introduction/concepts/quotes). ## Antes de começar 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](/pt-br/products/payments-direct-2/api-docs/developer-guides/request-an-access-token). - 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](/pt-br/products/payments-direct-2/introduction/concepts/funding-methods). - 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](/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-identities). ## Etapa 1: Criar uma coleção de cotações `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`. ### Parâmetros da requisição | Parâmetro | Obrigatório | Descrição | | --- | --- | --- | | `quoteAmount` | Sim | O valor a cotar. | | `quoteAmountType` | Sim | Se `quoteAmount` é o valor enviado (`SOURCE_AMOUNT`) ou o valor recebido (`DESTINATION_AMOUNT`). | | `sourceCurrency` | Sim | A moeda que você está enviando (ISO 4217, de 3 a 5 caracteres). | | `destinationCurrency` | Sim | A moeda que o beneficiário recebe (ISO 4217, de 3 a 5 caracteres). Em um payout de stablecoin, a stablecoin. | | `payinCategory` | Sim | O seu modelo de financiamento: `PRE_FUNDING`, `CREDIT_FUNDING` ou `JIT_FUNDING`. | | `destinationCountry` | Para um payout em moeda fiduciária | O país do beneficiário (ISO 3166-1 alfa-2). Omiti-lo em uma requisição de payout em moeda fiduciária retorna `USR_017`. Omita-o em um payout de stablecoin. | | `sourceCountry` | Não | O país do remetente (ISO 3166-1 alfa-2). | | `paymentRail` | Não | Solicita uma cotação para apenas este payment rail. Quando omitido, a coleção contém uma cotação para cada payment rail disponível para o corredor. Consulte [Referência de payment rails](/pt-br/products/payments-direct-2/api-docs/integration-resources/payment-rail-reference). | 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`. Cotação por valor de origem Use `SOURCE_AMOUNT` quando você controla quanto quer enviar. A API calcula quanto o beneficiário recebe depois de aplicar a taxa de câmbio e as tarifas. Neste exemplo, o remetente quer enviar **1.000 USD** a um beneficiário na Alemanha que recebe em EUR. ```bash curl -i -X POST \ https://api.test.ripple.com/v3/quotes/quote-collection \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "quoteAmount": 1000.00, "quoteAmountType": "SOURCE_AMOUNT", "sourceCurrency": "USD", "destinationCurrency": "EUR", "sourceCountry": "US", "destinationCountry": "DE", "payinCategory": "PRE_FUNDING" }' ``` Cotação por valor de destino Use `DESTINATION_AMOUNT` quando o beneficiário precisa receber um valor exato, por exemplo ao pagar uma fatura em moeda estrangeira. A API calcula o valor que você envia para cobrir o câmbio e as tarifas. Neste exemplo, o beneficiário precisa receber exatamente **20.000 MXN**. ```bash curl -i -X POST \ https://api.test.ripple.com/v3/quotes/quote-collection \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "quoteAmount": 20000.00, "quoteAmountType": "DESTINATION_AMOUNT", "sourceCurrency": "USD", "destinationCurrency": "MXN", "sourceCountry": "US", "destinationCountry": "MX", "payinCategory": "PRE_FUNDING" }' ``` ## Etapa 2: Revisar a resposta e escolher uma cotação 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. ```json { "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" } ] } ``` ### Campos principais | Campo | Descrição | | --- | --- | | `quoteCollectionId` | O ID desta coleção. Use-o para recuperar a coleção mais tarde com `GET /v3/quotes/quote-collection/{quote-collection-id}`. | | `quoteId` | O ID de uma cotação individual. Use o `quoteId` da cotação que você escolher para criar um pagamento. | | `quoteStatus` | `ACTIVE` significa que a cotação pode ser usada. `EXPIRED` significa que a janela de validade passou e é necessária uma nova coleção de cotações. | | `paymentRail` | O payment rail desta cotação, por exemplo `SEPA_INSTANT` ou `SPEI`. Cada cotação da coleção é para um payment rail diferente. | | `adjustedExchangeRate.adjustedRate` | A taxa de câmbio que a Ripple aplica ao pagamento. A taxa fica fixada durante a janela de validade da cotação. | | `fees[].totalFee` / `feeBreakdown` | Tarifa total de serviço e os itens de detalhamento. Um item de detalhamento pode incluir o `paymentRail` ao qual se aplica. | | `taxes` | Tributos sobre consumo aplicáveis às tarifas da Ripple, como VAT ou GST. Ausente quando não há tributos aplicáveis. | | `createdAt` / `expiresAt` | A janela de validade da cotação. Por padrão, as cotações são válidas por 15 minutos. | ### Escolher uma cotação 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](/pt-br/products/payments-direct-2/api-docs/integration-resources/payment-rail-reference). 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. quoteId e paymentId O `quoteId` que você escolher se torna o `paymentId` quando você cria o pagamento. Armazene-o antes de passar para a próxima etapa. ## Etapa 3: Tratar quando a cotação expira 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`. ## Etapa 4: Solicitar uma cotação para apenas um payment rail 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. ```bash curl -i -X POST \ https://api.test.ripple.com/v3/quotes/quote-collection \ -H "Authorization: Bearer " \ -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](/pt-br/products/payments-direct-2/api-docs/integration-resources/payment-rail-reference). ## Etapa 5: Recuperar uma coleção de cotações `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. ```bash curl -i -X GET \ https://api.test.ripple.com/v3/quotes/quote-collection/11111111-aaaa-2222-bbbb-222222222222 \ -H "Authorization: Bearer " ``` 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. ## Etapa 6: Recuperar uma cotação individual `GET /v3/quotes/{quote-id}` Use este endpoint para recuperar uma cotação específica por ID. ```bash curl -i -X GET \ https://api.test.ripple.com/v3/quotes/7ea3399c-1234-5678-8d8f-d320ea406630 \ -H "Authorization: Bearer " ``` A resposta contém os mesmos campos de uma entrada única do array `quotes`, sem o invólucro `quoteCollectionId`. ## Tratamento de erros 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: | Prefixo | Categoria | Causas comuns | | --- | --- | --- | | `USR_` | Erro de validação | Campos obrigatórios ausentes, códigos de moeda ou de país inválidos, um valor fora da faixa permitida, um `paymentRail` que não está disponível para o corredor, os valores descontinuados de `payinCategory` ou um corredor que não está disponível com `/v3/quotes`. | | `CFG_` | Erro de configuração | Configuração ausente ou incompleta para a sua conta. Entre em contato com o seu representante Ripple se o erro persistir. | | `SYS_` | Erro de sistema | Uma falha interna ou upstream. Isso inclui `SYS_018`, quando nenhum payment rail pôde ser precificado, e `SYS_017`, quando `/v3/quotes` não encontra nenhum payment rail para a requisição: o corredor não está disponível com `/v3/quotes` ou, em um payout de stablecoin, nenhuma rede solicitada está habilitada para a sua conta. Tentar novamente não altera um resultado `SYS_017`; para um corredor de moeda fiduciária, solicite a cotação por meio de `/v2/quotes`, documentado em [API do Payments Direct v2026.03](/products/payments-direct-2/v2026.03/api-docs/developer-guides/fetch-a-quote-collection). Para outros erros de sistema, envie a requisição novamente e entre em contato com o suporte se o erro persistir. | ### Erros de validação comuns **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](/products/payments-direct-2/v2026.03/api-docs/developer-guides/fetch-a-quote-collection). **`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](/pt-br/products/payments-direct-2/api-docs/error-handling/api-errors). ## Próximos passos Depois que você tiver uma cotação `ACTIVE` e tiver escolhido um `quoteId`, estará pronto para criar um pagamento. Consulte [Criar um pagamento](/pt-br/products/payments-direct-2/api-docs/developer-guides/create-a-payment) 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.