# Criar um pagamento Corredores compatíveis Para conhecer os corredores de pagamento compatíveis, consulte [Payout network](/pt-br/products/payments-direct-2/introduction/payout-network). Neste tutorial, você percorrerá as etapas necessárias para criar um pagamento usando a API do Payments Direct com o novo **endpoint de pagamentos v3**: 1. Criar uma coleção de cotações para um pagamento proposto. 2. Escolher uma cotação da coleção. 3. Criar um pagamento usando a **operação de pagamentos v3**, incluindo: - `beneficiaryIdentityId` (ID da identidade do pagamento do beneficiário) - `beneficiaryFinancialInstrumentId` (ID do instrumento financeiro / método de pagamento do beneficiário) - (Opcionalmente) `originatorIdentityId` (ID da identidade do pagamento do ordenante, para pagamentos de terceiros) 4. Obter as transições de estado do pagamento para confirmar que ele chegou a `COMPLETED`. Para saber mais sobre identidades do pagamento e instrumentos financeiros, consulte [Identidades do pagamento](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities) e [Instrumentos financeiros](/pt-br/products/payments-direct-2/introduction/concepts/financial-instruments). ## Antes de começar Para seguir este tutorial, você deve ter: - Acesso ao ambiente UAT da API do Payments Direct. - Um **token de acesso** OAuth2 válido com escopos para cotações e pagamentos. - Ao menos uma **identidade de ordenante** (e, opcionalmente, uma identidade para fluxos de ordenante de terceiros). - Ao menos uma **identidade de beneficiário** e um ou mais **instrumentos financeiros** para esse beneficiário. ## Etapa 1: Criar uma coleção de cotações Primeiro, solicite uma **coleção de cotações** que descreva quanto o seu beneficiário receberá, a taxa de câmbio, as tarifas e quando a cotação expira. Neste exemplo, um remetente está enviando **10.000 USD** a um beneficiário no **México**, que receberá **MXN** em uma conta bancária. ### Endpoint `POST /v3/quotes/quote-collection` ### Parâmetros do corpo da requisição No mínimo, forneça: - `quoteAmount` – O valor que você deseja cotar. - `quoteAmountType` – Se quoteAmount é um valor de origem ou de destino (por exemplo, SOURCE_AMOUNT). - `sourceCurrency` / `destinationCurrency` – As moedas de envio e de recebimento. - `destinationCountry` – O país do beneficiário (código ISO 3166-1 alfa-2), obrigatório para um payout em moeda fiduciária. `sourceCountry`, o país do ordenante, é opcional. - `paymentRail` – Opcional. Solicita uma cotação para apenas um payment rail. Omita o campo para receber 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). - `payinCategory` – Como você financia o pagamento (`PRE_FUNDING`, `CREDIT_FUNDING` ou `JIT_FUNDING`). Para mais detalhes, consulte [Modelo de financiamento](/pt-br/products/payments-direct-2/introduction/concepts/quotes#modelo-de-financiamento-payincategory). ### Exemplo de requisição ```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" }' ``` ### Exemplo de resposta (truncado) ```json { "quoteCollectionId": "11111111-aaaa-2222-bbbb-222222222222", "quotes": [ { "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630", "quoteStatus": "ACTIVE", "quoteAmountType": "SOURCE_AMOUNT", "sourceAmount": 10000, "destinationAmount": 204533.30, "sourceCurrency": "USD", "destinationCurrency": "MXN", "destinationCountry": "MX", "payinCategory": "PRE_FUNDING", "paymentRail": "SPEI", "adjustedExchangeRate": { "adjustedRate": 20.4136 }, "fees": [ { "totalFee": 14, "feeCurrency": "USD" } ], "createdAt": "2025-11-13T22:44:34.711Z", "expiresAt": "2025-11-13T22:59:34.767Z" } ] } ``` O que verificar - `quoteStatus` deve ser ACTIVE. - Anote o `quoteId` que você deseja usar; você o passará para a operação Criar pagamento. ## Etapa 2: Escolher uma cotação Uma coleção de cotações contém uma cotação para cada payment rail disponível para o corredor, e cada cotação indica o seu payment rail. O México oferece um único rail, `SPEI`, portanto esta coleção contém uma única cotação. Em um corredor com vários rails, a lógica da sua aplicação deve: 1. Iterar por `quotes[]` na resposta. 2. Aplicar os seus critérios (por exemplo, o payment rail, as tarifas ou a taxa de câmbio). 3. Selecionar um único `quoteId` para a etapa Criar pagamento. O payment rail indicado na cotação que você escolher é o rail que o pagamento usa. Para o restante deste tutorial, vamos supor que você selecione: `quoteId = 7ea3399c-1234-5678-8d8f-d320ea406630` ## Etapa 3: Criar um pagamento com a operação de pagamentos v3 Depois de selecionar uma cotação, você pode criar um pagamento usando a operação de pagamentos v3. É aqui que você conecta: - A cotação (`quoteId`) - A identidade do beneficiário (`beneficiaryIdentityId`) - O instrumento financeiro do beneficiário (`beneficiaryFinancialInstrumentId`) - **(Opcionalmente)** a identidade do ordenante (`originatorIdentityId`), caso você esteja enviando em nome de um cliente O `beneficiaryFinancialInstrumentId` identifica a conta que recebe os fundos. Cada identidade tem um instrumento financeiro ativo, portanto este é o instrumento atualmente vinculado à identidade do beneficiário. ### Rótulos de pagamento `paymentLabels` são strings simples que você pode usar para categorizar e pesquisar pagamentos. Um padrão comum é armazenar pares chave=valor. Por exemplo: ```json "paymentLabels": [ "customerSegment=PREMIUM", "invoiceNumber=INV-2025-0615" ] ``` Esses rótulos podem ser atualizados posteriormente por meio da operação **Update payment labels**. ### Endpoint `POST /v3/payments` ### Campos obrigatórios e opcionais Campos obrigatórios principais na requisição de pagamento v3: - `quoteId` – O quoteId da cotação que você selecionou. - `beneficiaryIdentityId` – O token de identidade do beneficiário. - `beneficiaryFinancialInstrumentId` – O token do instrumento financeiro da conta de pagamento do beneficiário. **Opcionais, mas comumente usados:** - `originatorIdentityId` – Inclua para pagamentos de terceiros em que você envia em nome de uma empresa ou instituição. Omita (ou use a sua própria identidade) quando você for o ordenante. - `receiverRelationship` – Relação entre o ordenante e o beneficiário (por exemplo, FAMILY, SUPPLIER). - `paymentMemo` – Memo de texto livre usado para conciliação; não é armazenado na PII. - `paymentLabels` – Rótulos de string definidos pela aplicação para agrupar e categorizar pagamentos (por exemplo, `customerSegment=PREMIUM`). Os rótulos são armazenados como strings simples; uma convenção comum é usar pares `chave=valor`. - Outros campos opcionais, como `internalId`, `purposeCode` e `sourceOfCash`, podem estar disponíveis dependendo da sua configuração. Transações diretas vs. pagamentos de terceiros - **Transação direta:** Você é o ordenante; o `originatorIdentityId` é omitido ou definido como a sua própria identidade. - **Terceiros:** Você envia em nome de um cliente; o `originatorIdentityId` deve ser definido como o token de identidade desse cliente. ### Exemplos de requisição Vamos mostrar lado a lado os exemplos de transação direta e de terceiros. Transação direta Neste exemplo, você é o ordenante. Você omite o `originatorIdentityId` (ou usa a sua própria identidade). ```bash curl -i -X POST \ https://api.test.ripple.com/v3/payments \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630", "beneficiaryIdentityId": "99254c4f-f207-4792-a846-06928825018c", "beneficiaryFinancialInstrumentId": "0e0d7b5a-7f2b-4c75-9bb9-8c4d0ff5f2a1", "receiverRelationship": "SUPPLIER", "paymentMemo": "INVOICE 2025-0615", "paymentLabels": [ "customerSegment=PREMIUM", "invoiceNumber=INV-2025-0615" ] }' ``` Pagamento de terceiros Neste exemplo, você está enviando em nome de um cliente corporativo. Você deve incluir o `originatorIdentityId`. ```bash curl -i -X POST \ https://api.test.ripple.com/v3/payments \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630", "originatorIdentityId": "c1e92b47-4579-4a7e-9c9a-02f3e3e4bb11", "beneficiaryIdentityId": "99254c4f-f207-4792-a846-06928825018c", "beneficiaryFinancialInstrumentId": "0e0d7b5a-7f2b-4c75-9bb9-8c4d0ff5f2a1", "receiverRelationship": "SUPPLIER", "paymentMemo": "INVOICE 2025-0615", "paymentLabels": [ "customerSegment=PREMIUM", "invoiceNumber=INV-2025-0615" ] }' ``` ### Exemplo de resposta Em caso de sucesso, a API retorna uma resposta 201 com detalhes do pagamento e um `paymentId` que você pode usar para monitorá-lo. O `paymentId` tem o mesmo valor do `quoteId` que você aceitou, porque um pagamento é identificado pela sua cotação. ```json { "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630", "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630", "paymentState": "INITIATED", "receiverRelationship": "SUPPLIER", "paymentMemo": "INVOICE 2025-0615", "paymentLabels": [ "customerSegment=PREMIUM", "invoiceNumber=INV-2025-0615" ], "originator": { "originatorIdentityId": "c1e92b47-4579-4a7e-9c9a-02f3e3e4bb11", "sourceCurrency": "USD", "sourceAmount": "10000.00", "sourceCountry": "US" }, "destination": { "beneficiaryIdentityId": "99254c4f-f207-4792-a846-06928825018c", "beneficiaryFinancialInstrumentId": "0e0d7b5a-7f2b-4c75-9bb9-8c4d0ff5f2a1", "destinationCurrency": "MXN", "destinationAmount": "204533.30", "destinationCountry": "MX" }, "fees": { "totalFeesAmount": "14.00", "totalFeesCurrency": "USD" }, "createdAt": "2025-03-15T10:23:45Z", "initiatedAt": "2025-03-15T10:23:45Z", "expiresAt": "2025-03-15T10:28:45Z" } ``` O valor-chave a capturar é: `paymentId = 7ea3399c-1234-5678-8d8f-d320ea406630` Você o usará nas etapas posteriores. Pagamentos financiados via JIT Se você usou `payinCategory: JIT_FUNDING` na sua cotação, o pagamento estará inicialmente no estado `AWAITING_FUNDING` em vez de `INITIATED`. A resposta incluirá um timestamp `jitFundingExpiresAt`. Você deve transferir os recursos necessários para a sua conta no ledger da Ripple antes desse horário para que o pagamento prossiga. Se o prazo passar sem o financiamento, o pagamento expira e você deve criar uma nova cotação e um novo pagamento. ## Etapa 4: Obter um pagamento por ID (opcional, mas recomendado) Para verificar o status atual de um pagamento ou recuperar os seus detalhes, chame a operação **Get payment by ID**. ### Endpoint `GET /v3/payments/{paymentId}` ### Exemplo de requisição ```bash curl -i -X GET \ https://api.test.ripple.com/v3/payments/7ea3399c-1234-5678-8d8f-d320ea406630 \ -H "Authorization: Bearer " ``` ### Exemplo de resposta (truncado) ```json { "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630", "initiatedAt": "2025-03-15T10:23:45Z", "expiresAt": "2025-03-15T10:28:45Z", "lastStateUpdatedAt": "2025-03-15T10:24:15Z", "paymentState": "TRANSFERRING", "originator": { "originatorIdentityId": "c1e92b47-4579-4a7e-9c9a-02f3e3e4bb11", "sourceCountry": "US", "sourceCurrency": "USD", "sourceAmount": 10000, "payin": "PRE_FUNDING" }, "destination": { "destinationAmount": 204533.30, "destinationCountry": "MX", "destinationCurrency": "MXN", "beneficiaryIdentityId": "99254c4f-f207-4792-a846-06928825018c", "beneficiaryFinancialInstrumentId": "0e0d7b5a-7f2b-4c75-9bb9-8c4d0ff5f2a1", "selectedPaymentRail": "SPEI" } } ``` Você pode usar este endpoint para: - Inspecionar o `paymentState` para ver em que ponto do ciclo de vida o pagamento está. - Persistir a resposta para as suas próprias auditorias ou painéis internos. ## Etapa 5: Obter as transições de estado para confirmar a conclusão Para ver como um pagamento se moveu pelo seu ciclo de vida, especialmente para confirmar que ele chegou a `COMPLETED`, use a operação **Get state transitions**. Endpoint `GET /v3/payments/{paymentId}/states` ### Exemplo de requisição ```bash curl -i -X GET \ https://api.test.ripple.com/v3/payments/7ea3399c-1234-5678-8d8f-d320ea406630/states \ -H "Authorization: Bearer " ``` ### Exemplo de resposta ```json { "stateTransitions": [ { "updatedFrom": "QUOTED", "updatedTo": "INITIATED", "updatedAt": "2025-03-15T10:23:45Z" }, { "updatedFrom": "INITIATED", "updatedTo": "VALIDATING", "updatedAt": "2025-03-15T10:23:47Z" }, { "updatedFrom": "VALIDATING", "updatedTo": "TRANSFERRING", "updatedAt": "2025-03-15T10:23:55Z" }, { "updatedFrom": "TRANSFERRING", "updatedTo": "COMPLETED", "updatedAt": "2025-03-15T10:25:12Z" } ] } ``` A sua aplicação pode: - Consultar este endpoint por polling até que o estado mais recente seja COMPLETED, ou - Usar um mecanismo de eventos/webhook, se disponível no seu ambiente. Interpretando as transições de estado - Cada objeto em `stateTransitions[]` registra uma mudança em `paymentState`. - Considere o pagamento concluído com sucesso quando o valor updatedTo da última transição for `COMPLETED`. - Outros estados terminais podem incluir `FAILED` ou `RETURNED`, dependendo do comportamento do corredor e da rede de pagamento. - Se o pagamento for rejeitado ou devolvido, você verá estados terminais como `DECLINED` ou `RETURNED` em vez de `COMPLETED`. ## Tratamento de erros Os erros comuns neste fluxo de trabalho incluem: - **400 Bad Request** – corpo da requisição malformado, campos obrigatórios faltando ou combinações inválidas (por exemplo, moeda/trilho incompatíveis). - **404 Not Found** – coleção de cotações, cotação ou ID de pagamento inexistente. - **409 Conflict** – mudanças conflitantes ou restrições de negócio (por exemplo, uso de uma identidade ou instrumento inativo). - **422 Unprocessable Entity** – o pagamento não pode prosseguir devido a falhas de validação específicas do corredor. - **500 Internal Server Error** – problemas inesperados no servidor; tente novamente ou entre em contato com o suporte se persistir. Os erros relacionados a pagamentos são retornados em um schema de erro padrão que inclui: - **code** – código de erro legível por máquina - **title** – resumo curto legível por humanos - **description** – explicação mais detalhada e dicas de correção Consulte a seção [Erros da API](/pt-br/products/payments-direct-2/api-docs/error-handling/api-errors) da documentação da API do Payments Direct para obter uma lista completa de códigos de erro. ## Resumo e próximos passos Neste tutorial, você: 1. Criou uma coleção de cotações para precificar um pagamento internacional. 2. Selecionou uma cotação e usou o seu `quoteId` para criar um pagamento com a operação v3, incluindo: - `beneficiaryIdentityId` - `beneficiaryFinancialInstrumentId` - O `originatorIdentityId` opcional para pagamentos de terceiros 1. Recuperou o pagamento e, em seguida, as suas transições de estado para confirmar que ele chegou a `COMPLETED`. **Em seguida, você pode:** - Para saber como criar e gerenciar as identidades referenciadas por `originatorIdentityId` e `beneficiaryIdentityId`, consulte [Criar e gerenciar identidades](/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-identities). - Para saber como criar, atualizar e desativar as contas bancárias referenciadas por `beneficiaryFinancialInstrumentId`, consulte [Criar e gerenciar instrumentos financeiros](/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-financial-instruments).