[{"value":"Pay","id":"Pay","hLevel":2,"level":1,"children":[{"value":"Request method","id":"request-method","hLevel":3,"level":2},{"value":"Request headers","id":"request-headers","hLevel":3,"level":2},{"value":"Request body","id":"request-body","hLevel":3,"level":2},{"value":"Response headers","id":"response-headers","hLevel":3,"level":2},{"value":"Response body","id":"response-body","hLevel":3,"level":2}]},{"value":"Get a payment","id":"Get-a-payment","hLevel":2,"level":1,"children":[{"value":"Request method","id":"request-method-1","hLevel":3,"level":2},{"value":"Request headers","id":"request-headers-1","hLevel":3,"level":2},{"value":"Request body","id":"request-body-1","hLevel":3,"level":2},{"value":"Response headers","id":"response-headers-1","hLevel":3,"level":2},{"value":"Response body","id":"response-body-1","hLevel":3,"level":2}]},{"value":"Capture","id":"Capture","hLevel":2,"level":1,"children":[{"value":"Request method","id":"request-method-2","hLevel":3,"level":2},{"value":"Request headers","id":"request-headers-2","hLevel":3,"level":2},{"value":"Request body","id":"request-body-2","hLevel":3,"level":2},{"value":"Response headers","id":"response-headers-2","hLevel":3,"level":2},{"value":"Response body","id":"response-body-2","hLevel":3,"level":2}]},{"value":"Void","id":"Void","hLevel":2,"level":1,"children":[{"value":"Request method","id":"request-method-3","hLevel":3,"level":2},{"value":"Request headers","id":"request-headers-3","hLevel":3,"level":2},{"value":"Request body","id":"request-body-3","hLevel":3,"level":2},{"value":"Response headers","id":"response-headers-3","hLevel":3,"level":2},{"value":"Response body","id":"response-body-3","hLevel":3,"level":2}]},{"value":"Refund","id":"Refund","hLevel":2,"level":1,"children":[{"value":"Request method","id":"request-method-4","hLevel":3,"level":2},{"value":"Request headers","id":"request-headers-4","hLevel":3,"level":2},{"value":"Request body","id":"request-body-4","hLevel":3,"level":2},{"value":"Response headers","id":"response-headers-4","hLevel":3,"level":2},{"value":"Response body","id":"response-body-4","hLevel":3,"level":2}]},{"value":"Get a refund","id":"Get-a-refund","hLevel":2,"level":1,"children":[{"value":"Request method","id":"request-method-5","hLevel":3,"level":2},{"value":"Request headers","id":"request-headers-5","hLevel":3,"level":2},{"value":"Request body","id":"request-body-5","hLevel":3,"level":2},{"value":"Response headers","id":"response-headers-5","hLevel":3,"level":2},{"value":"Response body","id":"response-body-5","hLevel":3,"level":2}]},{"value":"Report shipment tracking","id":"Report-shipment-tracking","hLevel":2,"level":1,"children":[{"value":"Request method","id":"request-method-6","hLevel":3,"level":2},{"value":"Request headers","id":"request-headers-6","hLevel":3,"level":2},{"value":"Request body","id":"request-body-6","hLevel":3,"level":2},{"value":"Response headers","id":"response-headers-6","hLevel":3,"level":2},{"value":"Response body","id":"response-body-6","hLevel":3,"level":2}]},{"value":"Get digital wallet configuration","id":"Get-digital-wallet-configuration","hLevel":2,"level":1,"children":[{"value":"Request method","id":"request-method-7","hLevel":3,"level":2},{"value":"Request headers","id":"request-headers-7","hLevel":3,"level":2},{"value":"Request body","id":"request-body-7","hLevel":3,"level":2},{"value":"Response headers","id":"response-headers-7","hLevel":3,"level":2},{"value":"Response body","id":"response-body-7","hLevel":3,"level":2}]}]

API reference

This article describes detailed information about APIs that are related to payment apps.

Pay

When a buyer completes an order and triggers a payment request, SHOPLINE will call this API to send the request to the payment app. For more information about the communication process, refer to Transaction flow.

Request method

HTTP POST

Request headers

When calling this API, SHOPLINE will include the following request headers:

Field	Required	Description
pay-api-version	Yes	The API version that you selected when configuring the payment app extension.
pay-api-idempotency-key	Yes	Idempotency key. Requests with the same idempotency key should be treated as duplicate requests by the payment app.
pay-api-signature	Yes	The signature value of the request body. After receiving the request, the payment app must verify the signature value to ensure it matches. If it does not match, the request should be considered invalid.
pay-api-timestamp	Yes	The timestamp when the request is initiated, in the format of `yyyyMMddHHmmss`.
pay-api-store-handle	Yes	The handle of the store initiating the payment, which is a unique identifier.

Example:

pay-api-version: 2.0.0
pay-api-idempotency-key: TESTKEYKEYKEY
pay-api-signature: SIGNSIGNSIGN
pay-api-timestamp: 20250304175916
pay-api-store-handle: HANDLE01

Request body

When calling this API, SHOPLINE can include the following parameters in the request body:

Field	Type	Required	Description
orderTransactionId	string	Yes	Payment transaction ID, which is the unique identifier of the payment request.
referenceOrderId	string	Yes	Order ID. It is recommended to display this ID in the order ID field of your payment app backend (if you have one). The merchant can search for the order on the SHOPLINE Admin > Orders page by using this ID.
kind	string	Yes	Payment type. Valid values are: `Sale`: indicates the sale type. For orders of this type, the payment app should automatically perform capture operations after buyer authorization. `Authorization`: indicates the authorization type. For orders of this type, the payment app remains the authorized state after buyer authorization, and should not automatically perform capture operations. For specific logic, refer to Manual capture.
amount	integer	Yes	Transaction amount, greater than 0. The precision varies according to the currency. For details, refer to Currency precision.
currency	string	Yes	Currency of the transaction amount. For details, refer to Currency precision.
redirectUrl	string	Yes	Payment completion URL. After the buyer completes the payment, the payment app must redirect the buyer to this URL. Maximum length: 512
cancelUrl	string	Yes	Payment cancellation URL. When the buyer cancels the payment, the payment app must redirect the buyer to this URL. Maximum length: 512
notifyUrl	string	Yes	URL for receiving asynchronous payment result notifications. When the payment status changes and you want to notify SHOPLINE, you can call the Payment status notification API via this URL. SHOPLINE will assign the `channel_id` and `payment_method` parameters to each payment app. This URL must include these two parameters, as they are required path parameters for the Payment status notification API. Maximum length: 512
billing	object	No	Billing information provided by the buyer on the checkout page.
billing.personalInfo	object	Yes	Personal information provided by the buyer for billing.
billing.firstName	string	No	First name.
billing.lastName	string	Yes	Last name.
billing.email	string	No	Email address.
billing.identityType	string	No	Identity document type.
billing.identityNumber	string	No	Identity document number.
billing.gender	string	No	Gender.
billing.phoneNumber	string	No	Phone number.
billing.homeTelephone	string	No	Home phone number.
billing.birthDay	string	No	Birthday, in the format of `YYYY-MM-DD`.
billing.address	object	Yes	Billing address information provided by the buyer.
billing.countryCode	string	Yes	Country or region code.
billing.state	string	No	State or province.
billing.stateCode	string	No	State or province code.
billing.city	string	No	City.
billing.district	string	No	District.
billing.street	string	No	Street (primary street address, including the full street name and house number).
billing.street2	string	No	Street 2 (supplementary information, such as unit number and floor).
billing.street3	string	No	Street 3 (additional notes, such as nearby landmark and special remarks).
billing.postcode	string	No	Postal code.
shipping	object	No	Shipping information.
shipping.personalInfo	object	Yes	Personal information for the shipping address.
shipping.firstName	string	No	First name.
shipping.lastName	string	Yes	Last name.
shipping.email	string	No	Email address.
shipping.identityType	string	No	Identity document type.
shipping.identityNumber	string	No	Identity document number.
shipping.gender	string	No	Gender.
shipping.phoneNumber	string	No	Phone number.
shipping.homeTelephone	string	No	Home phone number.
shipping.birthDay	string	No	Birthday, in the format of `YYYY-MM-DD`.
shipping.address	object	Yes	Address information.
shipping.countryCode	string	Yes	Country or region code.
shipping.state	string	No	State or province.
shipping.stateCode	string	No	State or province code.
shipping.city	string	No	City.
shipping.district	string	No	District.
shipping.street	string	No	Street (primary street address, including the full street name and house number).
shipping.street2	string	No	Street 2 (supplementary information, such as unit number and floor).
shipping.street3	string	No	Street 3 (additional notes, such as nearby landmark and special remarks).
shipping.postcode	string	No	Postal code.
shipping.shippingMethod	string	Yes	Shipping method, such as express delivery to home.
shipping.carrier	string	No	Shipping carrier, such as FedEx.
products	object[]	Yes	A list of products purchased by the buyer.
products.id	string	Yes	Product ID.
products.name	string	Yes	Product name.
products.sku	string	No	SKU.
products.desc	string	No	Description.
products.quantity	integer	Yes	Product quantity, greater than 0.
products.unitPrice	object	Yes	Unit price, greater than or equal to 0. The precision varies according to the currency. For details, refer to Currency precision.
products.value	integer	Yes	Amount, greater than or equal to 0. The precision varies according to the currency. For details, refer to Currency precision.
products.currency	string	Yes	Currency. For details, refer to Currency precision.
amountBreakdown	object	Yes	Breakdown of the payment amount.
amountBreakdown.productAmount	integer	Yes	Total product amount, greater than or equal to 0. The precision varies according to the currency. For details, refer to Currency precision.
amountBreakdown.discount	integer	Yes	Total discount, greater than or equal to 0. The precision varies according to the currency. For details, refer to Currency precision.
amountBreakdown.productTax	integer	Yes	Total product tax, greater than or equal to 0. The precision varies according to the currency. For details, refer to Currency precision.
amountBreakdown.shippingAmount	integer	Yes	Total shipping amount, greater than or equal to 0. The precision varies according to the currency. For details, refer to Currency precision.
amountBreakdown.shippingTax	integer	Yes	Total shipping tax, greater than or equal to 0. The precision varies according to the currency. For details, refer to Currency precision.
amountBreakdown.other	integer	Yes	Sum of other fees. A value greater than 0 represents a charge, while a value less than 0 represents a deduction. The precision varies according to the currency. For details, refer to Currency precision.
merchant	object	Yes	Merchant information.
merchant.storeWebsite	string	Yes	Domain name of the store.
card	object	No	Credit card information, which will be passed in the direct integration mode.
card.cardNo	string	Yes	Plaintext card number.
card.expirationMonth	string	Yes	Expiration month. The value range is 1-12.
card.expirationYear	string	Yes	Expiration year. The value range is 00-99. For example, a value of `25` indicates the year 2025.
card.cvv	string	Yes	CVV of the card.
card.holderName	string	No	Cardholder's name.
client	object	No	Client information when the buyer initiates the payment, which will be passed in the direct integration mode.
client.ip	string	Yes	Client IP address.
client.deviceType	string	No	Device type.
client.deviceId	string	No	Device ID.
client.javaScriptEnabled	boolean	No	Whether the browser supports JavaScript. `true`: supports `false`: does not support
client.javaEnabled	boolean	No	Whether the browser supports Java. `true`: supports `false`: does not support
client.colorDepth	string	No	Screen color depth, as reported by the browser.
client.screenHeight	string	No	Screen height, as reported by the browser.
client.screenWidth	string	No	Screen width, as reported by the browser.
client.timeZoneOffset	string	No	Local time zone offset of the browser.
client.userAgent	string	No	Browser User-Agent.
client.language	string	No	Browser language.
client.transactionWebSite	string	No	Transaction website URL, which is the URL where the payment is initiated.
client.accept	string	No	Browser's accepted content types.
paymentOptions	object	No	Payment options, currently used for recurring payment scenarios.
paymentOptions.recurringPayment	bool	No	Whether it is a recurring payment scenario. `true`: recurring payment `false`: not recurring payment
paymentOptions.userBehavior	string	No	Payment mode, currently used for recurring payment scenarios. Valid values are: `bindPayment`: indicates that the payment request uses the card-on-file payment mode. The payment app needs to return payment instrument information. `Recurring`: indicates that the payment request uses the direct debit payment mode.
paymentOptions.paymentInstrumentId	string	No	Payment instrument information. This field is available in the direct debit mode under recurring payment scenarios (`userBehavior` = `Recurring`). In this case, the payment app needs to process the direct debit request using this payment instrument information.
paymentMethodInstrument	string	No	Payment instrument information returned by the digital wallet. This field is required for Apple Pay or Google Pay transactions. The payment app must pass this information to the payment channel to complete the transaction.

Example:

{
 {
  "orderTransactionId": "2407354205016528273910-001",
  "referenceOrderId": "2407354205016528273910-001",
  "amount": 47,
  "currency": "USD",
  "redirectUrl": "https://...",
  "cancelUrl": "https://...",
  "notifyUrl": "https://...",
  "billing": {
    "personalInfo": {
      "firstName": "fist",
      "lastName": "last",
      "email": "demo@shopline.com",
      "identityType": "xx",
      "identityNumber": "xxx",
      "gender": "1",
      "phoneNumber": "xx",
      "homeTelephone": "xx",
      "birthDay": "1224"
    },
    "address": {
      "countryCode": "US",
      "state": "California",
      "stateCode": "US-CA",
      "city": "demo city",
      "district": "demo district",
      "street": "demo street",
      "street2": "demo street2",
      "street3": "demo street3",
      "postcode": "82371-2343"
    }
  },
  "shipping": {
    "personalInfo": {
      "firstName": "fist",
      "lastName": "last",
      "email": "demo@shopline.com",
      "identityType": "xx",
      "identityNumber": "xxx",
      "gender": "1",
      "phoneNumber": "xx",
      "homeTelephone": "xx",
      "birthDay": "1224"
    },
    "address": {
      "countryCode": "US",
      "state": "California",
      "stateCode": "US-CA",
      "city": "demo city",
      "district": "demo district",
      "street": "demo street",
      "street2": "demo street2",
      "street3": "demo street3",
      "postcode": "82371-2343"
    },
    "shippingMethod": "Standard shipping",
    "carrier": "Standard shipping carrier"
  },
  "products": [
    {
      "id": "0_18073231123420620812342600",
      "name": "product name",
      "sku": "item-no",
      "desc": "product desc",
      "quantity": 1,
      "unitPrice": {
        "value": 1899,
        "currency": "USD"
      }
    }
  ],
  "amountBreakdown": {
    "productAmount": 1899,
    "discount": 0,
    "productTax": 0,
    "shippingAmount": 699,
    "shippingTax": 0,
    "other": 0
  },
  "merchant": {
    "storeWebsite": "https://...",
  },
  "card": {
    "cardNo": "4444444444444444",
    "expirationMonth": "11",
    "expirationYear": "24",
    "cvv": "123",
    "holderName": "test"
  },
  "client": {
        "accept": "application/json",
        "colorDepth": "24",
        "ip": "xx.xx.xx.xx",
        "javaEnabled": false,
        "javaScriptEnabled": true,
        "language": "en-US",
        "screenHeight": "1920",
        "screenWidth": "1080",
        "timeZoneOffset": "-480",
        "transactionWebSite": "xxx",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36"
    },
  "paymentOptions": {
    "recurringPayment": true,
    "userBehavior": "bindPayment",
    // This field must be specified when the value of userBehavior is Recurring. It is obtained from the response of the card-on-file payment.
    "paymentInstrumentId":"{channelPaymentInstrumentId}"
  },
  // Payment instrument information returned by the digital wallet.
  "paymentMethodInstrument": "{...}"
}
}

Response headers

When responding to SHOPLINE's payment request, the payment app needs to include the following response headers:

Field	Required	Description
pay-api-signature	Yes	The signature value of the response body. After receiving the response, SHOPLINE will verify the signature value to ensure it matches. If it does not match, the response should be considered invalid.

Example:

pay-api-signature: SIGNSIGNSIGN

Response body

When responding to SHOPLINE's payment request, the payment app can include the following response parameters:

Field	Type	Required	Description
returnCode	string	Yes	Response status code. Valid values are: `SUCCESS`: indicates that the call of this API is successful. SHOPLINE will attempt to synchronize the payment result. Any value other than `SUCCESS`: indicates that the payment app has rejected the payment request. The payment status will be set to failed.
returnMessage	string	No	Response description. When `returnCode` is not `SUCCESS`, indicating that the payment app has rejected the payment request, the specific reason can be returned via this field.
returnMessageId	string	No	A random string returned to identify this response. If you encounter an issue and want to request assistance from SHOPLINE for troubleshooting, you can provide this string to help SHOPLINE engineers quickly locate the response.
orderTransactionId	string	Yes	Payment transaction ID, which is the unique identifier of the payment request.
channelOrderTransactionId	string	Yes	The unique identifier for this payment within the payment app.
paymentUrl	string	No	Buyer payment URL. SHOPLINE will guide the buyer to redirect to this URL. For specific usage, refer to Transaction flow.
paymentInstrumentInfo	object	No	Payment instrument information. This field must be returned if the payment request uses the card-on-file payment mode (`userBehavior` = `bindPayment`).
paymentInstrumentInfo.paymentInstrumentId	string	No	Payment instrument information. This field must be returned in the card-on-file payment mode under recurring payment scenarios. For direct debit payments, SHOPLINE will include this payment instrument information in the payment request to process the charge.

Example:

{
  "returnCode": "SUCCESS",
  "returnMessage": "",
  "returnMessageId": "randomUuid()",
  "orderTransactionId": "2407354205016528273910-001",
  "channelOrderTransactionId": "2381238",
  "paymentUrl": "https://...",
  
  "paymentInstrumentInfo": {
      "paymentInstrumentId": "12313123"
    }
}

Get a payment

SHOPLINE will call this API in multiple scenarios to query the latest information of a specific payment.

Request method

HTTP POST

Request headers

When calling this API, SHOPLINE will include the following request headers:

Field	Required	Description
pay-api-version	Yes	The API version that you selected when configuring the payment app extension.
pay-api-idempotency-key	Yes	Idempotency key. Requests with the same idempotency key should be treated as duplicate requests by the payment app.
pay-api-signature	Yes	The signature value of the request body. After receiving the request, the payment app must verify the signature value to ensure it matches. If it does not match, the request should be considered invalid.
pay-api-timestamp	Yes	The timestamp when the request is initiated, in the format of `yyyyMMddHHmmss`.

Example:

pay-api-version: 2.0.0
pay-api-idempotency-key: TESTKEYKEYKEY
pay-api-signature: SIGNSIGNSIGN
pay-api-timestamp: 20250304175916

Request body

When calling this API, SHOPLINE will include the following parameters in the request body:

Field	Required	Description
orderTransactionId	Yes	Payment transaction ID, which is the unique identifier of the payment request. It indicates the specific payment for which SHOPLINE needs to obtain the latest information.

Example:

{
  "orderTransactionId": "test_6d7c098e15ff"
}

Response headers

When responding to SHOPLINE's payment query, the payment app needs to include the following response headers:

Field	Required	Description
pay-api-signature	Yes	The signature value of the response body. After receiving the response, SHOPLINE will verify the signature value to ensure it matches. If it does not match, the response should be considered invalid.

Example:

pay-api-signature: SIGNSIGNSIGN

Response body

When responding to SHOPLINE's payment query, the payment app can include the following response parameters:

Field	Type	Required	Description
returnCode	string	Yes	Response status code. Valid values are: `SUCCESS`: indicates that the call of this API is successful. Any value other than `SUCCESS`: indicates that the payment app has rejected the payment query and will not perform any action on the payment.
returnMessage	string	No	Response description. When `returnCode` is not `SUCCESS`, indicating that the payment app has rejected the payment query, the specific reason can be returned via this field.
returnMessageId	string	No	A random string returned to identify this response. If you encounter an issue and want to request assistance from SHOPLINE for troubleshooting, you can provide this string to help SHOPLINE engineers quickly locate the response.
orderTransactionId	string	Yes	Payment transaction ID, which is the unique identifier of the payment request.
channelOrderTransactionId	string	Yes	The unique identifier for this payment within the payment app.
paymentStatus	string	Yes	The current payment status of this payment.
amount	integer	Yes	Amount, greater than 0. The precision varies according to the currency. For details, refer to Currency precision.
currency	string	Yes	Currency. For details, refer to Currency precision.
failCode	string	No	Failure code. When `paymentStatus` is `FAILED`, this field returns the specific failure code.
failMessage	string	No	Failure description. When `paymentStatus` is `FAILED`, this field returns the specific failure description.
paymentInstrumentInfo	object	No	Payment instrument information. This field must be returned if the payment request uses the card-on-file payment mode (`userBehavior` = `bindPayment`).
paymentInstrumentInfo. paymentInstrumentId	string	No	Payment instrument information. This field must be returned in the card-on-file payment mode under recurring payment scenarios. For direct debit payments, SHOPLINE will include this payment instrument information in the payment request to process the charge.

Example:

{
  "returnCode": "SUCCESS",
  "returnMessage": "",
  "returnMessageId": "randomUuid()",
  "orderTransactionId": "2407354205016528273910-001",
  "channelOrderTransactionId": "2381238",
  "paymentStatus": "FAIL",
  "amount": "286143",
  "currency": "USD",
  "failCode": "PAY_FAIL_CODE",
  "failMessage": "The reason for payment failure.",
  // This field must be returned in the card-on-file payment mode under recurring payment scenarios.
  "paymentInstrumentInfo": {
      "paymentInstrumentId": "12313123"
    }
}

Capture

For payments that use manual capture, when the merchant captures a payment, SHOPLINE will call this API to send a capture request to the payment app.

When SHOPLINE calls this API, if it cannot obtain a response or if the response signature verification fails, it will retry with the same parameters multiple times within 24 hours, until a correctly formatted response is received or the maximum retry limit is reached. The payment app must implement idempotency to handle retries.

Request method

HTTP POST

Request headers

When calling this API, SHOPLINE will include the following request headers:

Field	Required	Description
pay-api-version	Yes	The API version that you selected when configuring the payment app extension.
pay-api-idempotency-key	Yes	Idempotency key. Requests with the same idempotency key should be treated as duplicate requests by the payment app.
pay-api-signature	Yes	The signature value of the request body. After receiving the request, the payment app must verify the signature value to ensure it matches. If it does not match, the request should be considered invalid.
pay-api-timestamp	Yes	The timestamp when the request is initiated, in the format of `yyyyMMddHHmmss`.

Example:

pay-api-version: 2.0.0
pay-api-idempotency-key: TESTKEYKEYKEY
pay-api-signature: SIGNSIGNSIGN
pay-api-timestamp: 20250304175916

Request body

When calling this API, SHOPLINE will include the following parameters in the request body:

Field	Type	Required	Description
orderTransactionId	string	Yes	Payment transaction ID, which is the unique identifier of the payment request.
channelOrderTransactionId	string	Yes	The unique identifier for this payment within the payment app.
referenceOrderId	string	Yes	Order ID. It is recommended to display this ID in the order ID field of your payment app backend (if you have one). The merchant can search for the order on the SHOPLINE Admin > Orders page by using this ID.
orderTransactionCaptureId	string	Yes	The unique identifier generated by SHOPLINE for each capture operation.
amount	integer	Yes	Amount, greater than 0. The precision varies according to the currency. For details, refer to Currency precision.
currency	string	Yes	Currency. For details, refer to Currency precision.

Example:

{
  "channelOrderTransactionId": "2381238",
  "referenceOrderId": "12313",
  "orderTransactionId": "2407354205016528273910-001",
  "orderTransactionCaptureId": "32012312313",
  "amount": 100,
  "currency": "USD"
}

Response headers

When responding to SHOPLINE's capture request, the payment app needs to include the following response headers:

Field	Required	Description
pay-api-signature	Yes	The signature value of the response body. After receiving the response, SHOPLINE will verify the signature value to ensure it matches. If it does not match, the response should be considered invalid.

Example:

pay-api-signature: SIGNSIGNSIGN

Response body

When responding to SHOPLINE's capture request, the payment app can include the following response parameters:

Field	Type	Required	Description
returnCode	string	Yes	Response status code. Valid values are: `SUCCESS`: indicates that the call of this API is successful. SHOPLINE will attempt to synchronize the payment result. Any value other than `SUCCESS`: indicates that the payment app has rejected the capture request.
returnMessage	string	No	Response description. When `returnCode` is not `SUCCESS`, indicating that the payment app has rejected the capture request, the specific reason can be returned via this field.
returnMessageId	string	No	A random string returned to identify this response. If you encounter an issue and want to request assistance from SHOPLINE for troubleshooting, you can provide this string to help SHOPLINE engineers quickly locate the response.
channelOrderTransactionId	string	Yes	The unique identifier for this payment within the payment app.
amount	integer	Yes	Amount, greater than 0. The precision varies according to the currency. For details, refer to Currency precision.
currency	string	Yes	Currency. For details, refer to Currency precision.

Example:

{
  "returnCode": "SUCCESS",
  "returnMessage": "",
  "returnMessageId": "randomUuid()",
  "channelOrderTransactionId": "2381238",
  "amount": "286143",
  "currency": "USD"
}

Void

For payments that use manual capture, when the merchant voids an authorized payment, SHOPLINE will call this API to send a void request to the payment app.

Request method

HTTP POST

Request headers

When calling this API, SHOPLINE will include the following request headers:

Field	Required	Description
pay-api-version	Yes	The API version that you selected when configuring the payment app extension.
pay-api-idempotency-key	Yes	Idempotency key. Requests with the same idempotency key should be treated as duplicate requests by the payment app.
pay-api-signature	Yes	The signature value of the request body. After receiving the request, the payment app must verify the signature value to ensure it matches. If it does not match, the request should be considered invalid.
pay-api-timestamp	Yes	The timestamp when the request is initiated, in the format of `yyyyMMddHHmmss`.

Example:

pay-api-version: 2.0.0
pay-api-idempotency-key: TESTKEYKEYKEY
pay-api-signature: SIGNSIGNSIGN
pay-api-timestamp: 20250304175916

Request body

When calling this API, SHOPLINE will include the following parameters in the request body:

Field	Type	Required	Description
channelOrderTransactionId	string	Yes	Payment transaction ID, which is the unique identifier of the payment request.
orderTransactionId	string	Yes	The unique identifier for this payment within the payment app.
referenceOrderId	string	Yes	Order ID. It is recommended to display this ID in the order ID field of your payment app backend (if you have one). The merchant can search for the order on the SHOPLINE Admin > Orders page by using this ID.
orderTransactionVoidId	string	Yes	The unique identifier generated by SHOPLINE for each void operation.

Example:

{
  "channelOrderTransactionId": "2381238",
  "referenceOrderId": "12313",
  "orderTransactionId": "2407354205016528273910-001",
  "orderTransactionVoidId": "32012312313"
}

Response headers

When responding to SHOPLINE's void request, the payment app needs to include the following response headers:

Field	Required	Description
pay-api-signature	Yes	The signature value of the response body. After receiving the response, SHOPLINE will verify the signature value to ensure it matches. If it does not match, the response should be considered invalid.

Example:

pay-api-signature: SIGNSIGNSIGN

Response body

When responding to SHOPLINE's void request, the payment app can include the following response parameters:

Field	Type	Required	Description
returnCode	string	Yes	Response status code. Valid values are: `SUCCESS`: indicates that the call of this API is successful. SHOPLINE will attempt to synchronize the payment result. Any value other than `SUCCESS`: indicates that the payment app has rejected the void request.
returnMessage	string	No	Response description. When `returnCode` is not `SUCCESS`, indicating that the payment app has rejected the void request, the specific reason can be returned via this field.
returnMessageId	string	No	A random string returned to identify this response. If you encounter an issue and want to request assistance from SHOPLINE for troubleshooting, you can provide this string to help SHOPLINE engineers quickly locate the response.
channelOrderTransactionId	string	Yes	The unique identifier for this payment within the payment app.

Example:

{
  "returnCode": "SUCCESS",
  "returnMessage": "",
  "returnMessageId": "randomUuid()",
  "channelOrderTransactionId": "2381238"
}

Refund

When a merchant initiates a refund, SHOPLINE will call this API to send a refund request to the payment app. For more information about the communication process, refer to Transaction flow.

Request method

HTTP POST

Request headers

When calling this API, SHOPLINE will include the following request headers:

Field	Required	Description
pay-api-version	Yes	The API version that you selected when configuring the payment app extension.
pay-api-idempotency-key	Yes	Idempotency key. Requests with the same idempotency key should be treated as duplicate requests by the payment app.
pay-api-signature	Yes	The signature value of the request body. After receiving the request, the payment app must verify the signature value to ensure it matches. If it does not match, the request should be considered invalid.
pay-api-timestamp	Yes	The timestamp when the request is initiated, in the format of `yyyyMMddHHmmss`.

Example:

pay-api-version: 2.0.0
pay-api-idempotency-key: TESTKEYKEYKEY
pay-api-signature: SIGNSIGNSIGN
pay-api-timestamp: 166563275860600

Request body

When calling this API, SHOPLINE can include the following parameters in the request body:

Field	Type	Required	Description
refundTransactionId	string	Yes	Refund transaction ID, which is the unique identifier of the refund request.
channelOrderTransactionId	string	Yes	The unique identifier of the original payment within the payment app, corresponding to the refund.
amount	integer	Yes	Amount, greater than or equal to 0. The precision varies according to the currency. For details, refer to Currency precision.
currency	string	Yes	Currency. For details, refer to Currency precision.
notifyUrl	string	Yes	URL for receiving asynchronous refund result notifications. When the refund status changes and you want to notify SHOPLINE, you can call the Refund status notification API via this URL. SHOPLINE will assign the `channel_id` and `payment_method` parameters to each payment app. This URL must include these two parameters, as they are required path parameters for the Refund status notification API. Maximum length: 512
reason	string	No	The refund reason provided by the merchant.

Example:

{
  "refundTransactionId": "4323412313123",
  "channelOrderTransactionId": "454234323",
  "amount": 60,
  "currency": "USD",
  "notifyUrl": "https://.../",
  "reason": "return reason"
}

Response headers

When responding to SHOPLINE's refund request, the payment app needs to include the following response headers:

Field	Required	Description
pay-api-signature	Yes	The signature value of the response body. After receiving the response, SHOPLINE will verify the signature value to ensure it matches. If it does not match, the response should be considered invalid.

Example:

pay-api-signature: SIGNSIGNSIGN

Response body

When responding to SHOPLINE's refund request, the payment app can include the following response parameters:

Field	Type	Required	Description
returnCode	string	Yes	Response status code. Valid values are: `SUCCESS`: indicates that the call of this API is successful. SHOPLINE will attempt to synchronize the refund result. Any value other than `SUCCESS`: indicates that the payment app has rejected the refund request. The refund will be marked as failed.
returnMessage	string	No	Response description. When `returnCode` is not `SUCCESS`, indicating that the payment app has rejected the refund request, the specific reason can be returned via this field.
returnMessageId	string	No	A random string returned to identify this response. If you encounter an issue and want to request assistance from SHOPLINE for troubleshooting, you can provide this string to help SHOPLINE engineers quickly locate the response.
refundTransactionId	string	Yes	Refund transaction ID, which is the unique identifier of the refund request.
channelRefundTransactionId	string	Yes	The unique identifier for this refund within the payment app.
channelOrderTransactionId	string	Yes	The unique identifier of the payment, which corresponds to the refund, within the payment app.
amount	integer	Yes	Amount, greater than or equal to 0. The precision varies according to the currency. For details, refer to Currency precision.
currency	string	Yes	Currency. For details, refer to Currency precision.
refundStatus	string	Yes	The current refund status.

Example:

{
  "returnCode": "SUCCESS",
  "returnMessage": "",
  "returnMessageId": "randomUuid()",
  "refundTransactionId": "4324234",
  "channelRefundTransactionId": "54334342",
  "channelOrderTransactionId": "23423432",
  "amount": 100,
  "currency": "USD",
  "refundStatus": "FAIL"
}

Get a refund

SHOPLINE will call this API in multiple scenarios to query the latest information of a specific refund.

Request method

HTTP POST

Request headers

When calling this API, SHOPLINE will include the following request headers:

Field	Required	Description
pay-api-version	Yes	The API version that you selected when configuring the payment app extension.
pay-api-idempotency-key	Yes	Idempotency key. Requests with the same idempotency key should be treated as duplicate requests by the payment app.
pay-api-signature	Yes	The signature value of the request body. After receiving the request, the payment app must verify the signature value to ensure it matches. If it does not match, the request should be considered invalid.
pay-api-timestamp	Yes	The timestamp when the request is initiated, in the format of `yyyyMMddHHmmss`.

Example:

pay-api-version: 2.0.0
pay-api-idempotency-key: TESTKEYKEYKEY
pay-api-signature: SIGNSIGNSIGN
pay-api-timestamp: 20250304175916

Request body

When calling this API, SHOPLINE will include the following parameters in the request body:

Field	Required	Description
refundTransactionId	Yes	Refund transaction ID, which is the unique identifier of the refund request. It indicates the specific refund for which SHOPLINE needs to obtain the latest information.

Example:

{
  "refundTransactionId": "43212312432"
}

Response headers

When responding to SHOPLINE's refund query, the payment app needs to include the following response headers:

Field	Required	Description
pay-api-signature	Yes	The signature value of the response body. After receiving the response, SHOPLINE will verify the signature value to ensure it matches. If it does not match, the response should be considered invalid.

Example:

pay-api-signature: SIGNSIGNSIGN

Response body

When responding to SHOPLINE's refund query, the payment app can include the following response parameters:

Field	Type	Required	Description
returnCode	string	Yes	Response status code. Valid values are: `SUCCESS`: indicates that the call of this API is successful. Any value other than `SUCCESS`: indicates that the payment app has rejected the refund query and will not perform any action on the refund.
returnMessage	string	No	Response description. When `returnCode` is not `SUCCESS`, indicating that the payment app has rejected the refund query, the specific reason can be returned via this field.
returnMessageId	string	No	A random string returned to identify this response. If you encounter an issue and want to request assistance from SHOPLINE for troubleshooting, you can provide this string to help SHOPLINE engineers quickly locate the response.
refundTransactionId	string	Yes	Refund transaction ID.
channelRefundTransactionId	string	Yes	The unique identifier for this refund within the payment app.
channelOrderTransactionId	string	Yes	The unique identifier of the payment, which corresponds to the refund, within the payment app.
amount	integer	Yes	Amount, greater than or equal to 0. The precision varies according to the currency. For details, refer to Currency precision.
currency	string	Yes	Currency. For details, refer to Currency precision.
refundStatus	string	Yes	The current refund status.
failCode	string	No	Failure code. When `refundStatus` is `FAILED`, this field returns the specific failure code.
failMessage	string	No	Failure description. When `refundStatus` is `FAILED`, this field returns the specific failure description.

Example:

{
  "returnCode": "SUCCESS",
  "returnMessage": "",
  "returnMessageId": "randomUuid()",
  "refundTransactionId": "4324234",
  "channelRefundTransactionId": "54334342",
  "channelOrderTransactionId": "23423432",
  "amount": 100,
  "currency": "USD",
  "refundStatus": "FAIL",
  "failCode": "REFUND_FAIL_CODE",
  "failMessage": "The reason for refund failure."
}

Report shipment tracking

When a merchant ships an order, SHOPLINE will call this API to synchronize the order's shipment information with the payment app.

For the same tracking number, SHOPLINE may report shipment information multiple times due to status updates. The payment app should correctly handle these reporting requests.

Request method

HTTP POST

Request headers

When calling this API, SHOPLINE will include the following request headers:

Field	Required	Description
pay-api-version	Yes	The API version that you selected when configuring the payment app extension.
pay-api-idempotency-key	Yes	Idempotency key. Requests with the same idempotency key should be treated as duplicate requests by the payment app.
pay-api-signature	Yes	The signature value of the request body. After receiving the request, the payment app must verify the signature value to ensure it matches. If it does not match, the request should be considered invalid.
pay-api-timestamp	Yes	The timestamp when the request is initiated, in the format of `yyyyMMddHHmmss`.

Example:

pay-api-version: 2.0.0
pay-api-idempotency-key: TESTKEYKEYKEY
pay-api-signature: SIGNSIGNSIGN
pay-api-timestamp: 20250304175916

Request body

When calling this API, SHOPLINE can include the following parameters in the request body:

Field	Type	Required	Description
channelOrderTransactionId	string	Yes	The unique identifier of the payment, to which the shipment information belongs, within the payment app.
trackingList	object[]	Yes	A list of shipment information.
trackingList.trackingNo	string	Yes	Tracking number.
trackingList.site	string	Yes	Shipment tracking website. You can use the tracking number to query the relevant shipment information on this website.
trackingList.trackingStatus	string	Yes	Shipping status. The current fixed value is `03`, meaning 'Shipped'. SHOPLINE will synchronize shipment information to the payment app when the merchant ships the order. If the payment app requires the latest shipment information, check it using the `trackingNo` and `site` parameters on the official website of the specific carrier.
trackingList.handler	string	No	The name of the store reporting the shipment information.
trackingList.carrier	string	Yes	Shipping carrier.

Example:

{
  "channelOrderTransactionId": "123124",
  "trackingList": [
    {
      "trackingNo": "234234",
      "site": "https://...",
      "handler": "storeHandler",
      "trackingStatus": "03",
      "carrier": "stardard carrier"
    }
  ]
}

Response headers

When responding to SHOPLINE's shipment information reporting request, the payment app needs to include the following response headers:

Field	Required	Description
pay-api-signature	Yes	The signature value of the response body. After receiving the response, SHOPLINE will verify the signature value to ensure it matches. If it does not match, the response should be considered invalid.

Example:

pay-api-signature: SIGNSIGNSIGN

Response body

When responding to SHOPLINE's shipment information reporting request, the payment app can include the following response parameters:

Field	Type	Required	Description
returnCode	string	Yes	Response status code. Valid values are: `SUCCESS`: indicates that the call of this API is successful. Any value other than `SUCCESS`: indicates that SHOPLINE will not perform any action on the order.
returnMessage	string	No	Response description. When `returnCode` is not `SUCCESS`, indicating that the payment app has rejected the shipment information reporting request, the specific reason can be returned via this field.
returnMessageId	string	No	A random string returned to identify this response. If you encounter an issue and want to request assistance from SHOPLINE for troubleshooting, you can provide this string to help SHOPLINE engineers quickly locate the response.

Example:

{
  "returnCode": "SUCCESS",
  "returnMessage": "",
  "returnMessageId": "randomUuid()"
}

Get digital wallet configuration

When rendering Apple Pay or Google Pay payment buttons, SHOPLINE calls this API to retrieve the store's configuration details for these digital wallets.

Request method

HTTP POST

Request headers

When calling this API, SHOPLINE will include the following request headers:

Field	Required	Description
pay-api-version	Yes	The API version that you selected when configuring the payment app extension.
pay-api-idempotency-key	Yes	Idempotency key. Requests with the same idempotency key should be treated as duplicate requests by the payment app.
pay-api-signature	Yes	The signature value of the request body. After receiving the request, the payment app must verify the signature value to ensure it matches. If it does not match, the request should be considered invalid.
pay-api-timestamp	Yes	The timestamp when the request is initiated, in the format of `yyyyMMddHHmmss`.
pay-api-store-handle	Yes	The handle of the store initiating the payment, which is a unique identifier.

Example:

pay-api-version: 2.0.0
pay-api-idempotency-key: TESTKEYKEYKEY
pay-api-signature: SIGNSIGNSIGN
pay-api-timestamp: 20250304175916
pay-api-store-handle: HANDLE01

Request body

None

Response headers

When responding to SHOPLINE's wallet configuration query, the payment app needs to include the following response headers:

Field	Required	Description
pay-api-signature	Yes	The signature value of the response body. After receiving the response, SHOPLINE will verify the signature value to ensure it matches. If it does not match, the response should be considered invalid.

Example:

pay-api-signature: SIGNSIGNSIGN

Response body

When responding to SHOPLINE's wallet configuration query, the payment app can include the following response parameters:

Field	Type	Required	Description
returnCode	string	Yes	Response status code. Valid values are: `SUCCESS`: Indicates that the call of this API is successful. Any value other than `SUCCESS`: Indicates that the payment app has rejected the wallet configuration query.
returnMessage	string	No	Response description. When `returnCode` is not `SUCCESS`, indicating that the payment app has rejected the wallet configuration query, the specific reason can be returned via this field.
returnMessageId	string	No	A random string returned to identify this response. If you encounter an issue and want to request assistance from SHOPLINE for troubleshooting, you can provide this string to help SHOPLINE engineers quickly locate the response.
paymentMethod	string	Yes	Digital wallet payment method. Valid values are: `ApplePay`: Apple Pay `GooglePay`: Google Pay
channelConfigData	string	Yes	Payment channel configuration as a JSON string. The structure depends on the `paymentMethod`.

Payment channel configuration

The structure of channelConfigData varies based on the value of paymentMethod.

Apple Pay:

When paymentMethod is ApplePay, the structure of channelConfigData is as follows:

Field	Type	Required	Description
merchantCapabilities	string[]	Yes	Merchant payment capabilities. Valid values are: `supports3DS`: Always returned. `supportsCredit`: Returned if credit cards are supported. `supportsDebit`: Returned if debit cards are supported. `supportsEMV`: Returned if China UnionPay is supported. If neither `supportsCredit` nor `supportsDebit` is returned, both credit cards and debit cards are supported by default.
supportedNetworks	string[]	Yes	Supported card networks, such as `amex` and `visa`.

Google Pay:

When paymentMethod is GooglePay, the structure of channelConfigData is as follows:

Field	Type	Required	Description
type	string	Yes	Payment method type. Only `CARD` is supported, representing card payments.
parameters	object	Yes	Configuration parameters for the payment method type.
parameters.allowedAuthMethods	string[]	Yes	Supported payment authentication methods. Valid values are: `PAN_ONLY`: PAN-based authentication. This method uses cards on file stored in the Google Account and returns a payload containing the PAN and the expiration date. `CRYPTOGRAM_3DS`: 3DS cryptogram authentication. This method uses tokenized cards stored on Android devices and returns a payload containing a 3DS cryptogram.
parameters.allowedCardNetworks	string[]	Yes	Supported card networks, such as `AMEX` and `VISA`.
tokenizationSpecification	object	Yes	Tokenization configuration information.
tokenizationSpecification.type	string	Yes	Tokenization type. Valid values are: `PAYMENT_GATEWAY`: Payment gateway `DIRECT`: Direct
tokenizationSpecification.parameters	object	Yes	Configuration parameters for the tokenization type.
tokenizationSpecification.parameters.gateway	string	No	Payment gateway. Returned if `tokenizationSpecification.type` is `PAYMENT_GATEWAY`.
tokenizationSpecification.parameters.gatewayMerchantId	string	No	Account ID of the payment gateway. Returned if `tokenizationSpecification.type` is `PAYMENT_GATEWAY`.
tokenizationSpecification.parameters.protocolVersion	string	No	Encryption protocol version. Returned if `tokenizationSpecification.type` is `DIRECT`.
tokenizationSpecification.parameters.publicKey	string	No	Encryption public key. Returned if `tokenizationSpecification.type` is `DIRECT`.

Was this article helpful to you?

SHOPLINE

Legal

API reference​

Pay​

Request method​

Request headers​

Request body​

Response headers​

Response body​

Get a payment​

Request method​

Request headers​

Request body​

Response headers​

Response body​

Capture​

Request method​

Request headers​

Request body​

Response headers​

Response body​

Void​

Request method​

Request headers​

Request body​

Response headers​

Response body​

Refund​

Request method​

Request headers​

Request body​

Response headers​

Response body​

Get a refund​

Request method​

Request headers​

Request body​

Response headers​

Response body​

Report shipment tracking​

Request method​

Request headers​

Request body​

Response headers​

Response body​

Get digital wallet configuration​

Request method​

Request headers​

Request body​

Response headers​

Response body​

Payment channel configuration​

API reference

Pay

Request method

Request headers

Request body

Response headers

Response body

Get a payment

Request method

Request headers

Request body

Response headers

Response body

Capture

Request method

Request headers

Request body

Response headers

Response body

Void

Request method

Request headers

Request body

Response headers

Response body

Refund

Request method

Request headers

Request body

Response headers

Response body

Get a refund

Request method

Request headers

Request body

Response headers

Response body

Report shipment tracking

Request method

Request headers

Request body

Response headers

Response body

Get digital wallet configuration

Request method

Request headers

Request body

Response headers

Response body

Payment channel configuration