Processing a payment

Payment processing begins when Shoplazza sends an HTTP request to your payments app. Your app responds with a redirect URL that Shoplazza uses to redirect the customer to your app's payment page. Once the payment is completed, you need to communicate the transaction result back to Shoplazza via 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. (HTTP 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 responds with a confirmation, including the redirect URL. (HTTP 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

Shoplazza’s Payments Apps APIs rely on asynchronous communication, meaning you must send an OpenAPI request to notify Shoplazza of the results of any payment or refund transactions. To ensure data consistency between merchants, partners, and Shoplazza, implementing a robust retry policy is critical.

If Shoplazza does not acknowledge your OpenAPI request with an HTTP 200 OK status code, you must retry the request following the incremental strategy outlined below. This strategy allows for up to 18 retries within a 24-hour period.

Parameter	Description	VAlue
Maximum Retry Attempts	The total number of retry attempts allowed if no acknowledgment (HTTP 200) is received from Shoplazza.	18 retries
Initial Retry Delay	The time delay before the first retry attempt.	5 seconds
Exponential Backoff Factor	Each subsequent retry occurs at increasing intervals, calculated using exponential backoff logic, until acknowledgment is received or 24 hours elapse.	See the following example

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