Skip to content

Refunds callback

The Merchant may initiate a refund to its customer after their order has been placed. The money will be returned via the same payment method as the one used by the customer in the payment process.

It needs to be noted that OA will accept a refund request from the merchant even if the requested refund value exceeds the available balance of the merchant's OA account. In that case the requested refund will await the availability of sufficent funds on the merchant's OA account. Refund requests require a unique caseId. This caseId must be unique for the order, but the same caseId may be used for different orders. If the caseId has already been used for that order, OpenApp will reject the refund as a duplicate.

sequenceDiagram
  autonumber
  actor User
  participant OpenApp
  participant Merchant
  activate User
  Merchant->>+OpenApp: refund callback
  OpenApp->>-User: refund

Request

A refund request is executed by a POST to the following endpoint:

POST {{OpenAppUrl}}/merchant/v1/orders/refund

The request body contains information about the order, the amount and optionally the specific products for which the refund is executed:

Refund request
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "oaOrderId": "OA12345678901234",
  "shopOrderId": "WS1213ASDZXC231A",
  "currency": "PLN",
  "amount": 1999,
  "reason": "RETURNED",
  "caseId": "RET-123434",
  "notes": "Returned without charger cables.",
  "products": [
    {
      "id": "id123",
      "refundedQuantity": 1,
      "amount": 1999
    }
  ]
}
Refund request
{
    "additionalProperties": false,
    "type": "object",
    "properties": {
        "oaOrderId": {
            "description": "The OpenApp order ID.",
            "type": "string",
            "title": "oaOrderId"
        },
        "shopOrderId": {
            "description": "The unique ID of the order.",
            "maxLength": 36,
            "type": "string",
            "title": "shopOrderId"
        },
        "currency": {
            "type": "string",
            "title": "currency"
        },
        "amount": {
            "description": "The refunded amount. Price is expressed as the number (integer) of 1/100s of the price.",
            "minimum": 0,
            "type": "integer",
            "title": "amount"
        },
        "caseId": {
            "description": "Reference ID of the claim made by the user or the refund ID. Must be unique for the order.",
            "maxLength": 36,
            "type": "string",
            "title": "caseId"
        },
        "reason": {
            "description": "Reason for the refund",
            "enum": [
                "OTHER",
                "RETURNED",
                "WARRANTY"
            ],
            "type": "string",
            "title": "reason"
        },
        "notes": {
            "description": "Optional explanation of the refund",
            "maxLength": 500,
            "type": "string",
            "title": "notes"
        },
        "products": {
            "description": "Optional list of products that were refunded.",
            "type": "array",
            "items": {
                "$ref": "#/definitions/RefundProduct"
            },
            "title": "products"
        }
    },
    "required": [
        "amount",
        "caseId",
        "currency",
        "oaOrderId",
        "reason",
        "shopOrderId"
    ],
    "definitions": {
        "RefundProduct": {
            "title": "RefundProduct",
            "type": "object",
            "properties": {
                "id": {
                    "description": "The unique ID of the product.",
                    "maxLength": 36,
                    "type": "string",
                    "title": "id"
                },
                "refundedQuantity": {
                    "description": "The number of refunded products.",
                    "minimum": 0,
                    "type": "number",
                    "title": "refundedQuantity"
                },
                "amount": {
                    "description": "The refunded amount for this product. Price is expressed as the number (integer) of 1/100s of the price.",
                    "minimum": 0,
                    "type": "integer",
                    "title": "amount"
                },
                "notes": {
                    "description": "Optional explanation of the refund",
                    "maxLength": 500,
                    "type": "string",
                    "title": "notes"
                }
            },
            "required": [
                "amount",
                "id",
                "refundedQuantity"
            ]
        }
    },
    "$schema": "http://json-schema.org/draft-07/schema#"
}

Response

In response, OpenApp will confirm registration of the refund request. Execution of the refund to the customer will be visible in the settlement report.

Errors

Error name Code
OrderNotFoundException 404
MerchantOrderOwnershipException 404
RefundExistsException 409
RefundTooMuchException 400
MerchantWalletNotFoundException 404
UserNotFoundException 404