Sequence Diagram

Sequence Diagram Steps:

The merchant confirms the refund and submits the request in the Shoplazza backend.
The Shoplazza backend service receives the refund request and initiates the refund process.
The Shoplazza service assembles the refund request and calls the payment app's refund API.
The payments app synchronously returns the refund result.
The Shoplazza backend processes the refund result and displays the outcome.
The payments app asynchronously notifies Shoplazza of the final refund result.
The Shoplazza refund notification service processes the result and updates the order status.

Refund Request Specification

Request Headers

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

Request Header Example

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

Refund Request

By calling the refund session URL, the payment-related information is transmitted to the third party, and the third party synchronously returns the refund result. If the current status is not refunded, the refund result will be asynchronously notified.

Request Body: (The request body format is 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"
}

Request Structure

Parameter	Required	Type	Description
`id`	Y	string	Unique refund ID for idempotency.
`app_id`	Y	string	Payments app ID.
`account_id`	Y	string	Merchant ID in the payment system.
`payment_id`	Y	string	Original payment ID.
`amount`	Y	decimal	Refund amount (2 decimal places).
`currency`	Y	string	Currency code (e.g., USD, CAD).
`callback_url`	Y	string	URL for asynchronous refund result notifications.
`test`	N	boolean	Indicates test mode (no actual refund).
`type`	Y	string	Fixed value: `refund`.
`extra`	Y	string	Additional information (ignored).
`timestamp`	Y	string	Timestamp in ISO 8601 format.

Refund Response

Refund Response Fields

Key	Type	Required	Description
`refund_id`	string	Y	The ID of the refund, used to ensure the idempotence of the request and avoid repeated deductions for one payment.
`status`	string	Y	Refund status: - `refund_success`: Refund completed successfully. - `refund_failed`: Refund failed. - `refund_pending`: Refund is in progress.
`message`	string	Y	Refund description or reason for refund failure.

Refund Response Example

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