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