Refunds

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 sufficient 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.

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:

Request

{
  "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
    }
  ]
}

Schema

oaOrderIdstringRequired

The OpenApp order ID.

shopOrderIdstringRequired

The unique ID of the order.

maxLength: 36

currencystringRequired

amountintegerRequired

The refunded amount. Price is expressed as the number (integer) of 1/100s of the price.

minimum: 0

caseIdstringRequired

Reference ID of the claim made by the user or the refund ID. Must be unique for the order.

maxLength: 36

reasonenumRequired

Reason for the refund

Possible values: OTHERRETURNEDWARRANTY

notesstringOptional

Optional explanation of the refund

maxLength: 500

productsarray of RefundProductOptional

Optional list of products that were refunded.

Show child parametersHide child parameters4

idstringRequired

The unique ID of the product.

maxLength: 36

refundedQuantitynumberRequired

The number of refunded products.

minimum: 0

amountintegerRequired

The refunded amount for this product. Price is expressed as the number (integer) of 1/100s of the price.

minimum: 0

notesstringOptional

Optional explanation of the refund

maxLength: 500

Raw JSON Schema

{
  "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