Iframe: Pop-up Payment

This model embeds a third-party payment window within the Shoplazza checkout page using an iframe.

Sequence Diagram

Sequence Diagram Steps:

The customer selects a payment method and clicks to complete the payment.
The browser sends the payment request to the Shoplazza server.
The Shoplazza server forwards the payment request to the payments app server.
The payments app server returns a redirect URL to the Shoplazza server.
The Shoplazza server sends the redirect URL back to the browser.
The browser redirects the customer to the payment gateway page.
The customer submits payment details on the payment gateway page.
The payments app server initiates a payment completion callback to the Shoplazza server.
1. For more information about Complete payment callback API, please view Complete payment callback API.
The Shoplazza server returns a redirect URL to the payments app server.
If the payment fails, the customer is redirected to the cancel_url provided in the payment request.
If the payment is successful, the customer is redirected to the complete_url returned by the Shoplazza server.
The customer is directed to the order payment result page based on the payment outcome.
The payments app server sends a final payment result notification to the specified callback URL.
1. For more information about Notify Payment API, please view Notify Payment API.
The Shoplazza server acknowledges receipt of the notification with an HTTP 200 response.

Payment Request Explanation

When initiating a payment, Shoplazza sends the following parameters to the payment system:

Request Header

Header	Description
`Shoplazza-Shop-Id`	Shop ID in the Shoplazza system.
`Shoplazza-Shop-Domain`	System domain name assigned by Shoplazza.
`Custom-Domain`	The domain name used by the current order, which may be a Shoplazza-assigned domain or a user-defined domain.
`Custom-Ip`	The IP address of the customer's device placing the order.
`User-Agent`	The user agent string identifying the customer's device and browser.
`Shoplazza-Request-Id`	The unique ID of the request.
`Shoplazza-Api-Version`	The Open API version.
`Shoplazza-Hmac-Sha256`	Digital signature for request validation.
`Customer-Cpf`	Tax ID number.

Header Example

Shoplazza-Shop-Id: Id
Shoplazza-Shop-Domain: developer.myshoplaza.com
Custom-Domain: www.***.com
Custom-Ip: 000.000.00.00
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36
Shoplazza-Request-Id: 444fac0a-2115-11ec-9621-0242ac130002
Shoplazza-Api-Version: 2021-07
Shoplazza-Hmac-Sha256: e0e408c7c1fe1d69b8b79c8f56daae8321e54c27f3475b0df5a8167a658e09a2
Customer-Cpf: 11111111111-11

Request Parameters

Key	Required	Type	Description
`id`	Y	string	The ID of the payment is used to ensure the idempotence of the request and avoid repeated deductions for one payment.
`app_id`	Y	string	Payments app ID.
`account_id`	Y	string	The ID of the merchant in the third-party payment provider, such as `merNo`, `Account`, etc.
`shoplazza_order_id`	Y	string	Order ID. During the payment process, multiple browser tabs may be opened to initiate payment for the same order, and a `shoplazza_order_id` can only be paid once.
`amount`	Y	string	Order amount, reserved to two decimal places.
`currency`	Y	string	Currency code, e.g., `CAD`.
`products`	Y	string	Payment product information in JSON string format.
`cancel_url`	Y	string	URL the customer is redirected to when they cancel the payment.
`complete_url`	Y	string	Payment result synchronization notification address.
`callback_url`	Y	string	Payment result asynchronous notification address.
`customer_email`	N	string	Customer's email address.
`customer_phone_number`	N	string	Customer's phone number.
`customer_billing_address1`	Y	string	Billing address line 1.
`customer_billing_address2`	N	string	Billing address line 2.
`customer_billing_last_name`	Y	string	Billing last name.
`customer_billing_first_name`	Y	string	Billing first name.
`customer_billing_province`	Y	string	Billing province.
`customer_billing_city`	Y	string	Billing city.
`customer_billing_postal_code`	Y	string	Billing postal code.
`customer_billing_country_code`	Y	string	Billing country code.
`customer_billing_company`	Y	string	Billing company.
`customer_billing_state`	Y	string	Billing state.
`customer_billing_phone`	Y	string	Billing phone number.
`customer_shipping_address1`	Y	string	Shipping address line 1.
`customer_shipping_address2`	N	string	Shipping address line 2.
`customer_shipping_last_name`	Y	string	Shipping last name.
`customer_shipping_first_name`	Y	string	Shipping first name.
`customer_shipping_province`	Y	string	Shipping province.
`customer_shipping_city`	Y	string	Shipping city.
`customer_shipping_postal_code`	Y	string	Shipping postal code.
`customer_shipping_country_code`	Y	string	Shipping country code.
`customer_shipping_company`	Y	string	Shipping company.
`customer_shipping_state`	Y	string	Shipping state.
`customer_shipping_phone`	N	string	Shipping phone number.
`test`	N	boolean	Whether the request is in test mode (`true` or `false`).
`type`	Y	string	Payment type: - `sale`: Redirect payment - `card`: Direct credit card payment
`cards`	N	string	Serialized JSON object containing credit card information for direct payments.
`cards.first_name`	N	string	First name on the card (e.g., `Percy`).
`cards.last_name`	N	string	Last name on the card (e.g., `Parker`).
`cards.card_number`	N	string	Credit card number (e.g., `4242424242424242`).
`cards.expire_year`	N	string	Expiration year (2 digits, e.g., `23`).
`cards.expire_month`	N	string	Expiration month (2 digits, e.g., `06`).
`cards.card_cvv`	N	string	CVV (3 or 4 digits, e.g., `123`).
`timestamp`	Y	long	Timestamp of the request (e.g., `1697704968`).

Request Example

Request Body: (The request body format is x-www-form-urlencoded)
{
  "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",
  "products": "[{\"name\":\"name\",\"quantity\":\"2\",\"unit_price\":\"20.00\",\"sku\":\"2023\",\"url\":\"http://a.bc/def\",\"desc\":\"desc\"}]",
  "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": "lv",
  "customer_billing_first_name": "jianxing",
  "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": "jiaxing",
  "customer_shipping_first_name": "lv",
  "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": "card",
  "cards": "{\"first_name\":\"Percy \",\"last_name\":\"Parker \",\"card_number\":\"4242424242424242 \",\"expire_year\":\"2023 \",\"expire_month\":\"12 \",\"card_cvv\":\"123\"}",
  "timestamp": "1697704968"
}

Response Explanation

Success: Return a redirect URL for the payment gateway.

Shoplazza returns 301 Retargeting, with Location as redirect_url in the header. The customer will be redirected to the payment page of the app to complete the payment.

{
  "redirect_url": "https://payment-gateway.example/pay"
}

Failure: Return an error code and message.

{
  "code": "ERR-1234",
  "message": "Invalid amount"
}

Key Differences from Sale Model:

The payments app can customize the iframe dimensions:

Width and Height: Specified in pixels (no units required).
Minimum Dimensions: 300px (width) × 200px (height).
Maximum Dimensions: Must not exceed the screen size. If exceeded, Shoplazza defaults to 80vw × 80vh for the iframe container.