Payment flow overview

This section explains the payment and refund flows that a payments app can support.

Core functionalities

Payment apps must support the following core capabilities:

• Payment processing: Initiate and process payment transactions.
• Refund processing: Process refund requests for completed payments.
• Result notification: Notify Shoplazza of payment and refund results.
• Test mode: Support test transactions for development and verification. Shoplazza passes the test parameter to indicate whether a transaction is in test mode.

3DS verification

If a credit card payment requires 3-D Secure verification based on the country or region, the payment system must support 3DS verification.

Idempotency

All payment and refund requests must be idempotent. Shoplazza includes a unique id in request parameters, and the payment system must ensure the same id is not processed more than once.

Retry policy

Payment apps rely on asynchronous communication to notify Shoplazza of payment and refund results. If Shoplazza does not acknowledge a callback with HTTP 200 OK, retry the request according to the retry policy.

Parameter	Description	Value
Maximum retry attempts	Total retry attempts allowed if no HTTP 200 is received.	18 retries
Initial retry delay	Delay before the first retry attempt.	5 seconds
Exponential backoff factor	Subsequent retries occur at increasing intervals until acknowledgment or timeout.	See example

Example retry intervals:

[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 support one payment mode. Multiple payments apps can be used when different payment modes are required.

Method	Description	Notes
Sale	The customer is redirected to a third-party payment page to complete the transaction.	Suitable for most payment gateways.
Card	The customer enters credit card details directly on the Shoplazza checkout page.	Requires PCI-DSS compliance and must support 3DS when required.
Iframe	A third-party payment window is embedded within the Shoplazza checkout page.	Supports custom iframe dimensions.

For iframe payments:

• Minimum width: 300px
• Minimum height: 200px
• Maximum width and height: screen dimensions. Values exceeding screen size default to 80vw x 80vh.

Digital signature

All requests between Shoplazza and the payment system must include a digital signature for verification.

1. Sort JSON fields in the request body alphabetically.
2. Concatenate all key-value pairs into a single string.
3. Use HMAC-SHA256 to generate the signature.
4. Include the signature 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",
    "test": false,
    "type": "sale",
    "timestamp": "1724155549"
}', 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';
echo hash_hmac('sha256', $str, $key);

Common signature errors

• Parameter values are incorrectly formatted.
• The secret key does not match the one configured for the merchant.
• Boolean values are not converted to true or false strings.
• Amounts are not formatted to two decimal places.
• Empty fields are included in the signature string.
• The concatenation string contains = or &; it should be key1value1key2value2....

Merchant configuration

To activate a payment system, merchants go to Settings > Payments in the Shoplazza store admin and enter the merchant number and secret key provided by the payment provider.