Polling

Webhooks is the recommended way to retrieve notification information about payments that need processing. However, if you cannot implement a webhooks-enabled client application — for example, if you are prevented from setting up an allowlist or a callback URL — read this topic to learn about the use of polling as an alternative.

Check for new notifications

To poll the RippleNet service to check for new notifications, call Get orchestration notifications by status setting the status parameter to NEW.

GET /v4/orchestration/payment/notification?status=NEW&size=4 HTTP/1.1
Host: aclient.i.ripple.com
Content-Type: application/json
Authorization: Bearer <token>

The response to the Get orchestration notifications by status operation contains a paginated array of notifications matching the status you specified — all NEW notifications.

[
    {
        "uuid": "2b6a2e11-5740-4887-993a-8c41c6054f18",
        "notification_type": "NOTIFY_ACCEPT",
        "notification_version": "1.0",
        "notification_status": "NEW",
        "notification_payload": {
            "sender_end_to_end_id": "1657713291",
            "payment_id": "3ccb7f01-9a18-439f-8ff4-4779d2e49058",
            "payment_status": "ACCEPTED",
            "previous_payment_status": "PENDING",
            "connector_role": "SENDING",
            "payment_type": "REGULAR",
            "payout_method": null,
            "original_sender_end_to_end_id": null,
            "original_payment_id": null,
            "output": null
        },
        "created_at": "2022-07-13T11:54:55.765Z",
        "modified_at": "2022-07-13T12:08:42.015Z"
    },
    {
        "uuid": "ac086810-2b45-4f70-bd60-42f57a4a046e",
        "notification_type": "NOTIFY_LOCK",
        "notification_version": "1.0",
        "notification_status": "NEW",
        "notification_payload": {
            "sender_end_to_end_id": "1657713291",
            "payment_id": "3ccb7f01-9a18-439f-8ff4-4779d2e49058",
            "payment_status": "LOCKED",
            "previous_payment_status": "ACCEPTED",
            "connector_role": "SENDING",
            "payment_type": "REGULAR",
            "payout_method": null,
            "original_sender_end_to_end_id": null,
            "original_payment_id": null,
            "output": null
        },
        "created_at": "2022-07-13T11:55:12.03Z",
        "modified_at": "2022-07-13T12:08:42.015Z"
    },
    {
        "uuid": "b26842fd-d2b9-4973-b289-00f62efc600b",
        "notification_type": "NOTIFY_SETTLE",
        "notification_version": "1.0",
        "notification_status": "NEW",
        "notification_payload": {
            "sender_end_to_end_id": "1657713291",
            "payment_id": "3ccb7f01-9a18-439f-8ff4-4779d2e49058",
            "payment_status": "PREPARED",
            "previous_payment_status": "LOCKED",
            "connector_role": "SENDING",
            "payment_type": "REGULAR",
            "payout_method": null,
            "original_sender_end_to_end_id": null,
            "original_payment_id": null,
            "output": null
        },
        "created_at": "2022-07-13T11:55:13.187Z",
        "modified_at": "2022-07-13T12:08:42.015Z"
    },
    {
        "uuid": "57016691-fa88-48db-a33c-56baffee6066",
        "notification_type": "NOTIFY_COMPLETE",
        "notification_version": "1.0",
        "notification_status": "NEW",
        "notification_payload": {
            "sender_end_to_end_id": "1657713291",
            "payment_id": "3ccb7f01-9a18-439f-8ff4-4779d2e49058",
            "payment_status": "COMPLETED",
            "previous_payment_status": "PREPARED",
            "connector_role": "SENDING",
            "payment_type": "REGULAR",
            "payout_method": null,
            "original_sender_end_to_end_id": null,
            "original_payment_id": null,
            "output": null
        },
        "created_at": "2022-07-13T11:55:24.011Z",
        "modified_at": "2022-07-13T12:08:42.015Z"
    }
]

Note that the response is limited to returning a maximum number of results at a time, specified with the size=4 field in this example. For information about pagination, see Pagination.

If your payment is not in the array of results, your application will need to keep calling Get orchestration notifications by status until it appears.

When the RippleNet service responds to your request for all NEW notifications, it also immediately changes the notification status from NEW to SENT. This is to prevent re-sending the same notifications the next time you query for NEW notifications. Because it is possible that the RippleNet service may have sent a notification, but your client did not receive it, it is recommended practice to set up a second poller to query for SENT notifications.

Check for sent notifications

Although not required, if you set up a poller to query for NEW notifications, it is recommended to set up a second poller to check periodically for notifications with status SENT. This lets you catch any notifications that were sent by the RippleNet service that somehow were not received and processed by your client integration.

To poll the RippleNet service to check for sent notifications, call Get orchestration notifications by status setting the status parameter to SENT.

GET /v4/orchestration/payment/notification?status=SENT&size=4 HTTP/1.1
Host: aclient.i.ripple.com
Content-Type: application/json
Authorization: Bearer <token>

As with NEW notifications, the response to the Get orchestration notifications by statusoperation contains a paginated array of notifications matching the status you specified.

Note that when the RippleNet server responds to a request for SENT notifications, it does not change the status of the returned notifications, as it does with a request for NEW notifications. So a given notification with status SENT will continue to appear in subsequent requests until your client integration uses Acknowledge orchestration notification to acknowledge that it has received and processed the notification.

Acknowledge notifications

Once your client integration receives a notification about a payment, it can process the payment and advance it to the next step in the payment flow, as described in Send a payment and Receive a payment.

After it processes the payment, your client integration should then call Acknowledge orchestration notification using the UUID for the notification.

PUT /v4/orchestration/payment/notification/2b6a2e11-5740-4887-993a-8c41c6054f18/ack HTTP/1.1
Host: aclient.i.ripple.com
Content-Type: application/json
Authorization: Bearer <token>

This causes the RippleNet server to change the status of the notification from SENT to ACK and prevents your client from seeing the same notification again.

Alternatively, you can acknowledge a batch of notifications at the same time by calling Acknowledge orchestration notifications, and providing a list of notification UUIDs in the JSON body.

PUT /v4/orchestration/payment/notification/ack HTTP/1.1
Host: aclient.i.ripple.com
Content-Type: application/json
Authorization: Bearer <token>
{
  "uuids": [
    "2b6a2e11-5740-4887-993a-8c41c6054f18",
    "ac086810-2b45-4f70-bd60-42f57a4a046e",
    "57016691-fa88-48db-a33c-56baffee6066"
  ]
}

Best practices with pollers

The recommended polling methodology is to set up two pollers:

• The first poller ( poller_new ) runs every minute and queries for NEW notifications.
• The second poller ( poller_sent ) runs every 10 minutes and queries for SENT notifications.

These work together as follows:

1. The first poller ( poller_new ) runs (for example) every 1 minute, and calls Get orchestration notifications by status to query for notifications with status NEW . Your client application can query for as many, or as few, notifications as you want to process at a given time.
2. As RippleNet responds, it changes the notification status for each of the returned notifications from NEW to SENT .
3. The client application processes the payments by getting the full payment object for each, and moving it to the next payment state in the lifecycle ( APPROVED -> LOCKED -> EXECUTED -> COMPLETED .)
4. If there are no problems in Step 3, your client application should call Acknowledge orchestration notification with that UUID, which changes its notification state to ACK . This prevents your client application from seeing that notification again when the second poller ( poller_sent ) runs.
5. If some exception occurs during processing — for example, it is unable to reach the RippleNet server to get the full payment object or update its payment state — then leave it for the second poller by withholding the ACK .
6. Repeat.

The second poller runs with a lower frequency, and is looking for notifications that the client was unable to process previously, as well as any that may have gotten lost in transmission. For example, RippleNet sent the notification in a response to Get orchestration notifications by status but your client application didn't receive it.

1. The second poller ( poller_sent ) runs (for example) every 10 minutes and calls Get orchestration notifications by status to query for notifications with status SENT . In this case we also add a delay_time=10 parameter so we only get notifications that are at least 10 minutes old.
2. The client application processes the payments as above, getting the full payment details, and moving the payment state to the next step.
3. If the client application is able to process the payment, it should call Acknowledge orchestration notification with the UUID. This changes the notification status from SENT to ACK , and thus prevents the second poller ( poller_sent ) from seeing that notification again.
4. If it still runs into some exception, then withhold the ACK . The poller will try again in 10 minutes.
5. Repeat steps 1-4. Set a retry limit so that your client application only tries to process a given UUID n number of times.