{"templateId":"markdown","versions":[{"version":"v2026.04","label":"v2026.04","link":"/pt-br/products/payments-direct-2/introduction/concepts/payment-lifecycle","default":true,"active":true,"folderId":"7e5507fe"},{"version":"v2026.03","label":"v2026.03","link":"/pt-br/products/payments-direct-2/v2026.03/introduction/concepts/payment-lifecycle","default":false,"active":false,"folderId":"7e5507fe"},{"version":"v2025.11","label":"v2025.11","link":"/pt-br/products/payments-direct-2/v2025.11/introduction/concepts/payment-lifecycle","default":false,"active":false,"folderId":"7e5507fe"}],"sharedDataIds":{"sidebar":"sidebar-@l10n/pt-BR/products/payments-direct-2/@v2025.11/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Ciclo de vida do pagamento","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"ciclo-de-vida-do-pagamento","__idx":0},"children":["Ciclo de vida do pagamento"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Esta página descreve o ciclo de vida de um pagamento no ","Payments Direct",", detalha cada estado do pagamento e explica como descobrir o estado atual de um pagamento."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Um pagamento normalmente passa pelas seguintes fases no ","Payments Direct",":"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Iniciado"]},": o processo de pagamento começa quando você envia uma requisição de pagamento que referencia uma cotação aceita. ","Payments Direct"," cria um pagamento no estado ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INITIATED"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Validando"]},": o estado do pagamento muda para ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VALIDATING"]}," enquanto a plataforma executa verificações internas, como validar os dados do pagamento, conferir limites e reservar recursos do seu saldo disponível."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Se essas verificações forem bem-sucedidas, o pagamento segue para ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSFERRING"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Se for encontrado um problema previsível e corrigível pelo usuário (por exemplo, dados inválidos ou ausentes, status da conta ou regras de compliance), o pagamento passa para o estado terminal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Se um problema inesperado da plataforma ou do sistema impedir o processamento, o pagamento passa para o estado terminal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},"."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transferindo"]},": à medida que o pagamento percorre a rede até o beneficiário, o estado dele passa a ser ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSFERRING"]},". O valor do pagamento é debitado do seu saldo disponível, e a Ripple ou um parceiro downstream trabalha para concluir o pagamento."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Se um problema previsível e corrigível pelo usuário for descoberto nesta etapa (por exemplo, o banco de destino rejeita o pagamento por regras de compliance ou pelo status da conta), o pagamento passa para o estado terminal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Se ocorrer um erro inesperado da plataforma ou do sistema, o pagamento passa para o estado terminal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},"."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Concluído"]},": se o pagamento não entrar em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}," nem em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," nas fases anteriores e o payout network creditar o beneficiário com sucesso, o pagamento chega ao estado terminal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},". Na maioria dos casos, isso significa que o beneficiário recebeu os recursos."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Devolvido"]},": em alguns casos, um pagamento que já havia chegado a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]}," pode ser devolvido depois por uma instituição downstream ou pelo banco do beneficiário. Quando isso acontece, o pagamento passa para o estado terminal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]}," e os recursos voltam ao ordenante. As devoluções são geridas pela Ripple e pelos parceiros pagadores; os clientes não podem acioná-las diretamente."]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Financiamento JIT"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Nos pagamentos que usam JIT funding, o ciclo de vida começa com um estado adicional antes de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INITIATED"]},". Depois de criado, o pagamento entra em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AWAITING_FUNDING"]}," enquanto a Ripple aguarda o recebimento dos recursos necessários. Assim que os recursos chegam, o pagamento passa para ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INITIATED"]}," e segue o ciclo de vida padrão acima. Se o financiamento não for recebido antes do prazo, o pagamento expira. Para mais informações, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/funding-methods"},"children":["Métodos de financiamento"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O diagrama abaixo mostra uma visão simplificada de como um pagamento pode transitar entre os estados:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/payment-states-rpd2.493bce414aede6caafbe17b40885e69c9de9b632bf27aefa9a252ea8f4943486.5b618451.svg","alt":"Estados do pagamento"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A seção ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#estados-do-pagamento"},"children":["Estados do pagamento"]}," desta página traz descrições de referência de cada estado. Para mais detalhes sobre como funcionam as devoluções e como conciliá-las, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-returns"},"children":["Devoluções de pagamento"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"estados-do-pagamento","__idx":1},"children":["Estados do pagamento"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentState"]}," do objeto de pagamento indica o estado atual de um pagamento. Esta seção descreve cada valor possível e o que ele significa para o seu pagamento, incluindo o novo estado ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payments Direct"," oferece os seguintes estados de pagamento:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"20%","data-label":"Estado"},"children":["Estado  "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Descrição"},"children":["Descrição"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["QUOTED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Uma cotação foi criada, mas você ainda não a aceitou. A cotação descreve a taxa de câmbio proposta, as tarifas e os valores de um possível pagamento. Quando você aceita a cotação e cria um pagamento, a primeira transição de estado do pagamento é de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["QUOTED"]}," para ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INITIATED"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AWAITING_FUNDING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["O pagamento está aguardando o recebimento dos recursos para poder prosseguir. Este estado se aplica apenas a pagamentos que usam JIT funding. Assim que os recursos necessários chegam, o pagamento passa para ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INITIATED"]}," e segue o ciclo de vida padrão. Se os recursos não forem recebidos antes do prazo de financiamento, o pagamento expira."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INITIATED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Você, o ordenante do pagamento, iniciou um pagamento enviando uma requisição que referencia uma cotação aceita. ","Payments Direct"," cria um registro de pagamento com um identificador único e define ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentState"]}," como ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INITIATED"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VALIDATING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Ripple valida os dados do pagamento e reserva recursos do seu saldo disponível. A plataforma executa verificações como validação de dados, limites, status da conta e regras de compliance. Se essas verificações forem bem-sucedidas, o pagamento passa para ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSFERRING"]},". Se a requisição for previsivelmente inválida ou violar regras de negócio, de risco ou regulatórias, o pagamento passa para ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},". Se ocorrer um erro inesperado da plataforma ou do sistema, o pagamento passa para ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSFERRING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["O pagamento está percorrendo a rede até o beneficiário final. Os recursos foram reservados ou debitados do seu saldo disponível enquanto a Ripple e os parceiros pagadores tentam concluir o pagamento. Se um parceiro ou serviço interno rejeitar o pagamento por um motivo previsível e corrigível pelo usuário, o pagamento passa para ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},". Se um erro inesperado da plataforma ou do sistema impedir a conclusão, o pagamento passa para ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["O pagamento foi recusado porque a instrução de pagamento não é aceitável na forma atual. As causas típicas incluem dados inválidos ou ausentes, problemas de status ou de limite da conta, questões de autorização ou regras regulatórias e de compliance aplicadas pela Ripple ou por um parceiro downstream. O pagamento não será concluído nem tem nova tentativa automática. Os recursos reservados são liberados de volta ao saldo disponível do ordenante. Para prosseguir, corrija o problema descrito na mensagem de erro e envie um novo pagamento."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["O pagamento foi processado com sucesso e o beneficiário foi creditado conforme a cotação acordada. Este é um estado terminal para pagamentos concluídos com sucesso."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Não foi possível concluir o pagamento por causa de um erro inesperado da plataforma, do sistema ou da rede que a Ripple não classifica como recusa previsível. O motivo da falha, quando disponível, é retornado nos detalhes do erro. Os recursos reservados para o pagamento são liberados e devolvidos ao saldo disponível do ordenante, quando aplicável."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["O pagamento havia sido marcado como ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},", mas foi devolvido depois por uma instituição downstream (por exemplo, o banco do beneficiário) após o beneficiário ter sido creditado inicialmente. Este é um estado terminal. Os recursos voltam ao ordenante, e a devolução fica visível nos seus relatórios e notificações de pagamento. Os clientes não podem acionar devoluções diretamente."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"como-o-declined-se-diferencia-de-failed-e-returned","__idx":2},"children":["Como o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}," se diferencia de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}]},": a plataforma ou um parceiro downstream se recusou a processar o pagamento porque a requisição é inválida ou não pode ser aceita na forma atual. O problema costuma ser corrigível pelo usuário (por exemplo, ajustar dados, limites ou status da conta) e o pagamento não tem nova tentativa automática."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}]},": um erro inesperado da plataforma ou do sistema impede o processamento do pagamento. Esses erros não dizem respeito, em primeiro lugar, à validade da própria instrução de pagamento."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]}]},": o pagamento foi concluído e o beneficiário foi creditado inicialmente, mas os recursos foram devolvidos depois, resultando no estado terminal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"detalhes-de-execução-do-payout","__idx":3},"children":["Detalhes de execução do payout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Em alguns pagamentos, ","Payments Direct"," retorna metadados de execução adicionais em um campo opcional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payoutExecutionDetails"]}," no objeto de pagamento. Quando presente, esse objeto inclui o payment rail utilizado, informações de tempo e referências de rastreamento específicas da rede, como IDs de transação e números de confirmação."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O campo não é retornado em todos os pagamentos. Não construa fluxos obrigatórios que dependam da presença dele. Para mais informações, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-execution-details"},"children":["Detalhes de execução do payout"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"como-verificar-o-estado-do-pagamento","__idx":4},"children":["Como verificar o estado do pagamento"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Você pode verificar o estado atual de um pagamento e as transições de estado dele no ","Payments Direct UI"," ou pela API do ","Payments Direct","."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"no-payments-direct-ui","__idx":5},"children":["No ","Payments Direct UI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Na interface web do Ripple Payments, abra os detalhes do pagamento que você quer inspecionar."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A aba ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Detalhes do pagamento"]}," mostra a passagem do pagamento pelos estados em uma linha do tempo. Cada entrada mostra o estado e o timestamp em que o pagamento chegou a ele."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A aba ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JSON do objeto de pagamento"]}," traz o objeto de pagamento completo. O campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentState"]}," mostra o estado atual do pagamento."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"usando-a-api-do-payments-direct","__idx":6},"children":["Usando a API do ","Payments Direct"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Você também pode verificar o estado do pagamento pela API de pagamentos:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para verificar o estado atual de um pagamento específico, chame o endpoint ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/payments/{paymentId}"]},". O corpo da resposta inclui o campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentState"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para verificar o histórico de transições de estado de um pagamento, chame o endpoint ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/payments/{paymentId}/states"]},". A resposta mostra cada estado, quando o pagamento chegou a ele e a ordem das transições ao longo do tempo."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"como-os-recursos-são-afetados-em-cada-estado","__idx":7},"children":["Como os recursos são afetados em cada estado"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O estado de um pagamento determina o que aconteceu com os recursos do ordenante:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Estado"},"children":["Estado"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Situação dos recursos"},"children":["Situação dos recursos"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AWAITING_FUNDING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Nenhum recurso reservado ainda. O pagamento aguarda a chegada dos recursos JIT na sua conta de ledger da Ripple."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INITIATED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Nenhum recurso reservado ainda. O pagamento foi enviado, mas ainda não foi validado."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VALIDATING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Os recursos são ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["reservados"]}," do saldo disponível. O ordenante não pode usar recursos reservados em outros pagamentos."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSFERRING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Os recursos são ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["debitados"]},". O pagamento está em andamento; o valor de origem saiu da conta do ordenante."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Os recursos permanecem debitados. A liquidação está confirmada."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Os recursos reservados são ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["liberados"]}," de volta ao saldo disponível. Não houve débito."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Os recursos reservados são ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["liberados"]}," de volta ao saldo disponível. Não houve débito."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Os recursos debitados são ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["creditados de volta"]}," ao saldo disponível. A Ripple trata a devolução automaticamente."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"acompanhamento-das-mudanças-de-estado-com-webhooks","__idx":8},"children":["Acompanhamento das mudanças de estado com webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payments Direct"," envia uma notificação de webhook ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_STATE_TRANSITION"]}," sempre que um pagamento muda de estado. Esta é a abordagem recomendada para monitorar o andamento dos pagamentos em integrações de produção, porque elimina a necessidade de polling."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O payload do webhook segue um design “thin-plus”: inclui o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentId"]}," e o novo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentState"]},", além de campos de contexto como ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceCurrency"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceAmount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["destinationCurrency"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payoutAmount"]}," e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaryToken"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exemplo de payload de webhook"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"4d3f90cf-b70f-5ff1-827a-f8aa9cf84ab9\",\n  \"eventType\": \"PAYMENT_STATE_TRANSITION\",\n  \"eventVersion\": 1,\n  \"eventData\": {\n    \"paymentId\": \"5ce2c433-a96d-48d0-8857-02637a60abf4\",\n    \"paymentState\": \"COMPLETED\",\n    \"sourceCurrency\": \"USD\",\n    \"sourceAmount\": 100.00,\n    \"destinationCurrency\": \"BRL\",\n    \"payoutAmount\": 518.50,\n    \"beneficiaryToken\": \"cb207125-73a7-4a94-8502-a7780f1cae78\",\n    \"createdAt\": \"2026-03-01T14:20:00.000Z\",\n    \"expiresAt\": \"2026-04-30T14:20:00.000Z\"\n  },\n  \"createDate\": \"2026-03-01T14:22:46.000Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Entrega fora de ordem"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ordem de entrega dos webhooks não é garantida. As notificações podem chegar fora de sequência se houver novas tentativas. Use sempre os timestamps de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updatedAt"]}," do endpoint de transições de estado para determinar a sequência de estados autoritativa."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Observação"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As notificações de webhook de eventos ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_STATE_TRANSITION"]}," não incluem detalhes de erro, como códigos de motivo. Para obter os detalhes de erro de pagamentos ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}," ou ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]},", chame ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/payments/{paymentId}"]}," e inspecione o array ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[]"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"como-projetar-um-handler-de-estados-robusto","__idx":9},"children":["Como projetar um handler de estados robusto"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ao construir a lógica de integração que reage aos estados do pagamento, siga estas orientações:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Trate todos os estados terminais explicitamente."]}," Trate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}," e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]}," como desfechos distintos, com comportamentos diferentes a jusante."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Nos pagamentos financiados via JIT, monitore ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AWAITING_FUNDING"]},"."]}," Se a sua integração usa ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["JIT_FUNDING"]},", acompanhe este estado e garanta que os recursos sejam transferidos antes de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jitFundingExpiresAt"]},". Um pagamento que expira em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AWAITING_FUNDING"]}," exige uma nova cotação e um novo pagamento."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Não presuma a ordem dos estados a partir dos webhooks."]}," Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/payments/{paymentId}/states"]}," para confirmar a sequência autoritativa se a ordem de entrega for importante."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},", busque o objeto de pagamento completo"]}," para obter os detalhes do erro antes de decidir tentar novamente."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Implemente idempotência nos handlers de estado."]}," Os webhooks podem ser entregues mais de uma vez. O seu handler precisa ser seguro para chamadas repetidas com o mesmo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentId"]}," e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentState"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Trate estados desconhecidos com elegância."]}," Registre e acione alertas para valores de estado inesperados, mas não descarte o evento."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"operações-relevantes-da-api","__idx":10},"children":["Operações relevantes da API"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Operação"},"children":["Operação"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Método"},"children":["Método"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Caminho"},"children":["Caminho"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Criar um pagamento"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["POST"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v3/payments"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Obter um pagamento por ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["GET"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v3/payments/{paymentId}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Obter as transições de estado pelo ID do pagamento"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["GET"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v3/payments/{paymentId}/states"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Buscar pagamentos"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["POST"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v3/payments/filter"]}]}]}]}]}]}]},"headings":[{"value":"Ciclo de vida do pagamento","id":"ciclo-de-vida-do-pagamento","depth":1},{"value":"Estados do pagamento","id":"estados-do-pagamento","depth":2},{"value":"Como o DECLINED se diferencia de FAILED e RETURNED","id":"como-o-declined-se-diferencia-de-failed-e-returned","depth":3},{"value":"Detalhes de execução do payout","id":"detalhes-de-execução-do-payout","depth":2},{"value":"Como verificar o estado do pagamento","id":"como-verificar-o-estado-do-pagamento","depth":2},{"value":"No Payments Direct UI","id":"no-payments-direct-ui","depth":3},{"value":"Usando a API do Payments Direct","id":"usando-a-api-do-payments-direct","depth":3},{"value":"Como os recursos são afetados em cada estado","id":"como-os-recursos-são-afetados-em-cada-estado","depth":2},{"value":"Acompanhamento das mudanças de estado com webhooks","id":"acompanhamento-das-mudanças-de-estado-com-webhooks","depth":2},{"value":"Como projetar um handler de estados robusto","id":"como-projetar-um-handler-de-estados-robusto","depth":2},{"value":"Operações relevantes da API","id":"operações-relevantes-da-api","depth":2}],"frontmatter":{"seo":{"title":"Ciclo de vida do pagamento"}},"lastModified":"2026-10-21T04:11:32.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/pt-br/products/payments-direct-2/introduction/concepts/payment-lifecycle","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}