Processing a payment

Payment processing begins when Shoplazza makes an HTTP call to your payments app. Your app responds with a redirect URL that Shoplazza uses to redirect the customer to your app's payment page. After the payment is finalized, you need to communicate the result to Shoplazza using OpenAPI.

How the Payment App flow works

The following diagram illustrates how a payment flow works between the payments app and Shoplazza:

The customer completes checkout, triggering a request for payment.
Shoplazza sends a backend request to the payments app, specifying the amount and currency to be charged.
The app responds with a redirect URL for a payment page hosted by the partner's app. (200 OK)
Shoplazza redirects the customer to the redirect URL.
The payments app collects the buyer’s payment credentials and processes the payment as described in the backend request.
The payments app communicates the payment processing result (resolve, reject, or pend) to Shoplazza via OpenAPI, implementing a retry policy as needed.
Shoplazza replies with the redirect URL. (200 OK)
The app redirects the customer to Shoplazza. (301 Redirect)
Customer continues checkout.
For payment processing, both upstream and downstream requests must be idempotent with the payment ID used as the idempotency key.

Asynchronous communications

Payment processing relies on asynchronous communications over HTTP between Shoplazza and the payments app. In an asynchronous system, retry policies are crucial to ensure a robust communication strategy.

Initial the payment flow

The payment flow begins with an HTTP request sent from Shoplazza to the provider's payment session URL provided during apply process. This request contains information about the customer and the order.

{
  "id": "7eb3fefb-6b43-4400-b40a-a2a0531364ae",
  "app_id": "db5fc9a6-2a64-11ec-8d3d-0242ac130003",
  "account_id": "TIOnETZE",
  "shoplazza_order_id": "2711-WFT50903",
  "amount": "254.20",
  "currency": "CAD",
  "cancel_url": "https://developer.myshoplaza.com/checkout/3444-222GOA08029",
  "complete_url": "https://developer.myshoplaza.com/openapi/2021-07/payments_apps/complete_callbacks?version=1.0",
  "callback_url": "https://developer.myshoplaza.com/openapi/2021-07/payments_apps/notify_callbacks?version=1.0",
  "customer_email": "[email protected]",
  "customer_phone_number": "18202787518",
  "customer_billing_address1": "Address detail 1",
  "customer_billing_address2": "Address detail 2",
  "customer_billing_last_name": "LI",
  "customer_billing_first_name": "jiang",
  "customer_billing_province": "Liaoning",
  "customer_billing_city": "Heishan County",
  "customer_billing_postal_code": "123123",
  "customer_billing_country_code": "CN",
  "customer_billing_company": "shoplazza",
  "customer_billing_state": "LN",
  "customer_billing_phone": "13922235670",
  "customer_shipping_address1": "Shipping_address 1",
  "customer_shipping_address2": "Shipping_address 2",
  "customer_shipping_last_name": "jiang",
  "customer_shipping_first_name": "LI",
  "customer_shipping_province": "Liaoning",
  "customer_shipping_city": "Heishan County",
  "customer_shipping_postal_code": "123123",
  "customer_shipping_country_code": "CN",
  "customer_shipping_company": "Shoplazza",
  "customer_shipping_state": "LN",
  "customer_shipping_phone": "13922235670",
  "test": false,
  "type": "sale",
  "timestamp": "2021-09-01T18:32:20Z"
}

params key	required	type	description
id	Y	string	Payment ID, Used as the idempotency key
app_id	Y	string	Payment App's ID
account_id	Y	string	Merchant's ID in Payment App
shoplazza_order_id	Y	string	Order ID, A customer might open multiple tabs in their browser for a given order. All of those tabs will be associated with the same Order ID.
amount	Y	string	The amount of the Money
currency	Y	string	Three-letter ISO 4217 currency code.
cancel_url	Y	string	The URL Payment App should redirect to while customer cancel the payment process.
complete_url	Y	string	The URL used for the payment app callback when payment is completed
callback_url	Y	string	The URL used for the payment app event callback
customer_email	N	string	Customer's Email

customer_phone_number	N	string	Customer's Phone Number
customer_billing_first_name	Y	string	First name for billing address
customer_billing_last_name	N	string	Last name for billing address
customer_billing_address1	Y	string	Billing Address 1st line
customer_billing_address2	Y	string	Billing Address 2nd line
customer_billing_province	Y	string	Province for billing address
customer_billing_city	Y	string	City for billing address
customer_billing_postal_code	Y	string	Postal code for billing address
customer_billing_country_code	Y	string	country code for billing address
customer_billing_company	Y	string	company name for billing address
customer_billing_state	Y	string	state for billing address
customer_billing_phone	Y	string	phone number for billing address
customer_shipping_first_name	Y	string	First name for shipping address
customer_shipping_last_name	N	string	Last name for shipping address
customer_shipping_address1	Y	string	Shipping Address 1st line
customer_shipping_address2	Y	string	Shipping Address 2nd line
customer_shipping_province	Y	string	Province for shipping address
customer_shipping_city	Y	string	City for shipping address
customer_shipping_postal_code	Y	string	Postal code for shipping address
customer_billing_country_code	Y	string	country code for shipping address
customer_billing_company	Y	string	company name for shipping address
customer_billing_state	Y	string	state for shipping address
customer_billing_phone	Y	string	phone number for shipping address
test	Y	boolean	Indicates whether the payment is in test or live mode.
type	Y	string	Either `sale` or `authorization`. If you support payment authorization, then this value is set based on the merchant's configuration. If you don't support separate authorization and capture, then the value is always `sale`. For sale transactions, you need to capture the funds instantly with this request. For authorization transactions, you must place a hold on the funds and capture them later when Shoplazza sends a capture request.
timestamp	Y	string	ISO-8601 format, eg: `2021-09-01T18:32:20Z`

Request Headers

Shoplazza-Shop-Domain: developer.myshoplaza.com
Custom-Domain: www.example.com
Shoplazza-Shop-Id: 27113
Shoplazza-Request-Id: 444fac0a-2115-11ec-9621-0242ac130002
Shoplazza-Api-Version: 2021-07
Shoplazza-Hmac-Sha256: 1dd2bb95e6b19655c1190eb0730d2db74fe1a527945cc0933f0eb59b2811be4a

Header	Descripton
Shoplazza-Shop-Domain	The permanent domain of the merchant's shop. Can be used to identify which shop is initiating the payment.
Custom-Domain	The domain of the merchant's shop. It can be used to identify which domain is initiating the payment.
Shoplazza-Shop-Id	The Shoplazza shop ID
Shoplazza-Request-Id	The unique request ID used to track specific requests for troubleshooting purposes.
Shoplazza-Api-Version	The API version selected in the payments app configuration. The version selected defines the response payload's format expected by the payments app.
Shoplazza-Hmac-Sha256	hmac signature

Response

Shoplazza must receive a HTTP 2xx response for the payment session creation to be successful. If the request fails, then it will be retried a number of times and will eventually transition to an "aborted" state, at which point the buyer will have to retry their payment through Shoplazza checkout. The response must contain the URL for the partner page where Shoplazza will redirect the buyer.

{
  "redirect_url": "https://payments_app_page.com/abc"
}

Retry policy

Due to the asynchronous nature of Shoplazza's Payments Apps APIs, you must send a OpenAPI request to notify Shoplazza of the results of any payment or refund requests. A retry policy helps provide data consistency between merchants, partners, and Shoplazza.

If you don't receive an acknowledgment of a OpenAPI request from Shoplazza (HTTP 200 status code), then you must retry the request according to the following incremental strategy, up to a total of 18 retries over 24h.

Parameter	Description	VAlue
Number of recommended retries	The maximum number of recommended retries.	18
Base delay interval	The time interval after which the first retry is attempted.	5 seconds
Exponential backoff factor	Partners are expected to retry their requests immediately, and then 5 seconds afterwards, and then at increasing time intervals after that, until the request is acknowledged or 24 hours has passed, whichever comes first.	See example below

Example:

[0 seconds, 5 seconds, 10 seconds, 30 seconds, 45 seconds, 1 minute, 2 minutes, 5 minutes, 12 minutes, 38 minutes, 1 hour, 2 hours] + [4 hours] * 5