Refund Payment

See the detailed API documentation for technical reference.

Why Refund Payment Matters

Refunds are a standard part of commerce. Customers may return products, or merchants may issue refunds due to issues such as product defects, minor damages, or delivery delays.

The Refund Payment call enables merchants to process these situations seamlessly. Refunds can also be triggered directly through the Merchant Portal.

Example Scenario

Astrid ordered a woolen hat, a jacket, and socks.

The order was split into two deliveries, and when Astrid received the woolen hat, she noticed the color differed from what she expected. She returns the hat.

Once the merchant receives the hat in good condition with tags attached, the refund is created. The merchant issues a REFUND call from their order management system to the Riverty eCommerce API. Astrid’s invoice is automatically updated, deducting the cost of the hat. She now only pays for the jacket she kept.

Return Costs

Merchants can charge customers a fee for handling returns. This is supported by adding a separate item in the Refund API request with a negative grossUnitPrice value.

For example:

• ✅ Recommended: Add return costs as a distinct item (ensures transparency on the customer’s invoice).
• ❌ Not recommended: Deduct return costs from the original product’s unit price (harms customer experience).

Important: Any fees or additional charges must be clearly disclosed to the customer during the checkout process.

API Call Structure

Capture Number

• A unique ID returned in the CAPTURE response.
• Links the refund to the original invoice

Order Items

• Contains product details, as in the AUTHORIZE or CAPTURE calls.
• Supports:
  • Partial Refunds: refund selected items.
  • Full Refunds: refund all items (if request body is empty).
  • Multiple partial refunds within the same order.
  • Full refund after partial refunds (remaining items only).

Examples

Partial Refund (no return costs)

{
  "items": [
    {
      "imageUrl": "https://developer-sandbox.riverty.com/images/brown_wool_hat.jpg",
      "quantity": 1,
      "productId": "3323-BRN-M",
      "vatAmount": 4.79,
      "vatPercent": 19,
      "description": "Woolen hat, brown, Size M",
      "netUnitPrice": 25.21,
      "grossUnitPrice": 30
    }
  ],
  "captureNumber": "800001138"
}

Partial Refund with Return Costs

{
  "items": [
    {
      "quantity": 1,
      "productId": "3323-BRN-M",
      "vatAmount": 5.21,
      "vatPercent": 21,
      "description": "Woolen hat, brown, Size M",
      "netUnitPrice": 24.79,
      "grossUnitPrice": 30
    },
    {
      "quantity": 1,
      "productId": "567657876",
      "vatAmount": -0.52,
      "vatPercent": 21,
      "description": "Return costs",
      "netUnitPrice": -2.48,
      "grossUnitPrice": -3
    }
  ],
  "captureNumber": "800001157"
}

Example Response

{
  "refundNumbers": [
    "800001139"
  ],
  "totalCapturedAmount": 135,
  "totalAuthorizedAmount": 185
}