# Criar um pagamento Identity Management v3 Este tópico descreve o modelo de identidade v3. O **Identity Management v3** é recomendado para todas as novas integrações. Para conhecer os corredores de pagamento compatíveis, consulte [Payout network](/pt-br/products/payments-direct-2/introduction/payout-network). Para detalhes ou dúvidas sobre migração, entre em contato com o seu representante Ripple. 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). Clientes que usam identidades legadas v2 Este tutorial pressupõe o modelo recomendado do **Identity Management v3** (identidades separadas para ordenantes e beneficiários). ## 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. Para clientes que usam identidades legadas v2 Se você ainda estiver usando identidades legadas v2, certifique-se de saber o `identityId` v2 do beneficiário. Você usará esse ID diretamente na requisição de pagamento e omitirá o ID do instrumento financeiro. ## 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 /v2/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. - `sourceCountry` / `destinationCountry` – Os países do ordenante e do beneficiário (códigos ISO 3166-1 alfa-2). - `payoutCategory` – Como o beneficiário recebe os recursos (por exemplo, BANK). - `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/v2/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", "payoutCategory": "BANK", "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", "sourceCountry": "US", "destinationCountry": "MX", "payoutCategory": "BANK", "payinCategory": "PRE_FUNDING", "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 Se a resposta contiver várias cotações (por exemplo, rotas ou opções de câmbio diferentes), a lógica da sua aplicação deve: 1. Iterar por `quotes[]` na resposta. 2. Aplicar os seus critérios (melhor taxa de câmbio, menor tarifa, configuração de pagamento preferida). 3. Selecionar um único `quoteId` para a etapa Criar pagamento. 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 esse é 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 key=value. 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 `key=value`. - 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": "7ea3399c-1234-5678-8d8f-d320ea406630", "beneficiaryFinancialInstrumentId": "0e0d7b5a-7f2b-4c75-9bb9-8c4d0ff5f2a1", "receiverRelationship": "SUPPLIER", "paymentMemo": "INVOICE 2025-0615", "paymentLabels": [ "customerSegment=PREMIUM", "invoiceNumber=INV-2025-0615" ] }' ``` Para clientes que usam identidades legadas v2 Se o seu tenant ainda estiver usando identidades v2 (em que os dados de identidade e de instrumento financeiro são armazenados juntos): - Defina apenas o `beneficiaryIdentityId` como o seu ID de identidade v2 existente. - Não defina o `beneficiaryFinancialInstrumentId` (deixe-o em branco ou omita o campo). - O serviço de Pagamentos usará os dados financeiros embutidos na identidade v2 para roteamento e pagamento. **Exemplo:** ```json "beneficiary": { "beneficiaryIdentityId": "id-v2-identity-uuid" // beneficiaryFinancialInstrumentId omitido para compatibilidade com PII v2 } ``` Todos os outros campos da requisição de pagamento (cotação, valores, finalidade, memo etc.) permanecem os mesmos mostrados neste tutorial. 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": "7ea3399c-1234-5678-8d8f-d320ea406630", "beneficiaryFinancialInstrumentId": "0e0d7b5a-7f2b-4c75-9bb9-8c4d0ff5f2a1", "receiverRelationship": "SUPPLIER", "paymentMemo": "INVOICE 2025-0615", "paymentLabels": [ "customerSegment=PREMIUM", "invoiceNumber=INV-2025-0615" ] }' ``` Para clientes que usam identidades legadas v2 Se o seu tenant ainda estiver usando identidades v2 (em que os dados de identidade e de instrumento financeiro são armazenados juntos): - Defina apenas o `beneficiaryIdentityId` como o seu ID de identidade v2 existente. - Não defina o `beneficiaryFinancialInstrumentId` (deixe-o em branco ou omita o campo). - O serviço de Pagamentos usará os dados financeiros embutidos na identidade v2 para roteamento e pagamento. **Exemplo:** ```json "beneficiary": { "beneficiaryIdentityId": "id-v2-identity-uuid" // beneficiaryFinancialInstrumentId omitido para compatibilidade com PII v2 } ``` Todos os outros campos da requisição de pagamento (cotação, valores, finalidade, memo etc.) permanecem os mesmos mostrados neste tutorial. ### Exemplo de resposta Em caso de sucesso, a API retorna uma resposta 201 com detalhes sobre o pagamento e um `paymentId` que você pode usar para monitorá-lo. ```json { "paymentId": "aa74f2f4-5996-4f0c-9d8a-7a5e1d51c502", "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": "7ea3399c-1234-5678-8d8f-d320ea406630", "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 = aa74f2f4-5996-4f0c-9d8a-7a5e1d51c502` 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/aa74f2f4-5996-4f0c-9d8a-7a5e1d51c502 \ -H "Authorization: Bearer " ``` ### Exemplo de resposta (truncado) ```json { "paymentId": "aa74f2f4-5996-4f0c-9d8a-7a5e1d51c502", "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": "7ea3399c-1234-5678-8d8f-d320ea406630", "beneficiaryFinancialInstrumentId": "0e0d7b5a-7f2b-4c75-9bb9-8c4d0ff5f2a1", "payout": "BANK" } } ``` 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/aa74f2f4-5996-4f0c-9d8a-7a5e1d51c502/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 do payout network. - 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/payment rail 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 [Tratamento de erros](/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).