{"templateId":"markdown","versions":[{"version":"v2026.03","label":"v2026.03","link":"/products/payments-direct-2/api-docs/concepts/payment-states","default":true,"active":true,"folderId":"eb16255d"},{"version":"v2025.11","label":"v2025.11","link":"/products/payments-direct-2/v2025.11/api-docs/concepts/payment-states","default":false,"active":false,"folderId":"eb16255d"}],"sharedDataIds":{"sidebar":"sidebar-products/payments-direct-2/@v2025.11/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Payment states","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com/products/custody","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"payment-states","__idx":0},"children":["Payment states"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every payment in ","Ripple Payments Direct"," 2.0 moves through a defined set of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["states"]}," from the moment a quote is accepted to final settlement. Understanding these states is fundamental to building a reliable integration. They determine when funds move, when an error has occurred, and what action (if any) your system should take next."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-youll-learn","__idx":1},"children":["What you'll learn"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["What each payment state means and when it occurs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How to follow the normal payment lifecycle from quote to completion."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The key differences between ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How funds in your account are affected at each state."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How to track state changes using the API and webhooks."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-states-reference","__idx":2},"children":["Payment states reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentState"]}," field appears on every payment object and state transition record. The following states are currently defined:"]},{"$$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":"State"},"children":["State"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Terminal?"},"children":["Terminal?"]}]}]},{"$$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":["The payment is waiting for funds to be transferred to your Ripple ledger account. This state applies only to just-in-time (JIT) funded payments. The payment will proceed once funding is confirmed, or expire if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jitFundingExpiresAt"]}," is reached."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$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":["The payment has been submitted and is awaiting validation by Ripple."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$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":["Ripple is validating the payment details and reserving funds from the originator's available balance."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$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":["The payment is being processed and funds are moving through the network toward the beneficiary. The source amount has been debited from the originator's account."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$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":["The payment has completed and the beneficiary has received the funds."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Yes"]}]}]},{"$$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":["The payment could not be completed. Any funds previously reserved to complete the payment are released back to the available balance."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Yes"]}]}]},{"$$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":["The payment was returned by a downstream institution after initially completing. Funds that were previously reserved and debited are returned and added back to the available balance."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Yes"]}]}]},{"$$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":["The payment was declined due to user input errors or business rule violations. Any funds previously reserved to complete the payment are released back to the available balance."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Yes"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Forward compatibility"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Additional states may be introduced in the future. Design your integration to handle unknown payment states gracefully. Do not fail hard on unexpected ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentState"]}," values."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-payment-lifecycle","__idx":3},"children":["The payment lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The typical, successful lifecycle of a payment follows this progression:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/payment-states-rpd2-happy-path.c0fb43a0a62e223b1e76571839c9ec581c9d8c21ac59ed41b1aaa61bd19d64d1.a69a9225.png","alt":"Payment lifecycle"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For pre-funded and credit-funded payments, a payment enters ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INITIATED"]}," as soon as it is submitted by accepting a valid quote. It then moves through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VALIDATING"]}," while Ripple checks payment details and reserves funds. When validation succeeds, the payment enters ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSFERRING"]}," as funds move to the beneficiary, and finally reaches ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]}," when settlement is confirmed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For just-in-time (JIT) funded payments, the payment begins in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AWAITING_FUNDING"]}," until funds are received in your Ripple ledger account, then proceeds to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INITIATED"]}," and follows the same path to completion. If funds are not received before ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jitFundingExpiresAt"]},", the payment expires."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"terminal-states","__idx":4},"children":["Terminal states"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A terminal state means the payment lifecycle has ended and no further transitions will occur. There are four terminal states:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]}," -"]}," the successful outcome."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," -"]}," a processing or system error prevented completion."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}," -"]}," a validation or business rule error prevented completion."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]}," -"]}," the payment completed but was subsequently reversed by a downstream institution."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once a payment reaches a terminal state, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentId"]}," can no longer be used to initiate further activity. If you need to retry, you must create a new quote and payment."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-funds-are-affected-at-each-state","__idx":5},"children":["How funds are affected at each state"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The state of a payment determines what has happened to the originator's funds:"]},{"$$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":"State"},"children":["State"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fund status"},"children":["Fund status"]}]}]},{"$$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":["No funds reserved yet. The payment is waiting for JIT funds to arrive in your Ripple ledger account."]}]},{"$$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":["No funds reserved yet. The payment has been submitted but not yet validated."]}]},{"$$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":["Funds are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["reserved"]}," from the available balance. The originator cannot use reserved funds for other payments."]}]},{"$$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":["Funds are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["debited"]},". The payment is in flight; the source amount has left the originator's account."]}]},{"$$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":["Funds remain debited. Settlement is confirmed."]}]},{"$$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":["Reserved funds are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["released"]}," back to the available balance. No debit occurred."]}]},{"$$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":["Reserved funds are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["released"]}," back to the available balance. No debit occurred."]}]},{"$$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":["Debited funds are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["credited back"]}," to the available balance. Ripple handles the return automatically."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"understanding-failed-declined-and-returned","__idx":6},"children":["Understanding FAILED, DECLINED, and RETURNED"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These three terminal states all indicate that a payment did not reach the beneficiary, but they have distinct causes and implications:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"failed","__idx":7},"children":["FAILED"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," indicates that ","Ripple Payments"," could not complete the payment due to a processing or system error, for example, a network failure, a timeout with a downstream rail, or an internal service error. The failure is not caused by an error in the payment data you provided."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Funds"]},": Reserved funds are released. No debit occurred."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]},": Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[]"]}," field on the payment object for a reason code, then consider retrying the payment with a new quote after a delay."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"declined","__idx":8},"children":["DECLINED"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}," indicates that the payment was rejected due to user input errors or a business rule violation, for example, invalid beneficiary account details, a compliance rule block, or a field that fails downstream validation."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Funds"]},": Reserved funds are released. No debit occurred."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]},": Review the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[]"]}," field for a specific error code and description. Correct the underlying issue (for example, update the beneficiary's financial instrument) before retrying."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"returned","__idx":9},"children":["RETURNED"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]}," indicates that the payment initially reached ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]}," (funds were debited and settlement was confirmed) but was subsequently returned by a downstream institution or payout partner. For example, the destination bank may have rejected the transfer after it was processed, or a compliance review may have triggered a return."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Funds"]},": Debited funds are credited back to your available balance automatically by Ripple."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]},": Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[]"]}," field on the payment object for the return reason code. In many cases, you will need to correct the beneficiary's details before retrying. No manual fund recovery action is needed."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhook notifications for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_STATE_TRANSITION"]}," events do not include error details such as reason codes. To retrieve error details for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]}," payments, call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/payments/{paymentId}"]}," and inspect the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[]"]}," array."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tracking-state-changes","__idx":10},"children":["Tracking state changes"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"using-the-state-transitions-endpoint","__idx":11},"children":["Using the state transitions endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To retrieve the full history of state changes for a payment, use:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /v3/payments/{paymentId}/state-transitions\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each record in the response includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updatedFrom"]}," - the state before the transition"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updatedTo"]}," - the state after the transition"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updatedAt"]}," - the timestamp of the transition"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example response (excerpt)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"[\n  {\n    \"updatedFrom\": \"INITIATED\",\n    \"updatedTo\": \"VALIDATING\",\n    \"updatedAt\": \"2026-03-01T14:22:10.123Z\"\n  },\n  {\n    \"updatedFrom\": \"VALIDATING\",\n    \"updatedTo\": \"TRANSFERRING\",\n    \"updatedAt\": \"2026-03-01T14:22:18.456Z\"\n  },\n  {\n    \"updatedFrom\": \"TRANSFERRING\",\n    \"updatedTo\": \"COMPLETED\",\n    \"updatedAt\": \"2026-03-01T14:22:45.789Z\"\n  }\n]\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"using-webhooks","__idx":12},"children":["Using webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ripple Payments Direct"," 2.0 sends a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_STATE_TRANSITION"]}," webhook notification each time a payment changes state. This is the recommended approach for monitoring payment progress in production integrations, as it eliminates the need to poll."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The webhook payload uses a \"thin-plus\" design: it includes the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentId"]}," and the new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentState"]},", along with additional context fields such as ",{"$$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"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaryToken"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example webhook payload"]}]},{"$$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":"Out-of-order delivery"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhook delivery order is not guaranteed. Notifications may arrive out of sequence if retries occur. Always use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updatedAt"]}," timestamps from the state transitions endpoint (not webhook arrival order) to determine the authoritative state sequence."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"designing-a-robust-state-handler","__idx":13},"children":["Designing a robust state handler"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When building integration logic that reacts to payment states, follow these guidelines:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Treat all terminal states explicitly."]}," Handle ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURNED"]}," as distinct outcomes with different downstream behavior."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["For JIT-funded payments, monitor ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AWAITING_FUNDING"]},"."]}," If your integration uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["JIT_FUNDING"]},", track this state and ensure funds are transferred before ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jitFundingExpiresAt"]},". A payment that expires in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AWAITING_FUNDING"]}," requires a new quote and payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do not assume state order from webhooks."]}," Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/payments/{paymentId}/state-transitions"]}," to confirm the authoritative sequence if delivery order matters."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},", fetch the full payment object"]}," to retrieve error details before deciding to retry."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Implement idempotency on state handlers."]}," Webhooks may be delivered more than once. Your handler should be safe to call repeatedly for the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentState"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle unknown states gracefully."]}," Log and alert on unexpected state values, but do not discard the event."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"relevant-api-operations","__idx":14},"children":["Relevant API operations"]},{"$$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":"Operation"},"children":["Operation"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Method"},"children":["Method"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Path"},"children":["Path"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create a payment"]},{"$$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":["Get a payment by 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":["Get state transitions by payment ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["GET"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v3/payments/{paymentId}/state-transitions"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Search payments"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["POST"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v3/payments/filter"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":15},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["To learn how to create a payment and handle its lifecycle end-to-end, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/tutorials/create-a-payment"},"children":["Create a payment"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["To understand what happens when a payment is returned and how funds are recovered, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/concepts/payment-returns"},"children":["Payment returns"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["To set up webhooks for real-time state transition notifications, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/best-practices/notification-webhooks"},"children":["Notification webhooks"]},"."]}]}]},"headings":[{"value":"Payment states","id":"payment-states","depth":1},{"value":"What you'll learn","id":"what-youll-learn","depth":2},{"value":"Payment states reference","id":"payment-states-reference","depth":2},{"value":"The payment lifecycle","id":"the-payment-lifecycle","depth":2},{"value":"Terminal states","id":"terminal-states","depth":3},{"value":"How funds are affected at each state","id":"how-funds-are-affected-at-each-state","depth":2},{"value":"Understanding FAILED, DECLINED, and RETURNED","id":"understanding-failed-declined-and-returned","depth":2},{"value":"FAILED","id":"failed","depth":3},{"value":"DECLINED","id":"declined","depth":3},{"value":"RETURNED","id":"returned","depth":3},{"value":"Tracking state changes","id":"tracking-state-changes","depth":2},{"value":"Using the state transitions endpoint","id":"using-the-state-transitions-endpoint","depth":3},{"value":"Using webhooks","id":"using-webhooks","depth":3},{"value":"Designing a robust state handler","id":"designing-a-robust-state-handler","depth":2},{"value":"Relevant API operations","id":"relevant-api-operations","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Payment states","seo":{"title":"Payment states"}},"lastModified":"2026-04-03T15:45:06.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/payments-direct-2/api-docs/concepts/payment-states","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}