Sale: Jump to Third-Party Payment

Sequence Diagram

Sequence Diagram Steps

  1. The customer selects a payment method and clicks to complete the payment.
  2. The browser sends the payment request to the Shoplazza server.
  3. The Shoplazza server forwards the payment request to the payments app server.
  4. The payments app server returns a redirect URL to the Shoplazza server.
  5. The Shoplazza server sends the redirect URL back to the browser.
  6. The browser redirects the customer to the payment gateway page.
  7. The customer submits payment details on the payment gateway page.
  8. 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.
  9. The Shoplazza server returns a redirect URL to the payments app server.
  10. If the payment fails, the customer is redirected to the cancel_url provided in the payment request.
    1. For
  11. If the payment is successful, the customer is redirected to the complete_url returned by the Shoplazza server.
  12. The customer is directed to the order payment result page based on the payment outcome.
  13. 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.
  14. 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

HeaderDescription
Shoplazza-Shop-IdShop ID in the Shoplazza system.
Shoplazza-Shop-DomainSystem domain name assigned by Shoplazza.
Custom-DomainThe domain name used by the current order, which may be a Shoplazza-assigned domain or a user-defined domain.
Custom-IpThe IP address of the customer's device placing the order.
User-AgentThe user agent string identifying the customer's device and browser.
Shoplazza-Request-IdThe unique ID of the request.
Shoplazza-Api-VersionThe Open API version.
Shoplazza-Hmac-Sha256Digital signature for request validation.
Customer-CpfTax 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"
}