{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/payments-odl/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Receive a payment","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":"receive-a-payment","__idx":0},"children":["Receive a payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page is for developers of new applications that receive RippleNet payments. It is recommended that new integrations use the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["orchestration"]}," API operations that make it easy to complete a payment, and to obtain notifications about payment status."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The goals of this topic are:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Describe the high-level payment flow for receivers."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Provide a tutorial to receive one test payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Outline the options for getting notifications about payments."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you read this tutorial, make sure you're familiar with the concepts presented in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/introduction/concepts/payment-flow"},"children":["Payment flow"]}," article."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-flow-for-receivers","__idx":2},"children":["Payment flow for receivers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following table summarizes the flow of tasks a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," must complete to successfully receive a payment."]},{"$$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":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payment flow step"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Related API operation"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Description"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/best-practices/authentication"},"children":["Authorization"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/best-practices/authentication#determine-the-desired-environment"},"children":["auth-&lt;environment>.rnc.ripplenet.com/oauth/token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Receiver requests a ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["bearer token"]}," for authentication and authorization for use with authorized RippleNet API operations."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#lock-payment"},"children":["Lock payment"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/sendorchestrationpaymentaction"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Post action to orchestration payment"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Receiver agrees to the payment terms that the sender has already accepted. This changes the payment state from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCEPTED"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCKED"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#complete-payment"},"children":["Complete payment"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/sendorchestrationpaymentaction"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Post action to orchestration payment"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Receiver confirms receipt of the payment and the payout to the beneficiary. This changes the payment state to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"the-orchestration-api-operations","__idx":3},"children":["The orchestration API operations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To complete a payment, both the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," require a very small set of API operations that use ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["orchestration"]}," to streamline the workflow. These orchestration operations not only simplify the process of completing a payment, but they also support ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["webhooks"]}," for delivering notifications about payment states."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Note about '_orchestration_' and '_templates_'"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The term ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["orchestration"]}," refers to a pre-defined sequence of actions that occur during a payment flow. The payment flow is governed by an ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["orchestration template"]}," (sometimes referred to as a ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["workflow template"]},") that defines the action that the RippleNet service takes automatically at each stage of the payment process."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Orchestration templates are pre-defined by Ripple, and different payment flows are represented by different templates."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are three categories of orchestration operations:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments"},"children":["Orchestration payments"]}," — These operations are primarily used by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["senders"]}," for initiating and and working with payments."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/getorchestrationpaymentnotifications"},"children":["Orchestration notifications"]}," — These operations are used both by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["senders"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receivers"]}," to get notifications about payments and payment states."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/sendorchestrationpaymentaction"},"children":["Orchestration actions"]}," — This category consists of a single API operation, ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/sendorchestrationpaymentaction"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Post action to orchestration payment"]}]},", that lets you perform various webhook-enabled actions on payments. For example, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receivers"]}," use this API operation both to lock and to complete a payment."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"check-payment-status","__idx":4},"children":["Check payment status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To check the status of your payment, you first need to receive notification of a status change."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The recommended way to receive notifications is to set up ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["webhooks"]}," notifications and have RippleNet post to a previously registered callback URL. The body of the post contains a message ID (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uuid"]},") that you can use with a call to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/getorchestrationpaymentnotificationbyuuid"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Get orchestration notification"]}]}," to retrieve the full notification details about the status of your payment. For more information, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/best-practices/webhooks"},"children":["Webhooks"]}," under Best Practices."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Alternatively, if webhooks is not an option for you, you can use ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["polling"]}," — that is, repeatedly calling a ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Get orchestration notifications"]}," operation, until your payment appears in the response. For more information, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/best-practices/polling-basic"},"children":["Polling"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"receive-a-payment--instructions","__idx":5},"children":["Receive a payment — instructions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following sections describe the steps a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," follows to complete the payment flow."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"prerequisites","__idx":6},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create an application that receives RippleNet payments with webhook notifications, you must have the following :"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Access to your RippleNet test instance."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Credentials to authenticate API authorization to your RippleNet test instance."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A way to make API requests and view the responses. For example, you can use a REST client like Postman, or cURL from the command line."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you are using ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["webhooks"]}," (recommended) a callback URL registered with RippleNet, and the RippleNet IP addresses in the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["allowlist"]}," for your server. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/best-practices/webhooks"},"children":["Webhooks"]}," for more information."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-access-token","__idx":7},"children":["Get access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To access all RippleNet API operations (except the Authentication operation itself), you need a valid access token."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/best-practices/authentication"},"children":["Authentication"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"lock-payment","__idx":8},"children":["Lock payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After authentication to the API, the first step to receive a payment is to lock it. Locking a payment means that your institution has completed data validation and compliance checks, and agrees to, and locks, the terms of the payment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When your institution (as the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]},") and any ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["intermediary"]}," institutions all agree to proceed with the payment by making successful calls to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/sendorchestrationpaymentaction"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Post action to orchestration payment"]}]}," to lock payment, the payment's state changes from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCEPTED"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCKED"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following sections describes the two steps you need to follow to lock payments."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Find payments with status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCEPTED"]},".",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," These are payments for which the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," has agreed to the quote, and are waiting for you to lock them."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Lock each of these payments."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Following these two steps, we also describe how to either decline the lock, or to fail the payment completely at the lock stage."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"find-accepted-quotes","__idx":9},"children":["Find accepted quotes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With webhook notification, Ripple posts a notification to the callback URL that you registered with Ripple, whenever there is a notification available. If the status for the payment described in the notification is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCEPTED"]},", then it's ready for you to change it to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCKED"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The body of the webhook post to your callback URL contains the unique message ID for the notification message:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"msg_id\": \"720a2aab-88ab-4830-befd-dd10218fcadd\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upon receiving the notification, your client application should respond with HTTP success code ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},", to prevent the RippleNet server from retrying the callback."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once your application has the message ID for the notification, you can pass it to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/getorchestrationpaymentnotificationbyuuid"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Get orchestration notification"]}]},", to get the full details of the notification."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"GET /v4/orchestration/payment/notification/720a2aab-88ab-4830-befd-dd10218fcadd HTTP/1.1\nHost: aclient.i.ripple.com\nContent-Type: application/json\nAuthorization: Bearer <token>\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response to the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Get orchestration notification"]}," operation contains the details of the notification message."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n       \"uuid\": \"720a2aab-88ab-4830-befd-dd10218fcadd\",\n       \"notification_type\": \"PAYMENT_SUCCESS\",\n       \"notification_version\": \"1.0\",\n       \"notification_status\": \"ACCEPTED\",\n       \"notification_payload\": {\n           \"sender_end_to_end_id\": \"19999999999-012\",\n           \"payment_id\": \"ab2d66c9-e67a-4020-b0c9-c249912a07a0\",\n           \"payment_status\": \"COMPLETED\",\n           \"previous_payment_status\": \"PREPARED\",\n           \"connector_role\": \"SENDING\",\n           \"payment_type\": \"REGULAR\",\n           \"payout_method\": null,\n           \"original_sender_end_to_end_id\": null,\n           \"output\": null\n       },\n       \"created_at\": \"2021-09-03T12:30:22.081Z\",\n       \"modified_at\": \"2021-09-03T12:30:22.081Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notification_status"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCEPTED"]}," and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notification_type"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_SUCCESS"]},", then this payment is ready for you to lock it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"lock-the-payment","__idx":10},"children":["Lock the payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To lock an accepted quote, call ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/sendorchestrationpaymentaction"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Post action to orchestration payment"]}]}," as follows:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"POST /v4/orchestration/payments/action\nHost: south-bank.ripplenet.com\nContent-Type: application/json\nAuthorization: Bearer <token>\n{   \n    \"unique_reference_number\": \"ab2d66c9-e67a-4020-b0c9-c249912a07a0\",\n    \"status\": \"SUCCESS\",\n    \"notification_type\": \"CONFIRM_LOCK\",\n    \"output\": \"null\",\n    \"error\": \"null\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The required information, passed in the JSON body of the API call, is as follows:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unique_reference_number"]}," – Set this to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_id"]}," for the payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notification_type"]}," – Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONFIRM_LOCK"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," – Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SUCCESS"]}," to lock the payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["output"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," – Set to \"null\" for a successful lock."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the request is successful, the Action API returns HTTP status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}," and a short response confirming the unique reference number for the payment."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"unique_reference_number\": \"ab2d66c9-e67a-4020-b0c9-c249912a07a0\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Notice that this changes payment state from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCEPTED"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCKED"]},". For more information about payment states, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/introduction/concepts/payment-states"},"children":["Payment States"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Next, the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," will make a request to settle the payment. Then, the payment can be paid out to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]},", the relevant accounts on your ledgers can be settled, and the payment can be completed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["But before we look at the payment settlement, let's consider the cases where you, as the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]},", may want to decline the lock, or fail the payment completely."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"decline-the-payment-lock","__idx":11},"children":["Decline the payment lock"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," for the payment, you may wish to decline the lock if the payment information has errors or the compliance check returns hits. The ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/sendorchestrationpaymentaction"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Post action to orchestration payment"]}]}," call is exactly the same, except that you change the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," in the body to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},", and provide a reason for the error so that the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," can fix it and retry."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To decline the lock for a payment, call ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/sendorchestrationpaymentaction"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Post action to orchestration payment"]}]}," as follows:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"POST /v4/orchestration/payments/action\nHost: south-bank.ripplenet.com\nContent-Type: application/json\nAuthorization: Bearer <token>\n{   \n    \"unique_reference_number\": \"ab2d66c9-e67a-4020-b0c9-c249912a07a0\",\n    \"status\": \"DECLINED\",\n    \"notification_type\": \"CONFIRM_LOCK\",\n    \"output\": \"null\",\n    \"error\": [\n        {\n            \"type\":\"RE01\",\n            \"code\":\"ACCT_NUMBER_LENGTH\",\n            \"reason\":\"Incorrect Receiver Account Number Length\"\n        }\n    ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The required information, passed in the JSON body of the API call, is as follows:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unique_reference_number"]}," – Set this to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_id"]}," for the payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notification_type"]}," – Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONFIRM_LOCK"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," – Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINE"]}," to decline the lock."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["output"]}," – Set to \"null\"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," – This is an array of one or more errors that you want to report back to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]},". The error ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," would be unique to each ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]},", but the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}," should be a short description so that the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," can fix the problem, and resend."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the request to decline the lock is successful, the Action API returns HTTP status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}," and a short response confirming the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," unique reference number."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"unique_reference_number\": \"ab2d66c9-e67a-4020-b0c9-c249912a07a0\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"fail-the-payment-lock","__idx":12},"children":["Fail the payment lock"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To permanently fail the lock for a payment, call ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/sendorchestrationpaymentaction"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Post action to orchestration payment"]}]}," as follows:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"POST /v4/orchestration/payments/action\nHost: south-bank.ripplenet.com\nContent-Type: application/json\nAuthorization: Bearer <token>\n{\n   \"error\":[\n      {\n         \"type\":\"SYSTEM_FAILURE\",\n         \"code\":\"RB01\",\n         \"reason\":\"Incorrect Receiver Account Number Length\"\n      },\n      {\n         \"type\":\"ADDITIONALINFO_DATA_VALIDATION\",\n         \"code\":\"RB02\",\n         \"reason\":\"Invalid payment type value\"\n      }\n   ],\n   \"status\":\"FAILURE\",\n   \"unique_reference_number\":\"ab2d66c9-e67a-4020-b0c9-c249912a07a0\",\n   \"notification_type\":\"CONFIRM_LOCK\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The required information, passed in the JSON body of the API call, is as follows:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unique_reference_number"]}," – Set this to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_id"]}," for the payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notification_type"]}," – Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONFIRM_LOCK"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," – Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILURE"]}," to decline the lock."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["output"]}," – Set to \"null\"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," – This is an array of one or more errors that you want to report back to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]},". The error ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," would be unique to each ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]},", but the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}," should be a short description so that the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," can understand why you terminated the payment transaction. In some cases, the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," might choose to correct the problem, and create a new payment."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the request to fail the lock is successful, the Action API returns HTTP status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}," and a short response confirming the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," unique reference number."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"unique_reference_number\": \"849eecc7-bbce-481d-bd40-c243a5cda077\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"complete-payment","__idx":13},"children":["Complete payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After each institution involved in the payment settles the balances on any related ledgers, you can then transfer the funds to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]},". This payout can be completed by a RippleNet institution or through a partner on local rails. As the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," involved in the payment, you must indicate that the payment ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]}," has received the payment, and that the RippleNet payment can be marked as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To do this, call ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/sendorchestrationpaymentaction"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Post action to orchestration payment"]}]}," with a body specifying the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONFIRM_COMPLETE"]}," notification type. If successful, this changes the payment state from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXECUTED"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},", signaling both to RippleNet and to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," that the payment has been settled and that the funds have been delivered to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the normal payment flow, you would verify out-of-band that the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]}," has received the payment before you take action to complete the payment. This tutorial does not include this step."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following sections describe the steps you need to follow to complete the payment."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Find payments with status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXECUTED"]},". These are payments for which the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," has initiated settlement."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deliver the funds to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update the status of the payment to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"find-executed-payments","__idx":14},"children":["Find executed payments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As with finding payments that are candidates to lock, once the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," has settled the payment, you will receive a webhook notification at the callback URL that you registered with Ripple. If the status for the payment described in the notification is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXECUTED"]},", then it is ready for you to change it to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},", once you have verified that the funds have been delivered to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The body of the webhook post to your callback URL contains the unique message ID for the notification message:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"msg_id\": \"720a2aab-88ab-4830-befd-dd10218fcadd\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upon receiving the notification, your callback application should respond with HTTP status code ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},". This stops the RippleNet server from retrying the callback."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once your application has the message ID for the notification, you can pass it to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/getorchestrationpaymentnotificationbyuuid"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Get orchestration notification"]}]},", to get the full details of the notification."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"GET /v4/orchestration/payment/notification/720a2aab-88ab-4830-befd-dd10218fcadd HTTP/1.1\nHost: aclient.i.ripple.com\nContent-Type: application/json\nAuthorization: Bearer <token>\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response to the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Get orchestration notification"]}," operation contains the details of the notification message."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n       \"uuid\": \"720a2aab-88ab-4830-befd-dd10218fcadd\",\n       \"notification_type\": \"PAYMENT_SUCCESS\",\n       \"notification_version\": \"1.0\",\n       \"notification_status\": \"EXECUTED\",\n       \"notification_payload\": {\n           \"sender_end_to_end_id\": \"19999999999-012\",\n           \"payment_id\": \"ab2d66c9-e67a-4020-b0c9-c249912a07a0\",\n           \"payment_status\": \"COMPLETED\",\n           \"previous_payment_status\": \"PREPARED\",\n           \"connector_role\": \"SENDING\",\n           \"payment_type\": \"REGULAR\",\n           \"payout_method\": null,\n           \"original_sender_end_to_end_id\": null,\n           \"output\": null\n       },\n       \"created_at\": \"2021-09-03T12:30:22.081Z\",\n       \"modified_at\": \"2021-09-03T12:30:22.081Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notification_status"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXECUTED"]}," and the notification type is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_SUCCESS"]},", then this payment is ready for you to mark it as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"complete-the-payment","__idx":15},"children":["Complete the payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To complete the payment, call the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/sendorchestrationpaymentaction"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Post action to orchestration payment"]}]}," operation as follows:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"POST /v4/orchestration/payments/action\nHost: south-bank.ripplenet.com\nContent-Type: application/json\nAuthorization: Bearer <token>\n{   \n    \"unique_reference_number\": \"ab2d66c9-e67a-4020-b0c9-c249912a07a0\",\n    \"status\": \"SUCCESS\",\n    \"notification_type\": \"CONFIRM_COMPLETE\",\n    \"output\": \"null\",\n    \"error\": \"null\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The required information, passed in the JSON body of the API call, is as follows:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unique_reference_number"]}," – Set this to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_id"]}," for the payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notification_type"]}," – Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONFIRM_COMPLETE"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," – Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SUCCESS"]}," to complete the payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["output"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," – Set to null for a completed payment."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the request is successful, the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/orchestration-payments/sendorchestrationpaymentaction"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Post action to orchestration payment"]}]}," call returns HTTP status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}," and a short response confirming the unique reference number for the payment."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"unique_reference_number\": \"ab2d66c9-e67a-4020-b0c9-c249912a07a0\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Notice that this changes payment state for the payment from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXECUTED"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},". For more information about payment states, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/introduction/concepts/payment-states"},"children":["Payment States"]},"."]}]},"headings":[{"value":"Receive a payment","id":"receive-a-payment","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Payment flow for receivers","id":"payment-flow-for-receivers","depth":3},{"value":"The orchestration API operations","id":"the-orchestration-api-operations","depth":3},{"value":"Check payment status","id":"check-payment-status","depth":3},{"value":"Receive a payment — instructions","id":"receive-a-payment--instructions","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":3},{"value":"Get access token","id":"get-access-token","depth":3},{"value":"Lock payment","id":"lock-payment","depth":3},{"value":"Find accepted quotes","id":"find-accepted-quotes","depth":4},{"value":"Lock the payment","id":"lock-the-payment","depth":4},{"value":"Decline the payment lock","id":"decline-the-payment-lock","depth":4},{"value":"Fail the payment lock","id":"fail-the-payment-lock","depth":4},{"value":"Complete payment","id":"complete-payment","depth":3},{"value":"Find executed payments","id":"find-executed-payments","depth":4},{"value":"Complete the payment","id":"complete-the-payment","depth":4}],"frontmatter":{"seo":{"title":"Receive a payment"}},"lastModified":"2025-10-03T17:57:05.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/payments-odl/api-docs/ripplenet/tutorials/receive-a-payment/receive-a-payment-basic","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}