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 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 auth-.rnc.ripplenet.com/oauth/token Receiver requests a bearer token for authentication and authorization for use with authorized RippleNet API operations.
Lock payment Post action to orchestration payment Receiver agrees to the payment terms that the sender has already accepted. This changes the payment state from ACCEPTED to LOCKED.
Complete payment Post action to orchestration payment 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 — These operations are primarily used by senders for initiating and and working with payments.
  • Orchestration notifications — These operations are used both by senders and receivers to get notifications about payments and payment states.
  • Orchestration actions — This category consists of a single API operation, Post action to orchestration payment , 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 to retrieve the full notification details about the status of your payment. For more information, see 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.

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 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.

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 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:

Copy
Copied!
{
    "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, to get the full details of the notification.

Copy
Copied!
GET /v4/orchestration/payment/notification/720a2aab-88ab-4830-befd-dd10218fcadd HTTP/1.1
Host: aclient.i.ripple.com
Content-Type: application/json
Authorization: Bearer <token>

The response to the Get orchestration notification operation contains the details of the notification message.

Copy
Copied!
{
       "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 as follows:

Copy
Copied!
POST /v4/orchestration/payments/action
Host: south-bank.ripplenet.com
Content-Type: application/json
Authorization: Bearer <token>
{   
    "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.

Copy
Copied!
{
    "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.

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 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 as follows:

Copy
Copied!
POST /v4/orchestration/payments/action
Host: south-bank.ripplenet.com
Content-Type: application/json
Authorization: Bearer <token>
{   
    "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.

Copy
Copied!
{
    "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 as follows:

Copy
Copied!
POST /v4/orchestration/payments/action
Host: south-bank.ripplenet.com
Content-Type: application/json
Authorization: Bearer <token>
{
   "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.

Copy
Copied!
{
    "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 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:

Copy
Copied!
{
    "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, to get the full details of the notification.

Copy
Copied!
GET /v4/orchestration/payment/notification/720a2aab-88ab-4830-befd-dd10218fcadd HTTP/1.1
Host: aclient.i.ripple.com
Content-Type: application/json
Authorization: Bearer <token>

The response to the Get orchestration notification operation contains the details of the notification message.

Copy
Copied!
{
       "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 operation as follows:

Copy
Copied!
POST /v4/orchestration/payments/action
Host: south-bank.ripplenet.com
Content-Type: application/json
Authorization: Bearer <token>
{   
    "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 call returns HTTP status 200 OK and a short response confirming the unique reference number for the payment.

Copy
Copied!
{
    "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.