Card: Credit Card Direct Payment

This model allows customers to enter their credit card details directly on the Shoplazza checkout page.

Sequence Diagram

Sequence Diagram Steps:

The customer enters their credit card information 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 the payment status to the Shoplazza server.
The Shoplazza server sends the payment result back to the browser.
If 3DS verification is required, the browser redirects the customer to the 3DS verification page. Otherwise, the process skips to Sequence 12.
The customer submits payment verification details on the 3DS 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

If 3DS is not required, the following content is returned (format is consistent with " Asynchronous Notification Payment Results ")

```json
{
  "app_id": "12345",
  "payment_id": "7eb3fefb-6b43-4400-b40a-a2a0531364ae",
  "amount": "254.20",
  "currency": "CAD",
  "status": "failed",
  "transaction_no": "123456789",
  "type": "sale",
  "message": "Charge invalid parameter",
  "error_code": "charge_invalid_parameter",
  "test": false,
  "extension": {
    "foo": "bar"
  },
  "timestamp": "2021-09-01T18:32:20Z"
}

Response Structure

Key	Required	Type	Description
`app_id`	Y	string	Payments app ID.
`payment_id`	Y	string	Payment ID, returns the ID of the request message.
`amount`	Y	string	Order amount.
`currency`	Y	string	Currency type.
`status`	Y	string	Payment status: - `paid`: Payment successful - `failed`: Payment failure - `paying`: Processing payment
`transaction_no`	Y	string	Third-party payment system order number.
`type`	Y	string	Payment type, e.g., `sale`.
`message`	N	string	Payment failure message, required if payment fails.
`error_code`	N	string	Error code (required when `status` is `failed`).
`test`	Y	boolean	Indicates whether the transaction was in test mode.
`extension`	N	object	Custom extended fields.
`timestamp`	Y	long	ISO 8601 formatted timestamp, e.g., `2021-09-01T18:32:20Z`.

3DS Required: Return a redirect URL for 3DS verification.

Success: Return a redirect URL for the payment gateway.

{
  "redirect_url": "https://3ds-verification.example"
}

Failure: Return an error code and message.

{
  "code": "ERR-1234",
  "message": "amount less than 1000"
}