Return Notification

Why the Return Notification is important?

The Return Notification API enables merchants to register upcoming returns towards Riverty on behalf of their customers. This empowers customers to report returns from their merchant login/profile page, streamlining the process and providing them with more control over their returns.

Please note, the return notification does not automatically trigger a refund to the consumer. Merchants must separately initiate the refund process upon receiving and inspecting the returned item for any damage.

How to integrate the Return Notification

The Return Notification process resembles the Refund Request.

Return requests can only be completed for transactions which have already been Captured (shipped). The captureNumber, provided in reponse to the Capture Request, is the unique ID required to correctly update the Settlement and Reconciliation between Riverty and Merchants.

Important restrictions:

  • A return notification call can only be requested once per capture.
  • The items in the return notification should be the same as used in the Capture Request
  • Items must be before their invoice payment due date
  • Items must be unpaid

An example

In the refund payment example, customer Astrid visited to report a return. However, because her merchant uses the Return Notification API, she could have also reported the return via her online account with the merchant. Consequently, Astrid can report her return on the merchant's website or app, eliminating the need to login to or the Riverty app.

This request contains the same information as the Authorize, Capture, and Refund requests for the product(s) being reported for return.

The code example below shows a Partial Return Notification, where only one order item out of many is being returned. Sending the POST request to the Return Notification endpoint with no body will trigger a Full Return Notification, reporting all captured items as returned.


  "captureNumber": "800001138",
  "orderItems": [
      "productId": "3323-BRN-M",
      "description": "Woolen hat, brown, Size M",
      "grossUnitPrice": 30,
      "netUnitPrice": 25.21,
      "quantity": 1,
      "vatPercent": 19,
      "vatAmount": 4.79