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:

2190

payment_app_workflow

  1. The customer completes checkout, triggering a request for payment.
  2. Shoplazza sends a backend request to the payments app, specifying the amount and currency to be charged.
  3. The app responds with a redirect URL for a payment page hosted by the partner's app. (200 OK)
  4. Shoplazza redirects the customer to the redirect URL.
  5. The payments app collects the buyer’s payment credentials and processes the payment as described in the backend request.
  6. The payments app communicates the payment processing result (resolve, reject, or pend) to Shoplazza via OpenAPI, implementing a retry policy as needed.
  7. Shoplazza replies with the redirect URL. (200 OK)
  8. The app redirects the customer to Shoplazza. (301 Redirect)
  9. 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 keyrequiredtypedescription
idYstringPayment ID, Used as the idempotency key
app_idYstringPayment App's ID
account_idYstringMerchant's ID in Payment App
shoplazza_order_idYstringOrder 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.
amountYstringThe amount of the Money
currencyYstringThree-letter ISO 4217 currency code.
cancel_urlYstringThe URL Payment App should redirect to while customer cancel the payment process.
complete_urlYstringThe URL used for the payment app callback when payment is completed
callback_urlYstringThe URL used for the payment app event callback
customer_emailNstringCustomer's Email
customer_phone_numberNstringCustomer's Phone Number
customer_billing_first_nameYstringFirst name for billing address
customer_billing_last_nameNstringLast name for billing address
customer_billing_address1YstringBilling Address 1st line
customer_billing_address2YstringBilling Address 2nd line
customer_billing_provinceYstringProvince for billing address
customer_billing_cityYstringCity for billing address
customer_billing_postal_codeYstringPostal code for billing address
customer_billing_country_codeYstringcountry code for billing address
customer_billing_companyYstringcompany name for billing address
customer_billing_stateYstringstate for billing address
customer_billing_phoneYstringphone number for billing address
customer_shipping_first_nameYstringFirst name for shipping address
customer_shipping_last_nameNstringLast name for shipping address
customer_shipping_address1YstringShipping Address 1st line
customer_shipping_address2YstringShipping Address 2nd line
customer_shipping_provinceYstringProvince for shipping address
customer_shipping_cityYstringCity for shipping address
customer_shipping_postal_codeYstringPostal code for shipping address
customer_billing_country_codeYstringcountry code for shipping address
customer_billing_companyYstringcompany name for shipping address
customer_billing_stateYstringstate for shipping address
customer_billing_phoneYstringphone number for shipping address
testYbooleanIndicates whether the payment is in test or live mode.
typeYstringEither 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.
timestampYstringISO-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
HeaderDescripton
Shoplazza-Shop-DomainThe permanent domain of the merchant's shop. Can be used to identify which shop is initiating the payment.
Custom-DomainThe domain of the merchant's shop. It can be used to identify which domain is initiating the payment.
Shoplazza-Shop-IdThe Shoplazza shop ID
Shoplazza-Request-IdThe unique request ID used to track specific requests for troubleshooting purposes.
Shoplazza-Api-VersionThe API version selected in the payments app configuration. The version selected defines the response payload's format expected by the payments app.
Shoplazza-Hmac-Sha256hmac 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.

ParameterDescriptionVAlue
Number of recommended retriesThe maximum number of recommended retries.18
Base delay intervalThe time interval after which the first retry is attempted.5 seconds
Exponential backoff factorPartners 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