Payment callbacks API

The Payment Callbacks API lets payment service providers update Shoplazza with the status of payments and refunds.

Payment apps use two callback types:

• Complete payment: A synchronous callback used after customers complete redirect payments, iframe payments, or direct credit card payments that require 3DS verification. Shoplazza returns a redirect URL that sends the customer to the payment completion page.
• Payment and refund notification: An asynchronous callback used to notify Shoplazza of the final result for payments and refunds.

If Shoplazza does not receive a successful response, the payments app must retry the request according to the retry policy.

Complete payment

Requires the write_payment_info access scope.

Use the Complete Payment API after the customer completes payment on a third-party page or after 3DS verification. At this stage, the final payment result does not need to be returned; the goal is to continue the customer-facing payment flow.

Request headers

Header	Description
Access-Token	OAuth authorization token returned upon authentication.
Shoplazza-Shop-Domain	Shoplazza system domain for the store.
Shoplazza-Hmac-Sha256	Signature calculated using the signature method.
Content-Type	Fixed as application/json.

Request parameters

Key	Required	Type	Description
app_id	Yes	string	Payments app ID.
payment_id	Yes	string	Payment ID.
amount	Yes	number	Order amount.
currency	Yes	string	Currency code.
transaction_no	Yes	string	Third-party payment transaction number.
type	Yes	string	Payment type, such as sale or authorization.
test	Yes	boolean	Whether the request is in test mode.
status	Yes	string	Payment status, fixed as paying.
extension	No	object	Custom extension fields.
timestamp	Yes	string	ISO 8601 timestamp.

Successful response

{
  "redirect_url": "https://developer.myshoplaza.com/checkout/12345"
}

Payment and refund notification

Requires the write_payment_info access scope.

Use the notification callback to asynchronously notify Shoplazza of the final payment or refund result. Payments and refunds share the same request format, with different type and status values.

Request headers

Header	Description
Access-Token	OAuth authorization token returned upon authentication.
Shoplazza-Shop-Domain	Shoplazza system domain for the store.
Shoplazza-Hmac-Sha256	Signature calculated using the signature method.
Content-Type	Fixed as application/json.

Request parameters

Key	Required	Type	Description
app_id	Yes	string	Payments app ID.
payment_id	Yes	string	Payment ID.
amount	Yes	number	Order or refund amount.
currency	Yes	string	Currency code.
status	Yes	string	Payment status (paid, failed) or refund status (refund_success, refund_failed).
transaction_no	Yes	string	Third-party payment transaction number.
type	Yes	string	sale for payment notifications or refund for refund notifications.
message	No	string	Failure message, required when the transaction fails.
error_code	Conditional	string	Error code, required when status is failed.
test	Yes	boolean	Whether the request is in test mode.
extension	No	object	Custom extension fields.
timestamp	Yes	string	ISO 8601 timestamp.

Successful response

Shoplazza returns HTTP 200 after receiving the notification.

{}