接口文档​

本文详细介绍了支付应用相关接口的信息。

付款​

当买家完成订单，触发付款请求时，SHOPLINE 将向支付应用发起付款接口调用（具体的工作流程）。

请求方式​

使用 HTTP POST 请求。

请求头​

SHOPLINE 请求付款接口时，会携带以下请求头：

字段是否必填含义
pay-api-version是配置支付应用拓展时选择的 API 版本。
pay-api-idempotency-key是幂等 Key。幂等 Key 相同的请求，支付应用应该视为重复请求。
pay-api-signature是请求体的签名值。支付应用在接收请求后，需要 校验签名值 是否匹配；若不匹配则应视为请求非法。
pay-api-timestamp是请求发起的时间，格式为 yyyyMMddHHmmss。
pay-api-store-handle是发起付款的店铺的 handle，即店铺唯一标识。

示例：

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

请求体​

SHOPLINE 在请求付款接口时，将在请求体携带以下参数：

字段类型是否必填含义
orderTransactionIdstring是支付交易流水号，付款请求唯一标识。
referenceOrderIdstring是业务订单号。建议将这个单号展示在支付应用后台（如果你有）的业务单号字段。商家能通过这个单号，在 SHOPLINE 商家后台 > 订单列表 搜索到该订单。
kindstring是支付类型。有效枚举值包含：
  • Sale：代表销售类型。此类订单需要在买家授权后，支付应用方自动进行 Capture。
  • Authorization：代表授权类型。此类订单在买家授权后，支付应用方不应自动进行 Capture；具体逻辑请查看 手动入账模式。
amountinteger是交易金额，大于 0。传递的精度根据币种会有不同，具体请查看 币种精度。
currencystring是交易金额币种，具体请查看 币种精度。
redirectUrlstring是完成支付 URL。买家完成支付后，支付应用需要将买家重定向到该 URL 指向的 SHOPLINE 页面。
最大长度限制：512
cancelUrlstring是取消支付 URL。买家取消支付时，支付应用需要将买家重定向到该 URL 指向的 SHOPLINE 页面。
最大长度限制：512
notifyUrlstring是异步结果的通知 URL。当支付状态变更，需要通知 SHOPLINE 时，你可以调用 支付状态通知接口；SHOPLINE 将为每个支付应用分配 channel_id 和 payment_method，这两个参数也是 支付状态通知接口 的必要路径参数，而此 URL 直接包含了这两个参数。
最大长度限制：512
billingobject否账单信息，买家在结算页填写的账单信息。
billing.personalInfoobject是买家填写的账单个人信息。
billing.firstNamestring否名字。
billing.lastNamestring是姓氏。
billing.emailstring否邮箱地址。
billing.identityTypestring否身份证件类型。
billing.identityNumberstring否身份证件号码。
billing.genderstring否性别。
billing.phoneNumberstring否电话号码。
billing.homeTelephonestring否家庭电话号码。
billing.birthDaystring否生日，格式为 YYYY-MM-DD。
billing.addressobject是买家填写的账单地址信息。
billing.countryCodestring是国家或地区编码。
billing.statestring否州或省。
billing.stateCodestring否州或省编码。
billing.citystring否城市。
billing.districtstring否区域。
billing.streetstring否街道（主要街道地址，包含完整的街道名和门牌号）。
billing.street2string否街道 2（补充信息，如单元号、楼层等）。
billing.street3string否街道 3（额外备注，如附近地标、特别说明等）。
billing.postcodestring否邮政编码。
shippingobject否物流信息。
shipping.personalInfoobject是物流地址填写的个人信息。
shipping.firstNamestring否名字。
shipping.lastNamestring是姓氏。
shipping.emailstring否邮箱地址。
shipping.identityTypestring否身份证件类型。
shipping.identityNumberstring否身份证件号码。
shipping.genderstring否性别。
shipping.phoneNumberstring否电话号码。
shipping.homeTelephonestring否家庭电话号码。
shipping.birthDaystring否生日，格式为 YYYY-MM-DD。
shipping.addressobject是地址信息。
shipping.countryCodestring是国家或地区编码。
shipping.statestring否州或省。
shipping.stateCodestring否州或省编码。
shipping.citystring否城市。
shipping.districtstring否区域。
shipping.streetstring否街道（主要街道地址，包含完整的街道名和门牌号）。
shipping.street2string否街道 2（补充信息，如单元号、楼层等）。
shipping.street3string否街道 3（额外备注，如附近地标、特别说明等）。
shipping.postcodestring否邮政编码。
shipping.shippingMethodstring是物流方式。
shipping.carrierstring否物流承运商，如 FedEx。
productsobject[]是买家购买的商品列表。
products.idstring是商品编号。
products.namestring是商品名称。
products.skustring否货号。
products.descstring否描述。
products.quantityinteger是商品数量，大于 0。
products.unitPriceobject是单价，大于等于 0。传递的精度根据币种会有不同，具体请查看 币种精度。
products.valueinteger是金额，大于等于 0。传递的精度根据币种会有不同，具体请查看 币种精度。
products.currencystring是币种。具体请查看 币种精度。
amountBreakdownobject是本次支付的金额明细。
amountBreakdown.productAmountinteger是商品总金额，大于等于 0。传递的精度根据币种会有不同，具体请查看 币种精度。
amountBreakdown.discountinteger是总折扣，大于等于 0。传递的精度根据币种会有不同，具体请查看 币种精度。
amountBreakdown.productTaxinteger是商品总税费，大于等于 0。传递的精度根据币种会有不同，具体请查看 币种精度。
amountBreakdown.shippingAmountinteger是总运费，大于等于 0。传递的精度根据币种会有不同，具体请查看 币种精度。
amountBreakdown.shippingTaxinteger是总运费税费，大于等于 0。传递的精度根据币种会有不同，具体请查看 币种精度。
amountBreakdown.otherinteger是其它费用总和，大于 0 代表是费用项，小于 0 代表是抵扣项。传递的精度根据币种会有不同，具体请查看 币种精度。
merchantobject是商户信息。
merchant.storeWebsitestring是店铺网站域名。
cardobject否信用卡信息，将在 直连 模式下传递。
card.cardNostring是明文卡号。
card.expirationMonthstring是有效期月份，取值范围为 1-12。
card.expirationYearstring是有效期年份，取值范围为 00-99。例如，取值为 25 表示 2025 年。
card.cvvstring是卡片 CVV 验证码。
card.holderNamestring否持卡人姓名。
clientobject否买家发起支付时的客户端信息，将在 直连 模式下传递。
client.ipstring是客户端 IP。
client.deviceTypestring否设备类型。
client.deviceIdstring否设备 ID。
client.javaScriptEnabledboolean否浏览器是否支持 JavaScript。
  • true：支持
  • false：不支持
client.javaEnabledboolean否浏览器是否支持 Java。
  • true：支持
  • false：不支持
client.colorDepthstring否浏览器显示器色深。
client.screenHeightstring否持卡人浏览器分辨率高度。
client.screenWidthstring否持卡人浏览器分辨率宽度。
client.timeZoneOffsetstring否浏览器本地时区偏移量。
client.userAgentstring否浏览器 User-Agent。
client.languagestring否浏览器语言。
client.transactionWebSitestring否交易网址，即发起支付的当前网址。
client.acceptstring否浏览器接受报文类型。
paymentOptionsobject否支付选项，目前用于周期性付款场景。
paymentOptions.recurringPaymentbool否是否是周期性付款场景。
  • true：周期性付款场景
  • false：非周期性付款场景
paymentOptions.userBehaviorstring否支付模式，目前用于周期性付款场景。有效枚举值包含：
  • bindPayment：表示当前支付请求为绑卡支付模式，支付应用需返回支付工具信息。
  • Recurring：表示当前支付请求为代扣模式。
paymentOptions.paymentInstrumentIdstring否支付工具信息。周期性付款场景的代扣模式下（userBehavior = Recurring）有值，此时支付应用需通过该支付工具信息处理代扣支付请求。
paymentMethodInstrumentstring否数字钱包返回的支付工具信息。在 Apple Pay 或 Google Pay 支付模式下必填，支付应用需将该信息传递给支付渠道以完成扣款。

示例：

{
  {
  "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",
    // userBehavior = Recurring 时必须提供，从绑卡支付响应信息中获得
    "paymentInstrumentId":"{channelPaymentInstrumentId}"
  },
  // 数字钱包返回的支付工具信息
  "paymentMethodInstrument": "{...}"
}
}

响应头​

支付应用响应 SHOPLINE 的付款请求时，需要携带以下响应头：

字段是否必填含义
pay-api-signature是响应体的签名值。SHOPLINE 在收到响应后，将 校验签名值 是否匹配；若不匹配则应视为响应非法。

示例：

pay-api-signature: SIGNSIGNSIGN

响应体​

支付应用响应 SHOPLINE 的付款请求时，需要返回以下信息：

字段类型是否必填含义
returnCodestring是接口响应状态码。有效枚举值包含：
  • SUCCESS：SHOPLINE 认为此次付款接口调用成功，接下来将会尝试 同步付款结果。
  • 非 SUCCESS：SHOPLINE 将认为支付应用不接受此次付款请求，本次支付的状态将会被置为支付失败。
returnMessagestring否响应描述。当 returnCode 返回非 SUCCESS 时，代表支付应用不接受此次付款请求，此时可在该字段返回具体的原因。
returnMessageIdstring否返回的一个随机串，用来标识这次响应。
在后续报告问题需要 SHOPLINE 协助排查时，你可以提供这个随机串，以便 SHOPLINE 工程师更快的定位到该响应。
orderTransactionIdstring是支付交易流水号，付款请求唯一标识。
channelOrderTransactionIdstring是这笔支付在支付应用的唯一标识。
paymentUrlstring否买家付款 URL。SHOPLINE 将引导买家重定向到该地址，具体使用方式参考 交易流程。
paymentInstrumentInfoobject否支付工具信息。如果当前支付单是绑卡支付模式（支付请求中的 userBehavior = bindPayment），需要返回该字段。
paymentInstrumentInfo.paymentInstrumentIdstring否支付工具信息。周期性付款场景的绑卡支付模式下，必须返回该字段；代扣支付时，SHOPLINE 将在支付请求中携带该支付工具信息进行扣款支付。

示例：

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

付款查询​

SHOPLINE 将在 多个场景 调用付款查询接口，查询某笔支付的最新信息。

请求方式​

使用 HTTP POST 请求。

请求头​

SHOPLINE 请求付款查询接口时，会携带以下请求头：

字段是否必填含义
pay-api-version是配置支付应用拓展时选择的 API 版本。
pay-api-idempotency-key是幂等 Key。幂等 Key 相同的请求，支付应用应该视为重复请求。
pay-api-signature是请求体的签名值。支付应用在接收请求后，需要 校验签名值 是否匹配；若不匹配则应视为请求非法。
pay-api-timestamp是请求发起的时间，格式为 yyyyMMddHHmmss。

示例：

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

请求体​

SHOPLINE 在请求付款查询接口时，将在请求体携带以下参数：

字段是否必填含义
orderTransactionId是支付交易流水号，付款请求唯一标识；代表 SHOPLINE 需要获取该笔支付的最新信息。

示例：

{
  "orderTransactionId": "2407354205016528273910-001"
}

响应头​

支付应用响应 SHOPLINE 的付款查询请求时，需要携带以下响应头：

字段是否必填含义
pay-api-signature是响应体的签名值。SHOPLINE 在收到响应后，将 校验签名值 是否匹配；若不匹配则应视为响应非法。

示例：

pay-api-signature: SIGNSIGNSIGN

响应体​

支付应用响应 SHOPLINE 的付款查询请求时，需要返回以下信息：

字段类型是否必填含义
returnCodestring是接口响应状态码。有效枚举值包含：
  • SUCCESS：SHOPLINE 认为此次付款查询接口调用成功。
  • 非 SUCCESS：SHOPLINE 将认为支付应用不接受此次付款查询请求，因此不会对支付单进行任何处理。
returnMessagestring否响应描述。当 returnCode 返回非 SUCCESS 时，代表支付应用不接受此次付款查询请求，此时可在该字段返回具体的原因。
returnMessageIdstring否返回的一个随机串，用来标识这次响应。
在后续报告问题需要 SHOPLINE 协助排查时，你可以提供这个随机串，以便 SHOPLINE 工程师更快地定位到该响应。
orderTransactionIdstring是支付交易流水号，付款请求唯一标识。
channelOrderTransactionIdstring是这笔支付在支付应用的唯一标识。
paymentStatusstring是此笔支付单当前的 支付状态。
amountinteger是金额，大于 0。传递的精度根据币种会有不同，具体请查看 币种精度。
currencystring是交易金额币种，具体请查看 币种精度。
failCodestring否失败编码。当 paymentStatus 返回 FAILED 时，通过此字段返回具体的失败编码。
failMessagestring否失败描述。当 paymentStatus 返回 FAILED 时，通过此字段返回具体的失败描述。
paymentInstrumentInfoobject否支付工具信息。如果当前支付单是绑卡支付模式（支付请求中的 userBehavior = bindPayment），需要返回该字段。
paymentInstrumentInfo.paymentInstrumentIdstring否支付工具信息。周期性付款场景的绑卡支付模式下，必须返回该字段；代扣支付时，SHOPLINE 将在支付请求中携带该支付工具信息进行扣款支付。

示例：

{
  "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.",
  // 在周期性付款场景的绑卡支付模式下，需要携带该字段
  "paymentInstrumentInfo": {
      "paymentInstrumentId": "12313123"
    }
}

Capture​

对于 手动入账 的支付单，当商家操作入账时，SHOPLINE 将向支付应用配置的 Capture URL 发起 Capture 接口调用。

调用该接口时，如果 SHOPLINE 无法获取到响应或者响应验签失败，将在 24 小时内以同样的参数重试多次，直到返回格式正确或超过最大重试次数。需要做好幂等处理。

请求方式​

使用 HTTP POST 请求。

请求头​

SHOPLINE 请求 Capture 接口时，会携带以下请求头：

字段是否必填含义
pay-api-version是配置支付应用拓展时选择的 API 版本。
pay-api-idempotency-key是幂等 Key，幂等 Key 相同的请求，支付应用应该视为重复请求。
pay-api-signature是请求体的签名值。支付应用在接收请求后，需要校验签名值是否匹配；若不匹配则应视为请求非法。
pay-api-timestamp是请求发起的时间，格式为 yyyyMMddHHmmss。

示例：

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

请求体​

SHOPLINE 在请求 Capture 接口时，将在请求体携带以下参数：

字段类型是否必填含义
orderTransactionIdstring是支付交易流水号，付款请求唯一标识。
channelOrderTransactionIdstring是这笔支付在支付应用的唯一标识。
referenceOrderIdstring是业务订单号。建议将这个单号展示在支付应用后台（如果你有）的业务单号字段。商家能通过这个单号，在 SHOPLINE 商家后台 > 订单列表 搜索到该订单。
orderTransactionCaptureIdstring是SHOPLINE 为每次 Capture 操作生成的唯一标识。
amountinteger是金额，大于 0。传递的精度根据币种会有不同，具体请查看 币种精度。
currencystring是交易金额币种，具体请查看 币种精度。

示例：

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

响应头​

支付应用响应 SHOPLINE 的 Capture 请求时，需要携带以下响应头：

字段是否必填含义
pay-api-signature是响应体的签名值。SHOPLINE 在收到响应后，将 校验签名值 是否匹配；若不匹配则应视为响应非法。

示例：

pay-api-signature: SIGNSIGNSIGN

响应体​

支付应用响应 SHOPLINE 的 Capture 请求时，需要返回以下信息：

字段类型是否必填含义
returnCodestring是接口响应状态码。有效枚举值包含：
• SUCCESS：SHOPLINE 认为此次 Capture 接口调用成功，接下来将尝试 同步付款结果。
• 非 SUCCESS：SHOPLINE 认为支付应用不接受此次 Capture 请求。
returnMessagestring否响应描述。当 returnCode 返回非 SUCCESS 时，代表支付应用不接受此次 Capture 请求，此时可在该字段返回具体的原因。
returnMessageIdstring否返回的一个随机串，用来标识这次响应。
在后续报告问题需要 SHOPLINE 协助排查时，你可以提供这个随机串，以便 SHOPLINE 工程师更快的定位到该响应。
channelOrderTransactionIdstring是这笔支付在支付应用的唯一标识。
amountinteger是金额，大于 0。传递的精度根据币种会有不同，具体请查看 币种精度。
currencystring是交易金额币种，具体请查看 币种精度。

示例：

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

Void​

对于 手动入账 的支付单，当商家取消入账时，SHOPLINE 将向支付应用发起 Void 接口调用。
调用该接口时，如果 SHOPLINE 无法获取到响应或者响应验签失败，将在 24 小时内以同样的参数重试多次，直到返回格式正确或超过最大重试次数。需要做好幂等处理。

请求方式​

使用 HTTP POST 请求。

请求头​

SHOPLINE 请求 Void 接口时，会携带以下请求头：

字段是否必填含义
pay-api-version是配置支付应用拓展时选择的 API 版本。
pay-api-idempotency-key是幂等 Key。幂等 Key 相同的请求，支付应用应该视为重复请求。
pay-api-signature是请求体的签名值。支付应用在接收请求后，需要 校验签名值 是否匹配；若不匹配则应视为请求非法。
pay-api-timestamp是请求发起的时间，格式为 yyyyMMddHHmmss。

示例：

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

请求体​

SHOPLINE 在请求 Void 接口时，将在请求体携带以下参数：

字段类型是否必填含义
channelOrderTransactionIdstring是支付交易流水号，付款请求唯一标识。
orderTransactionIdstring是这笔支付在支付应用的唯一标识。
referenceOrderIdstring是业务订单号。建议将这个单号展示在支付应用后台（如果你有）的业务单号字段。商家能通过这个单号，在 SHOPLINE 商家后台 > 订单列表 搜索到该订单。
orderTransactionVoidIdstring是SHOPLINE 为每次 Void 操作生成的唯一标识。

示例：

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

响应头​

支付应用响应 SHOPLINE 的 Void 请求时，需要携带以下响应头：

字段是否必填含义
pay-api-signature是响应体的签名值。SHOPLINE 在收到响应后，将 校验签名值 是否匹配；若不匹配则应视为响应非法。

示例：

pay-api-signature: SIGNSIGNSIGN

响应体​

支付应用响应 SHOPLINE 的 Void 请求时，需要返回以下信息：

字段类型是否必填含义
returnCodestring是接口响应状态码。有效枚举值包含：
• SUCCESS：SHOPLINE 认为此次 Void 接口调用成功，接下来将尝试 同步付款结果。
• 非 SUCCESS：SHOPLINE 认为支付应用不接受此次 Void 请求。
returnMessagestring否响应描述。当 returnCode 返回非 SUCCESS 时，代表支付应用不接受此次 Void 请求，此时可在该字段返回具体的原因。
returnMessageIdstring否返回的一个随机串，用来标识这次响应。
在后续报告问题需要 SHOPLINE 协助排查时，你可以提供这个随机串，以便 SHOPLINE 工程师更快的定位到该响应。
channelOrderTransactionIdstring是这笔支付在支付应用的唯一标识。

示例：

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

退款​

当商家发起退款，触发退款请求时，SHOPLINE 将向支付应用发起退款接口调用（具体的工作流程）。
调用该接口时，如果 SHOPLINE 无法获取到响应或者响应验签失败，将在 24 小时内以同样的参数重试多次，直到返回格式正确或超过最大重试次数。需要做好幂等处理。

请求方式​

使用 HTTP POST 请求。

请求头​

SHOPLINE 请求退款接口时，会携带以下请求头：

字段是否必填含义
pay-api-version是配置支付应用拓展时选择的 API 版本。
pay-api-idempotency-key是幂等 Key。幂等 Key 相同的请求，支付应用应该视为重复请求。
pay-api-signature是请求体的签名值。支付应用在接收请求后，需要 校验签名值 是否匹配；若不匹配则应视为请求非法。
pay-api-timestamp是请求发起的时间，格式为 yyyyMMddHHmmss。

示例：

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

请求体​

SHOPLINE 在请求退款接口时，将在请求体携带以下参数：

字段类型是否必填含义
refundTransactionIdstring是退款流水号，该次退款的唯一标识。
channelOrderTransactionIdstring是发起此次退款的正向支付单在支付应用的唯一标识。
amountinteger是金额，大于等于 0。传递的精度根据币种会有不同，具体请查看 币种精度。
currencystring是币种，具体请查看 币种精度。
notifyUrlstring是异步结果的通知 URL。当退款状态变更，需要通知 SHOPLINE 时，你可以调用 退款状态通知接口；SHOPLINE 将为每个支付应用分配 channel_id 和 payment_method，这两个参数也是 退款状态通知接口 的必要路径参数，而此 URL 直接包含了这两个参数。
最大长度限制：512
reasonstring否商家在申请退款时，填写的退款原因。

示例：

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

响应头​

支付应用响应 SHOPLINE 的退款请求时，需要携带以下响应头：

字段是否必填含义
pay-api-signature是响应体的签名值。SHOPLINE 在收到响应后，将 校验签名值 是否匹配；若不匹配则应视为响应非法。

示例：

pay-api-signature: SIGNSIGNSIGN

响应体​

支付应用响应 SHOPLINE 的退款请求时，需要返回以下信息：

字段类型是否必填含义
returnCodestring是接口响应状态码。有效枚举值包含：
  • SUCCESS：SHOPLINE 认为此次退款接口调用成功，接下来将尝试 同步退款结果。
  • 非 SUCCESS：SHOPLINE 将认为支付应用不接受此次退款请求，因此会直接标记该退款单为失败。
returnMessagestring否响应描述。当 returnCode 返回非 SUCCESS 时，代表支付应用不接受此次退款请求，此时可在该字段返回具体的原因。
returnMessageIdstring否返回的一个随机串，用来标识这次响应。
在后续报告问题需要 SHOPLINE 协助排查时，你可以提供这个随机串，以便 SHOPLINE 工程师更快地定位到该响应。
refundTransactionIdstring是退款流水号，退款请求的唯一标识。
channelRefundTransactionIdstring是这笔退款在支付应用的唯一标识。
channelOrderTransactionIdstring是这笔退款关联的支付单，在支付应用的唯一标识。
amountinteger是金额，大于等于 0。传递的精度根据币种会有不同，具体请查看 币种精度。
currencystring是币种，具体请查看 币种精度。
refundStatusstring是此笔退款单当前的 退款状态。

示例：

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

退款查询​

SHOPLINE 将在 多个场景 调用退款查询接口，查询某笔退款的最新信息。

请求方式​

使用 HTTP POST 请求。

请求头​

SHOPLINE 请求退款查询接口时，会携带以下请求头：

字段是否必填含义
pay-api-version是配置支付应用拓展时选择的 API 版本。
pay-api-idempotency-key是幂等 Key。幂等 Key 相同的请求，支付应用应该视为重复请求。
pay-api-signature是请求体的签名值。支付应用在接收请求后，需要 校验签名值 是否匹配；若不匹配则应视为请求非法。
pay-api-timestamp是请求发起的时间，格式为 yyyyMMddHHmmss。

示例：

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

请求体​

SHOPLINE 在请求退款查询接口时，将在请求体携带以下参数：

字段是否必填含义
refundTransactionId是退款流水号，退款请求唯一标识。代表 SHOPLINE 需要获取该笔退款的最新信息。

示例：

{
  "refundTransactionId": "43212312432"
}

响应头​

支付应用响应 SHOPLINE 的退款查询请求时，需要携带以下响应头：

字段是否必填含义
pay-api-signature是响应体的签名值。SHOPLINE 在收到响应后，将 校验签名值 是否匹配；若不匹配则应视为响应非法。

示例：

pay-api-signature: SIGNSIGNSIGN

响应体​

支付应用响应 SHOPLINE 的退款查询请求时，需要返回以下信息：

字段类型是否必填含义
returnCodestring是接口响应状态码。有效枚举值包含：
• SUCCESS：SHOPLINE 认为此次退款查询接口调用成功。
• 非 SUCCESS：SHOPLINE 将认为支付应用不接受此次退款查询请求，因此不会对退款单进行任何处理。
returnMessagestring否响应描述。当 returnCode 返回非 SUCCESS 时，代表支付应用不接受此次退款查询请求，此时可在该字段返回具体的原因。
returnMessageIdstring否返回的一个随机串，用来标识这次响应。
在后续报告问题需要 SHOPLINE 协助排查时，你可以提供这个随机串，以便 SHOPLINE 工程师更快地定位到该响应。
refundTransactionIdstring是退款流水号。
channelRefundTransactionIdstring是这笔退款在支付应用的唯一标识。
channelOrderTransactionIdstring是这笔退款关联的支付单，在支付应用的唯一标识。
amountinteger是金额，大于等于 0。传递的精度根据币种会有不同，具体请查看 币种精度。
currencystring是币种，具体请查看 币种精度。
refundStatusstring是此笔退款单当前的 退款状态。
failCodestring否失败编码。当 refundStatus 返回 FAILED 时，通过此字段返回具体的失败编码。
failMessagestring否失败描述。当 refundStatus 返回 FAILED 时，通过此字段返回具体的失败描述。

示例：

{
  "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."
}

物流上报​

商家进行发货操作时，SHOPLINE 将调用物流上报接口，向支付应用同步订单的物流信息。
针对同一个物流单号，因物流状态更新，SHOPLINE 可能会多次上报物流信息，支付应用应该要正确地处理这些上报请求。
调用该接口时，如果 SHOPLINE 无法获取到响应或者响应验签失败，将在 24 小时内以同样的参数重试多次，直到返回格式正确或超过最大重试次数。需要做好幂等处理。

请求方式​

使用 HTTP POST 请求。

请求头​

SHOPLINE 请求物流上报接口时，会携带以下请求头：

字段是否必填含义
pay-api-version是配置支付应用拓展时选择的 API 版本。
pay-api-idempotency-key是幂等 Key。幂等 Key 相同的请求，支付应用应该视为重复请求。
pay-api-signature是请求体的签名值。支付应用在接收请求后，需要 校验签名值 是否匹配；若不匹配则应视为请求非法。
pay-api-timestamp是请求发起的时间，格式为 yyyyMMddHHmmss。

示例：

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

请求体​

SHOPLINE 在请求物流上报接口时，将在请求体携带以下参数：

字段类型是否必填含义
channelOrderTransactionIdstring是物流信息所归属的支付单在支付应用的唯一标识。
trackingListobject[]是物流信息列表。
trackingList.trackingNostring是物流单号。
trackingList.sitestring是物流追踪信息网站。你可以在该网站查询物流单当前的信息。
trackingList.trackingStatusstring是物流状态，当前固定值为 03，含义为已发货。SHOPLINE 将在商家操作发货时同步物流信息到支付应用；如果支付应用需要该物流的更新信息，请结合 trackingNo 和 site 去具体物流服务商官网查询。
trackingList.handlerstring否上报物流信息的店铺的名称。
trackingList.carrierstring是物流承运商。

示例：

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

响应头​

支付应用响应 SHOPLINE 的物流上报请求时，需要携带以下响应头：

字段是否必填含义
pay-api-signature是响应体的签名值。SHOPLINE 在收到响应后，将 校验签名值 是否匹配；若不匹配则应视为响应非法。

示例：

pay-api-signature: SIGNSIGNSIGN

响应体​

支付应用响应 SHOPLINE 的物流上报请求时，需要返回以下信息：

字段类型是否必填含义
returnCodestring是接口响应状态码。有效枚举值包含：
• SUCCESS：SHOPLINE 认为此次物流上报接口调用成功。
• 非 SUCCESS：SHOPLINE 将不会对支付单进行任何处理。
returnMessagestring否响应描述。当 returnCode 返回非 SUCCESS 时，代表支付应用不接受此次物流上报请求，此时可在该字段返回具体的原因。
returnMessageIdstring否返回的一个随机串，用来标识这次响应。
在后续报告问题需要 SHOPLINE 协助排查时，你可以提供这个随机串，以便 SHOPLINE 工程师更快地定位到该响应。

示例：

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

钱包支付配置查询​

SHOPLINE 在需要渲染 Apple Pay 或者 Google Pay 支付按钮时，将通过该接口获取店铺的数字钱包配置信息。

请求方式​

使用 HTTP POST 请求。

请求头​

SHOPLINE 请求钱包支付配置查询接口时，会携带以下请求头：

字段是否必填含义
pay-api-version是配置支付应用拓展时选择的 API 版本。
pay-api-idempotency-key是幂等 Key。幂等 Key 相同的请求，支付应用应该视为重复请求。
pay-api-signature是请求体的签名值。支付应用在接收请求后，需要 校验签名值 是否匹配；若不匹配则应视为请求非法。
pay-api-timestamp是请求发起的时间，格式为 yyyyMMddHHmmss。
pay-api-store-handle是发起付款的店铺的 handle，即店铺唯一标识。

示例：

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

请求体​

无

响应头​

支付应用响应 SHOPLINE 的钱包支付配置查询请求时，需要携带以下响应头：

字段是否必填含义
pay-api-signature是响应体的签名值。SHOPLINE 在收到响应后，将 校验签名值 是否匹配；若不匹配则应视为响应非法。

示例：

pay-api-signature: SIGNSIGNSIGN

响应体​

支付应用响应 SHOPLINE 的钱包支付配置查询请求时，需要返回以下信息：

字段类型是否必填含义
returnCodestring是接口响应状态码。有效枚举值包含：
  • SUCCESS：SHOPLINE 认为此次钱包支付配置查询接口调用成功。
  • 非 SUCCESS：SHOPLINE 将认为支付应用不接受此次钱包支付配置查询请求。
returnMessagestring否响应描述。当 returnCode 返回非 SUCCESS 时，代表支付应用不接受此次钱包支付配置查询请求，此时可在该字段返回具体的原因。
returnMessageIdstring否返回的一个随机串，用来标识这次响应。
在后续报告问题需要 SHOPLINE 协助排查时，你可以提供这个随机串，以便 SHOPLINE 工程师更快的定位到该响应。
paymentMethodstring是数字钱包支付方式。有效枚举值包含：
  • ApplePay：Apple Pay 支付模式
  • GooglePay：Google Pay 支付模式
channelConfigDatastring是支付渠道配置信息。格式为 JSON 字符串，具体结构取决于 paymentMethod 的值。

支付渠道配置信息​

下面根据 paymentMethod 的不同值，说明 channelConfigData 的结构。

  • Apple Pay：
    当 paymentMethod 为 ApplePay 时，channelConfigData 返回结构如下：
字段类型是否必填含义
merchantCapabilitiesstring[]是商家支持的支付能力。有效枚举值包含：
  • supports3DS：必定返回。
  • supportsCredit：若支持信用卡则返回。
  • supportsDebit：若支持借记卡则返回。
  • supportsEMV：若支持中国银联则返回。
如果 supportsCredit 和 supportsDebit 均未返回，默认同时支持信用卡和借记卡。
supportedNetworksstring[]是商家支持的支付系统网络。例如：amex、visa。
  • Google Pay：
    当 paymentMethod 为 GooglePay 时，channelConfigData 返回结构如下：
字段类型是否必填含义
typestring是付款方式类型。仅支持 CARD，代表卡支付。
parametersobject是付款方式类型的配置参数。
parameters.allowedAuthMethodsstring[]是支持的支付验证方式。有效枚举值包含：
  • PAN_ONLY：PAN 直接验证。使用 Google 账号存档卡，返回数据包含 PAN 及有效期。
  • CRYPTOGRAM_3DS：3DS 密文验证。使用 Android 设备令牌卡，返回数据包含 3DS 密文。
parameters.allowedCardNetworksstring[]是支持的支付系统网络。例如：AMEX、VISA。
tokenizationSpecificationobject是支付标记化配置信息。
tokenizationSpecification.typestring是标记化类型。有效枚举值包含：
  • PAYMENT_GATEWAY：支付网关
  • DIRECT：直连
tokenizationSpecification.parametersobject是标记化类型的配置参数。
tokenizationSpecification.parameters.gatewaystring否支付网关。当 tokenizationSpecification.type 为 PAYMENT_GATEWAY 时返回。
tokenizationSpecification.parameters.gatewayMerchantIdstring否支付网关账号 ID。当 tokenizationSpecification.type 为 PAYMENT_GATEWAY 时返回。
tokenizationSpecification.parameters.protocolVersionstring否加密协议版本。当 tokenizationSpecification.type 为 DIRECT 时返回。
tokenizationSpecification.parameters.publicKeystring否加密公钥。当 tokenizationSpecification.type 为 DIRECT 时返回。
这篇文章对你有帮助吗？
SHOPLINE
SHOPLINE
SHOPLINE Enterprise
条款协议
隐私
条款
开发者协议
LinkedInEmail
LinkedInEmail
© Copyright 2013-2026 SHOPLINE Limited.