Sale: Jump to third-party payment

In the sale model, the customer is redirected from Shoplazza checkout to a third-party payment page to complete the transaction.

Sequence diagram steps

1. The customer selects a payment method and clicks to complete payment.
2. The browser sends the payment request to the Shoplazza server.
3. The Shoplazza server forwards the payment request to the payments app server.
4. The payments app server returns a redirect URL to the Shoplazza server.
5. The Shoplazza server sends the redirect URL back to the browser.
6. The browser redirects the customer to the payment gateway page.
7. The customer submits payment details on the payment gateway page.
8. The payments app server calls the Complete Payment API.
9. Shoplazza returns a redirect URL to the payments app server.
10. If payment fails, the customer is redirected to the cancel_url provided in the payment request.
11. If payment succeeds, the customer is redirected to the complete_url returned by Shoplazza.
12. The customer is directed to the order payment result page.
13. The payments app server sends the final payment result notification to the callback URL.
14. Shoplazza acknowledges receipt of the notification with HTTP 200.

Payment request

When initiating payment, Shoplazza sends request headers and parameters to the payment system.

Request headers

Header	Description
Shoplazza-Shop-Id	Shop ID in the Shoplazza system.
Shoplazza-Shop-Domain	System domain assigned by Shoplazza.
Custom-Domain	Domain used by the current order.
Custom-Ip	Customer device IP address.
User-Agent	Customer browser user agent.
Shoplazza-Request-Id	Unique request ID.
Shoplazza-Api-Version	Open API version.
Shoplazza-Hmac-Sha256	Digital signature for request validation.
Customer-Cpf	Tax ID number when applicable.

Request parameters

Key	Required	Type	Description
id	Yes	string	Payment ID used for idempotency.
app_id	Yes	string	Payments app ID.
account_id	Yes	string	Merchant ID in the payment provider system.
shoplazza_order_id	Yes	string	Shoplazza order ID.
amount	Yes	string	Order amount with two decimal places.
currency	Yes	string	Currency code, such as CAD.
products	Yes	string	Serialized JSON string for product information.
cancel_url	Yes	string	URL used when the customer cancels payment.
complete_url	Yes	string	Synchronous payment completion callback URL.
callback_url	Yes	string	Asynchronous payment notification callback URL.
customer_email	No	string	Customer email.
customer_phone_number	No	string	Customer phone number.
customer_billing_*	Varies	string	Billing address fields.
customer_shipping_*	Varies	string	Shipping address fields.
test	No	boolean	Whether the request is in test mode.
type	Yes	string	Payment type. Use sale for redirect payment.
timestamp	Yes	long	Request timestamp.

Response

For a successful payment session creation, return the third-party payment page URL.

{
  "redirect_url": "https://payment-gateway.example/pay"
}

For failures, return an error code and message.

{
  "code": "ERR-1234",
  "message": "Invalid amount"
}