Processing a refund

Refund processing starts when a merchant submits a refund request in the Shoplazza admin. Shoplazza calls the payments app refund API, and the payments app returns a synchronous result. If the refund is still pending, the payments app must asynchronously notify Shoplazza of the final result.

Sequence diagram steps

1. The merchant confirms the refund and submits the request in the Shoplazza admin.
2. Shoplazza receives the refund request and starts the refund process.
3. Shoplazza assembles the refund request and calls the payments app refund API.
4. The payments app synchronously returns the refund result.
5. Shoplazza processes and displays the refund result.
6. If needed, the payments app asynchronously notifies Shoplazza of the final refund result.
7. Shoplazza processes the refund notification and updates the order status.

Request headers

Header	Description
Shoplazza-Shop-Id	Shop ID in the Shoplazza system.
Shoplazza-Shop-Domain	System domain assigned by Shoplazza.
Shoplazza-Request-Id	Unique request ID.
Shoplazza-Api-Version	Open API version.
Shoplazza-Hmac-Sha256	Digital signature for request validation.

Request parameters

Shoplazza calls the refund session URL and sends payment-related information to the payment provider. The provider synchronously returns the refund result. If the current status is not final, the provider must later send an asynchronous refund notification.

The request body is sent as x-www-form-urlencoded.

{
  "id": "7eb3fefb-6b43-4400-b40a-a2a0531364ae",
  "app_id": "db5fc9a6-2a64-11ec-8d3d-0242ac130003",
  "account_id": "TIOnETZE",
  "payment_id": "7eb3fefb-6b43-4400-b40a-a2a0531364ae",
  "amount": "254.20",
  "currency": "CAD",
  "callback_url": "https://developer.myshoplaza.com/openapi/2021-07/payments_apps/notify_callbacks?version=1.0",
  "test": false,
  "type": "refund",
  "extra": "625598363623041156",
  "timestamp": "2021-09-01T18:32:20Z"
}

Parameter	Required	Type	Description
id	Yes	string	Unique refund ID used for idempotency.
app_id	Yes	string	Payments app ID.
account_id	Yes	string	Merchant ID in the payment provider system.
payment_id	Yes	string	Original payment ID.
amount	Yes	string	Refund amount with two decimal places.
currency	Yes	string	Currency code, such as USD or CAD.
callback_url	Yes	string	URL for asynchronous refund result notification.
test	No	boolean	Whether the request is in test mode.
type	Yes	string	Fixed value: refund.
extra	Yes	string	Additional information.
timestamp	Yes	long	Timestamp in ISO 8601 format.

Refund response

Key	Type	Required	Description
refund_id	string	Yes	Refund ID used for idempotency.
status	string	Yes	Refund status: refund_success, refund_failed, or refund_pending.
message	string	Yes	Refund description or failure reason.

Response example

{
  "refund_id": "db5fc9a6-2a64-11ec-8d3d-0242ac130003",
  "status": "refund_success",
  "message": "success"
}