Core Functionalities
Payment Processing
The payment flow must support the following basic functionalities:
- Payment: Initiate and process payment transactions.
- Refund: Process refund requests for completed payments.
- Result Notification: Notify Shoplazza of payment and refund results.
- Test Mode: Support a test mode for development and testing purposes. When initiating a payment, Shoplazza will pass a test parameter (boolean type) to indicate whether the transaction is in test mode. No actual payment will be processed in test mode.
3DS Verification
If the credit card used for payment requires 3DS (3-D Secure) verification based on the country or region, the payment system must support 3DS verification.
Idempotency
To avoid duplicate payments caused by retries, all payment requests must be idempotent. Shoplazza will include a unique id field in the request parameters. The payment system must ensure that the same id is not processed more than once.
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
Payment Models
A payments app can only support one payment mode, and multiple payments apps can be applied to support different payment modes
| Method | Description | Notes |
|---|---|---|
| Sale (Redirect Payment) | The customer is redirected to a third-party payment page to complete the transaction. | Suitable for most payment gateways. |
| Card (Direct Credit Card Payment) | The customer enters their credit card details directly on the Shoplazza checkout page. | Requires PCI-DSS compliance. Supports 3DS verification if required. |
| Iframe (Embedded Payment) | A third-party payment window is embedded within the Shoplazza checkout page using an iframe. | Customizable dimensions: - Minimum width: 300px - Minimum height: 200px - Maximum width/height: Screen dimensions (values exceeding screen size will default to 80vw × 80vh). |
Digital Signature
Signature Mechanism
All requests between Shoplazza and the payment system must include a digital signature for verification. The signature is calculated as follows:
- Sort the JSON fields in the request body alphabetically.
- Concatenate all key-value pairs into a single string.
- Use the HMAC-SHA256 algorithm to generate the signature. The key for the signature is the merchant's secret key provided by the payment platform.
The signature is included in the Shoplazza-Hmac-Sha256 HTTP header.
PHP Example
$data = json_decode('{
"id": "1c2bbaf5-774d-4a44-b2b8-641d09151c12",
"app_id": "99999",
"account_id": "10013",
"shoplazza_order_id": "999993147340725412810",
"amount": "10.00",
"currency": "USD",
"cancel_url": "https://test.myshoplaza.com/checkout/999993147340725412810?pay_token=4673af48023b4d83909540b2769fabb0",
"complete_url": "https://test.myshoplaza.com/openapi/2021-07/payments_apps/complete_callbacks?version=1.0",
"callback_url": "https://test.myshoplaza.com/openapi/2021-07/payments_apps/notify_callbacks?version=1.0",
"customer_email": "[email protected]",
"customer_phone_number": "",
"customer_billing_address1": "a s d",
"customer_billing_address2": "asd",
"customer_billing_last_name": "zhao",
"customer_billing_first_name": "xishng",
"customer_billing_province": "Chongqing",
"customer_billing_city": "重庆",
"customer_billing_postal_code": "400000",
"customer_billing_country_code": "CN",
"customer_billing_company": "",
"customer_billing_state": "CQ",
"customer_billing_phone": "",
"customer_shipping_address1": "a s d",
"customer_shipping_address2": "asd",
"customer_shipping_last_name": "zhao",
"customer_shipping_first_name": "xisan",
"customer_shipping_province": "Chongqing",
"customer_shipping_city": "重庆",
"customer_shipping_postal_code": "400000",
"customer_shipping_country_code": "CN",
"customer_shipping_company": "",
"customer_shipping_state": "CQ",
"customer_shipping_phone": "",
"ip": "171.43.249.13",
"test": false,
"type": "sale",
"timestamp": "1724155549",
"products": [
{
"name": "测试商品",
"quantity": 1,
"unit_price": "10.00",
"sku": "5",
"url": "https://test.myshoplaza.com/products/测试商品",
"desc": "测试商品"
}
]
}', true);
ksort($data);
$str = '';
foreach ($data as $key => $value) {
if ($key == 'amount') {
$value = bcadd($value, 0, 2);
}
if (is_bool($value)) {
$value = $value ? 'true' : 'false';
}
if (is_array($value)) {
$value = json_encode($value);
}
if (mb_strlen($value) > 0) {
$str .= $key . $value;
}
}
$key = '47adb962a5e4425185333564ab8a2fbe'; // Merchant secret key
echo hash_hmac('sha256', $str, $key);
Common Signature Error
- Incorrect Parameter Values
- Ensure all parameters contain valid and correctly formatted values as per the API documentation.
- Incorrect Secret Key
- Verify that the secret key used for signing matches the one provided in the API settings.
- Errors in the Signature Algorithm:
- Boolean Values : Boolean values (e.g.,
test) must be represented as strings: - Amount Formatting: Amounts must be formatted to 2 decimal places.
- Empty Fields in Signature: Empty fields must not be included when generating the signature.
- Concatenation Rules: When constructing the signature string:Do not append
=or&between values. Ensure values are concatenated in the exact sequence required by the API.
Str = "key1" + "value1" + "key2" + "value2" +...
Following these guidelines will help prevent signature verification errors.
Merchant Configuration
To activate the payment system, merchants must:
- Go to Settings > Payments in the Shoplazza store dashboard.
- Enter the merchant number and secret key.