Process Payment Request​

When a buyer selects the payment app to make payment during the checkout process, SHOPLINE will use the predetermined parameter protocol to initiate an HTTP call to the latest payment URL set by your payment app, and redirect the buyer to the PaymentUrl returned by you. After the payment is completed, you need to redirect the buyer back to the RedirectUrl passed in the interface, where the buyer will wait for the final payment result. You can synchronize payment results to SHOPLINE in the following two ways:

1. Provide a payment query URL, then SHOPLINE will initiate HTTP calls through the payment query URL at a certain frequency after calling the payment URL, and try to get the result of the payment until the final status is obtained or the final timeout (usually 24 hours) ;
2. Actively call our payment notification Webhook interface until a correct response is returned;

How the payment app flow works​

The following diagram illustrates how the payment flow between the payment app and SHOPLINE works:

1. The customer completes the checkout, triggering a payment request.
2. SHOPLINE sends a backend request to the payment app specifying the amount and currency to be charged.
3. The payment app responds with the redirect URL of the payment page hosted by the partner app.
4. SHOPLINE redirects the customer to the redirect URL.
5. The payment app collects the customer's payment credentials and processes the payment as described in the backend request.
6. The payment app sends the payment result to SHOPLINE, and SHOPLINE will implement a retry policy as needed.
7. SHOPLINE responds with a redirect URL and sends a successful HTTP status.
8. The payment app redirects the customer to SHOPLINE.
9. The customer proceeds to checkout.

Please be noted that the payment app should use the payment order number we passed for idempotent processing.

Embedded mode​

Payment Status Flow​

For a payment request initiated by a payment app, we expect its payment status to flow as follows:

Request Payment Interface​

When requesting payment, Shopline will request the payment Url provided by you through Http-Post;
Example request header Corresponds to Http Request Header pay-api-version: 1.0.0 pay-api-idempotency-key: TESTKEYKEYKEY pay-api-signature: SIGNSIGNSIGN pay-api-timestamp: 1665632758606000 pay-api-store-handle: xxx

Example Request Body​

Corresponds to Http Request Body

{
  "orderTransactionId": "test_4ea758952734",
  "referenceOrderId": "test_ff13c864b7fc",
  "amount": 47,
  "currency": "test_6ecc3b427a9f",
  "cancelUrl": "test_a273b5c6sas",
  "redirectUrl": "test_a273b5c641b4",
  "notifyUrl": "test_188f3fe29ae2",
  "billing": {
    "personalInfo": {
      "firstName": "test_fe18d6fc2798",
      "lastName": "test_53fb73557da0",
      "email": "test_e5e3dbd08790",
      "identityType": "test_cac8c5abdbc7",
      "identityNumber": "test_ebc761bb42ac",
      "gender": "test_0704156bc002",
      "phoneNumber": "test_e387bba596a8",
      "homeTelephone": "test_a904ea96f89f",
      "birthDay": "test_dccbf5b55cb6"
    },
    "address": {
      "countryCode": "test_58ee6b67432f",
      "state": "test_c86268fac927",
      "stateCode": "test_bd232ee9b52a",
      "city": "test_a8e72a4b7660",
      "district": "test_60580c478afe",
      "street": "test_f6ca14b11e07",
      "street2": "test_9d168406be68",
      "street3": "test_c9c85ef7c4b6",
      "postcode": "test_7250544bd97d"
    }
  },
  "shipping": {
    "personalInfo": {
      "firstName": "test_4db57f98c782",
      "lastName": "test_d25c9b6d4a07",
      "email": "test_089851321917",
      "identityType": "test_2f2fcc09f376",
      "identityNumber": "test_9b940715498a",
      "gender": "test_5650bb1861d2",
      "phoneNumber": "test_67507bac86dd",
      "homeTelephone": "test_a09b85892bc2",
      "birthDay": "test_9f05f7e481bb"
    },
    "address": {
      "countryCode": "test_096475ce74d7",
      "state": "test_c2113a8b18c9",
      "stateCode": "test_2b8d522f55fa",
      "city": "test_d0a6b9b780ca",
      "district": "test_95a9222ca449",
      "street": "test_a423b3d71c5e",
      "street2": "test_9fb2013867b3",
      "street3": "test_86d526908645",
      "postcode": "test_09ffe0b8cf1b"
    },
    "shippingMethod": "test_7796822bf919",
    "carrier": "test_17327dbfb7ce"
  },
  "products": [
    {
      "id": "test_fb4ef47a1a0f",
      "name": "test_260a61ca16a8",
      "sku": "test_5f883d1deab3",
      "desc": "test_d0cbf7004770",
      "quantity": 38,
      "unitPrice": {
        "value": 54,
        "currency": "test_17c30bdc32b3"
      }
    }
  ],
  "amountBreakdown": {
    "productAmount": 67,
    "discount": 99,
    "productTax": 49,
    "shippingAmount": 10,
    "shippingTax": 5,
    "other": 94
  },
  "merchant": {
    "storeWebsite": "test_b085e7df3518",
    "configData": {}
  },
  "card": {
    "cardNo": "4444444444444444",
    "expirationMonth": "11",
    "expirationYear": "24",
    "cvv": "123",
    "holderName": "test"
  },
  "client": {
    "ip": "test_b556bd9ff25a",
    "deviceType": "test_8baf6c506ef8",
    "deviceId": "test_5a6951dcc93c",
    "javaScriptEnabled": true,
    "javaEnabled": false,
    "colorDepth": "test_8f35331e86f5",
    "screenHeight": "test_e2c2f73f00bf",
    "screenWidth": "test_a0b636ab9ef2",
    "timeZoneOffset": "test_f65b530dfe9c",
    "userAgent": "test_743313c383b4",
    "language": "test_0231f84d3825",
    "transactionWebSite": "test_c991d72e506c",
    "accept": "test_7b30ef6c583c"
  }
}

Response header example​

SHOPLINE must receive the expected result before it considers the call to be successful. If the expected result is not returned, SHOPLINE will consider that the payment request failed due to unknown reasons, and will give the user a prompt on the settlement page;

Corresponds to Http Response Header

pay-api-signature: SIGNSIGNSIGN

Response body example​

Corresponds to Http Response Body

{
  "orderTransactionId": "test_6f047f6db6e3",
  "channelOrderTransactionId": "test_0a9991a24e73",
  "paymentUrl": "test_6b84f55b3972",
  "returnCode": "test_6d7c098e15ff",
  "returnMessage": "test_0b9d14bd55c3",
  "returnMessageId": "test_c02c42012682"
}

For embedded mode:

1. If the payment requires 3DS verification, please return the 3DS verification address in paymentUrl, and we will redirect the buyer to this page;
2. if 3DS verification is not required, please return the redirectUrl passed as an input parameter in paymentUrl, The buyer will wait for the payment result on this page;

Synchronize payment results

After the customer successfully completes the payment process, you can synchronize the payment result to SHOPLINE in the following two ways, and SHOPLINE recommends that you provide both:

1. Payment query URL, then SHOPLINE will initiate an HTTP call through the payment query URL at a certain frequency after calling the payment URL, and try to get the result of the payment until the final status is obtained or the final timeout (usually 24 hours) ;
2. Actively call our payment notification Webhook interface until a correct response is returned;

Payment query request header example​

Corresponding to Http Request Header

pay-api-version: 1.0.0
pay-api-idempotency-key: TESTKEYKEYKEY
pay-api-signature: SIGNSIGNSIGN
pay-api-timestamp: 1665632758606000

Example Payment Query Request Parameters​

Corresponding to Http Request Query orderTransactionId=SLASDJK12312131

Payment Query Response Header Example​

Corresponding to Http Response Header pay-api-signature: SIGNSIGNSIGN

Example Payment Query Response Body​

Corresponding to Http Response Header Body

Proactively notify SHOPLINE of the payment result​

You can actively notify SHOPLINE of the payment result by calling the OpenApi interface of the payment result notification; After receiving the notification, SHOPLINE will obtain the payment result through the payment query interface, and will not directly trust the notification result;

Appendix:​

Country Code​

Country codes use the ISO 3166 international standard.

[Currency and Precision Definition]​