riverty logo


Get Started Login

Return Notification

See the detailed API documentation for more information.

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.

When a single item or a complete order has been reported for return, Riverty will postpone the payment due date by at least 14-days (depending on merchant settings). This way merchants have sufficient time to receive and process the return and customers do not receive payment reminders for items which they have already posted for return.

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(s) for any damage.

How to integrate the Return Notification

The Return Notification process resembles the Refund Request.

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

Important restrictions:

  • Items must be before their invoice payment due date
  • Items must be unpaid
  • Items with a negative EUR amount (e.g. discounts) are not allowed
  • Items must have an amount > 0 EUR (e.g. free packaging cannot be returned)
  • Currently only BNPL 14/30-day invoice product (e.g. NOT Pay-in-X, Direct Debit from checkout, FLEX)

Sequence Diagram

Return Notification (1).png

An example

In the refund payment example, customer Astrid visited My Riverty to report a return. However, because her merchant uses the Return Notification API, she could have also reported the return directly via her online merchant account. Alternatiely, Astrid could have also used the My Riverty mobile app.

Once Astrid initiates a return via the merchant's webshop, the return notification API postpones the date Astrid will receive a payment reminder by 14 days by default. The remaining invoice balance will be updated for Astrid and is visible in the Riverty app. Astrid now has more time to pay her outstanding balance and return the goods to the merchant. Additionally, the merchant now has more time to receive and process Astrid's return before Astrid receives a payment reminder.

In case the merchant does not send in a Refund API request within the "postponed days (e.g. 14 days)", the first payment reminder is sent, and the invoice balance is set to the initial amount. Unless a full/partial payment has already been made.

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.

Returns and Discounts

If you provide discounts, please make sure all discounts are added as separate items in the Authorize Payment call so that they are not "returnable". This will make sure that the consumer will recieve the correct amount for what needs to be paid in case of partial return. Ideally, while the return process to Riverty is followed at the merchant, the "right" amounts are shown directly (e.g. taking discounts / non-returnable items / return costs) into account.

Return Code Examples

Request Full return

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

Request Partial return

  "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

Consumer view

After the return has been reported via the return notification API, the remaining invoice balance is updated and the consumer is shown a ‘Return pending' label connected to their order in the Riverty app. In case of partial returns the consumer is requested to 'manage’ their payment and pay the new outstanding balance.