说明

欢迎来到 Payinsider。

Payinsider API 为您全面开放 Payinsider 平台所有产品的技术 接入资源，支持多样化的对接模式与多语言服务。只需在 Payinsider 完成一次性对接，并借助我们的测试工具，您便能迅速与多家支付服 务商实现技术联通。 在对接流程中，您的专属 Payinsider 客户经理将全程陪伴，为 您提供专业的支持与指导。若您在对接过程中遇到任何问题或需要提 出反馈，请随时通过 Payinsider 官方邮箱 info@pay-insider.com 与 我们联系，我们将迅速响应并为您提供帮助。

一、起步

Payinsider 根据商户的模式特征提供三种对接模式：

1、端对端直连对接模式：本模式需要商户具备 PCI 资质认证或 对接上游认可的端对端直连资质认证，该模式下，需向 Payinsider 报备请求 IP 地址，Payinsider 会处理 IP 白名单，如遇 IP 变更，请 及时报备更新。

2、SDK 收银台模式：本模式适用于所有商户，Payinsider 提供 两种页面呈现形式，商户可根据收银台页面实际情况选择适合贵司的 形式：

1）自定义卡收集对接：仅支持信用卡对接 2）多支付方式集成对接：支持信用卡和本地支付组合式对接

3、Payinsider Hosted Checkout 模式：该模式下，checkout 页面由 Payinsider 统一管理，页面有灵活的 UI 模块，适配商户品牌 调性定制结账页面外观，支持页面根据商户配置展示支付方式、产品 信息、订单信息及其他自定义说明。

1、Payinsider 创建并发放沙盒环境账号给到商户，沙盒环境账 号支持商户体验全场景全模式服务。 2、商户根据 Payinsider API 说明进行沙盒环境技术对接。 3、对接完成后 Payinsider 根据商户所选对接模式及业务服务 发放具备权限的正式环境账号帮助商户完成转正。

沙盒环境 API 请求地址:

请求 url：

https://sandbox.pay-insider.com

内嵌 js 地址:

https://sandbox.pay-insider.com/v1/iframe/payinsider-pay.js

正式环境 API 请求地址:

请求 url：

https://product.pay-insider.com

内嵌 js 地址:

https://product.pay-insider.com/v1/iframe/payinsider-pay.js

Payinsider 发布新的功能时，会在商户后台发布公告说明，同时 4 会更新 API 的版本内容，请关注 API 的信息变更通知，为了防止影 响既有商户的对接业务，Payinsider 建议商户在 API 请求头上传递 x-api-version 信息。

如果省略传递版本信息，默认对接版本为 API 最早支持的版本。

二、认证授权

secureKey：

Payinsider 对所有请求使用 API 密钥 secureKey 进行身份验证。 您可以在 Payinsider 后台管理 API 密钥 secureKey。 API 密钥在 Payinsider 平台具有授权性，如授权直连，授权扣 款支付，因此需要保持 API 密钥的私有性和安全性。建议在对接过程 中不要使用硬编码、泄露 API 密钥、共享 API 密钥（特别是在源代 码版本控制系统中）等。 身份验证是通过 HTTP 的 Header 及请求体中的签名处理的，请 对接过程中保持两处传值正确。

Sign 值：

接口请求需要 sign 值签名认证，每个接口签名组成参数不同， 业务参数拼接完成后+secureKey 使用 SHA256 进行签名，示例如下： 1、每个接口请求参数的参与 sign 值请求的字段及顺序都有响 应说明，假设接口参与 sign 值计算的字段及顺序都要求如下： amount(1.00)， currency(USD) orderNo(124512345687451) requestId(15485233122) terminalId(100055522) timestamp(1755622145566) transNo(T1255224145556224554)

2、将以上参数的按顺序拼接其 value 并在末尾拼接 secureKey （GVGwstOxT8xOeskKlpXaZOb7Yfdz8tOc）得到以下内容： 1.00USD1245123456874511548523312210005552217556 22145566T1255224145556224554GVGwstOxT8xOeskKlpXaZ Ob7Yfdz8tOc

3、使用 SHA256 对以上内容进行签名，得到 sign 值为： 41741105aaa67df41ce559ebdecef6c8317065bb67b6e0427c9 07156f91968a3

三、响应信息说明

推送 url、返回 url 说明

推送 url 在 Payinsider 用于异步推送调起，在 Payinsider 后台 账户管理>终端商城>终端（APP/网站）下可配置。 返回 url 在实时调用 API 接口时进行传参，用以在浏览器做页面 跳转或后台接收实时返回信息等。

HTTP 状态码

HTTP 状态码可在对接过程中确认 API 请求的成功或者失败，在 对接过程中可能从 Payinsider 处接收到的 HTTP 状态码如下，如接 收到除此之外的其他状态码，可联系 Payinsider 获取说明：

Status Code	Status Message	Payinsider Status	Decline Reason
200	OK	SUCCESS	The request message has been successfully processed, and it has produced a response. The response message varies, depending on the request method and the requested data.
400	Bad	Request OUTAGE	The receiving server cannot understand the request because of malformed syntax. Do not repeat the request without first modifying it; check the request for errors, fix them and then retry the request.
401	Unauthorized	SOFT_DECLINE	You need to input valid authentication credentials (username/password) to access the resource.
403	Forbidden by acquirers	HARD_DECLINE	You do not have the appropriate user rights to access the request.
			Do not repeat the request.
404	Not Found	HARD_DECLINE	It was not possible to retrieve the resource you requested at the specified location. It may or may not become available again in the future. Usually, this happens when the URL you pass with the request is incorrect. You may make subsequent calls.
413	Payload too large	SOFT_DECLINE	The body of your request was too large. The maximum request size is 10MB. Send the request again with a size of less than 10MB.
500	Internal Server Error	OUTAGE	The receiving server encountered an unexpected condition that prevents it from fulfilling the request. Our servers may return a 500 status code also when the request is incorrect, for example because of a missing or not filled in mandatory field.

Payinsider 会根据交易的真实情况，为每一笔订单转义对应我司 统一管理的响应码和响应信息，方便商户根据响应码统一做业务判断。 Payinsider 会在每种响应代码说明中对该响应码进行说明，方便商户 了解更详细的交易情况。对应 Payinsider 响应信息的字段分别为 payinsiderResponseCode 和 payinsiderResponseMessage。

渠道响应码为商户对接的上游渠道真实响应码，在每个渠道的响 应码值和说明各有差异。

Payinsider 会在响应信息中对应 Payinsider 响应码和说明的字 段中进行转义和说明，同时 Payinsider 也会为商户提供真实的上游 渠道响应码和说明以便让商户在跟上游渠道沟通时更加便利、高效， 对应 Payinsider 响应信息中的字段分别为 acquirerResponseCode 和 acquirerResponseMessage。

交易状态是该笔订单在交易发生过程中及完成时的状态，Payinsider 针对交易状态分为三种情况：

Success -- 交易成功，代表交易的最终完成状态为成功。

Fail -- 交易失败，代表交易的最终状态为失败。

Pending -- 交易过程中的待处理状态，非交易最终状态，多在 3D 交易、授权交易、非信用卡等交易场景中发生。

四、幂等性

为防止订单存在重复下单、消费者重复支付等情况导致商户成本 增高，商户在每次下单请求前需要请求 Payinsider 生成唯一值 requestID，该 ID 有效期 30 分钟，并且在多次请求时能保证商户订 单的准确性。

五、数据标准要求

类型	格式要求
String	字符串，长度参照具体字段
Integer	整数位的数字
Dates	日期格式，格式要求为 YYYY-MM-DD hh24:mi:ss
Number	支持两位小数的数字
Timestamps1	时间戳要求，毫秒级时间戳，按照 UTC 时间生成，如：1725107628725
Timestamps2	YYYY-MM-DD HH24:mi:sss
Country Codes	参照 ISO 3166-2 标准
Currency Codes	参照 ISO 4217 标准
TLS 协议	TLS v1.2 以上
State Codes	参照 ISO 3166 Alpha-2 标准

六、版本日志

1、第一章数据标准要求中增加州字段传值要求

2、第二章交易 SDK 自定义卡收集对接模块传值信息增加产品 信息等

3、第三章订阅管理 API 修改续订扣费推送内容，增加订阅推送 系列功能

4、增加第四章商品管理 API 模块

5、增加第五章用户管理 API

6、增加第六章优惠券 SDK 对接

7、订单类管理交易推送修改推送内容

交易 SDK 对接

一、对接模式介绍

SDK 对接模式不需要用户具备 PCI 认证资质，Payinsider 提供 两种页面呈现形式供商户选择：

自定义卡收集对接 -- 开发者可在页面直接内嵌 Payinsider 提供卡信息收集页面，输入框样式和字体颜色大小均可自定义。下图红框部分为 Payinsider 的内嵌页面，用户可自定义样式和大小。

多支付方式集成对接 -- 开发者可在页面内嵌 Payinsider 集成多支付方式收银台页面，Payinsider 后台可对产品支持的支付方式进行勾选并自定义排序方式。下图页面红框部分为 Payinsider 集成式加载，该模式可配合使用 Payinsider 的优惠券功能，页面呈现效果如图：

二、自定义卡收集对接

1、非直连模式

对接步骤

1、商户在页面引用 Payinsider 自定义卡收集对接 js：

//此处示例代码为 Payinsider 沙盒环境 js 地址，如果对接正式环境，需要切换正式环境地址
<script src="https://sandbox.pay-insider.com/v1/iframe/payinsider-pay.js"></script>

2、在页面内嵌 Payinsider 卡信息 Dom 和弹窗 Dom，下文代 码中 id 部分不可变更，例：<div id="payinsider-number-frame"></div> ，其他代码可 根据自己网站需求自定义:

<!-- 以下是卡信息 dom -->
<div class="payinsider-pay-test-frame">
  <div class="row-frame">
    <div class="row-pay-frame">
      <span>Card number</span>
      <div class="pay-frame">
        <div id="payinsider-number-frame"></div>
      </div>
    </div>
  </div>
  <div class="row-frame">
    <div class="row-pay-frame">
      <span>Expiry date</span>
      <div class="pay-frame">
        <div id="payinsider-date-frame"></div>
        <!-- <div id="payinsider-month-frame"></div> -->
        <!-- <div id="payinsider-year-frame"></div> -->
      </div>
    </div>
  </div>
  <div class="row-frame">
    <div class="row-pay-frame">
      <span>CVV</span>
      <div class="pay-frame">
        <div id="payinsider-cvv-frame"></div>
      </div>
    </div>
  </div>
  <input type="submit" id="submitButton" class="submitBtn" value="Submit" />
</div>
<!-- 以下是弹窗 dom -->
<div id="payinsider-loading" class="payinsider-loading">
  <div class="loading-container">
    <div class="spinnerOneBox spinnerMaxBox">
      <div class="spinnerOneBox spinnerMidBox">
        <div class="spinnerOneBox spinnerMinBox"></div>
      </div>
    </div>
  </div>
</div>

3、页面引入以下样式部分，并可以修改自定义：

<style>
body, html {
  margin: 0 auto;
  padding: 0;
  box-sizing: border-box;
  background-color: #FFFFFF;
}
.payinsider-pay-test-frame {
  width: 40em;
  padding: .85em;
  border-radius: .28em;
  border: 1px solid #DCDFE6;
  margin: 17em auto;
}
.row-frame {
  width: 100%;
  display: flex;
  align-items: center;
  margin-bottom: 1em;
}
.row-pay-frame {
  flex: 1;
  margin: 0 .48em;
  position: relative;
}
.row-pay-frame .pay-frame {
  height: 2.28em;
  line-height: 2.28em;
  margin: .57em 0;
  display: flex;
  align-items: center;
}
.row-pay-frame span {
  padding: 0 .52em;
}
.row-pay-frame>span:after {
  content: '*';
  position: absolute;
  top: 0;
  left: 0;
  color: #000000;
}
.row-frame .pay-frame>div {
  flex: 1;
  height: 100%;
  padding: 0 .28em;
  border-radius: .28em;
  border: 1px solid #DCDFE6;
  position: relative;
}
.row-frame .pay-frame>div.payinsider-error {
  border-color: #FF4D4F;
}
.row-frame .pay-frame>div:first-child {
  margin-right: .57em;
}
.row-frame .pay-frame>div .payinsider-hint {
  width: 100%;
  font-size: .85em;
  white-space: nowrap;
  color: #FF4D4F;
  position: absolute;
  top: 100%;
  left: -.5em;
}
.submitBtn {
  color: #FFFFFF;
  font-weight: bold;
  width: 100%;
  height: 2.58em;
  border-radius: .28em;
  background: #000000;
  margin: .57em .28em;
  outline: none;
  cursor: pointer;
}
/* 以下是弹窗 css */
.payinsider-loading {
  width: 100%;
  height: 100%;
  background: rgba(0, 0, 0, 0.8);
  position: fixed;
  top: 0;
  left: 0;
  z-index: 99999;
  display: none;
}
.loading-container {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
}
.spinnerOneBox {
  align-items: center;
  border: 0.3em solid transparent;
  border-top: 0.3em solid #fff;
  border-right: 0.3em solid #fff;
  border-radius: 100%;
  display: flex;
  justify-content: center;
}
.spinnerMaxBox {
  animation: spinnerOne 3s linear infinite;
  height: 3em;
  width: 3em;
}
.spinnerMidBox {
  animation: spinnerOne 5s linear infinite;
  height: 2.4em;
  width: 2.4em;
}
.spinnerMinBox {
  animation: spinnerOne 5s linear infinite;
  height: 1.8em;
  width: 1.8em;
}
@keyframes spinnerOne {
  0% {
    transform: rotate(0deg);
  }
  100% {
    transform: rotate(360deg);
  }
}
</style>

4、页 面 初 始 化 时 需 要 每 次 在 服 务 端 请 求 以 下 接 口 获 取 AccessToken，该 AccessToken 有效期为 30 分钟，超过 30 分钟失 效则下单请求失败。secret-key 可在 Payinsider 后台设置种查看。

服务端请求以下接口,每笔交易都需要先请求获取 AccessToken

curl --request POST
--url 'https://sandbox.pay-insider.com/router/checkout/accessToken'
--header 'Content-Type: application/json'
--header 'terminal-id: 240000500001'
--header 'secret-key: lwQP3QdSbYdiYaLtyvyzDGZ'

5、页面初始化，在页面加入以下代码：

let payinsider = null
// 商 品 id 数 据 储 存 变 量 ----------------------------- 2024.11.06
// 确保 payinsider 已注册 destroy（注销） 推荐离开页面时使用
if (payinsider) payinsider.destroy()
let accessToken =
  'f72ac43559c58f2c2463b2cc7e9a7cccc767d14032a66614a45677ddb256a282'
let frameName = [
  'payinsider-number-frame',
  'payinsider-cvv-frame',
  'payinsider-month-frame',
  'payinsider-year-frame',
  'payinsider-date-frame',
]
const appearance = {
  // 主题色 默认 default  黑暗 dark
  theme: 'default',
  variables: {
    // // 字体
    // familyPrimaryText: 'Roboto-Black-1',
    // // 基础字体大小
    // sizePrimaryText: 16,
    // // 字体颜色
    // colorPrimaryText: '#fff',
    // // 底色
    // backgroundColorPrimary: '#000',
    // // placeholder颜色
    // colorPlaceholder: '',
    // // input Selection 颜色
    // backgroundColorInputSelection: '',
    // // 按钮底色  可接受单个字符串和2位（渐变色）数组传参
    // backgroundColorButton: ['green', 'yellow'],
    // // 按钮字体颜色
    // colorButtonText: '#fff',
    // // 为弹窗z-index层级设置一个值
    // zIndex: 1,
  },
}
payinsider = new PayinsiderPay(
  accessToken,
  {
    // 小语种
    lang: 'zh',
    // 新增传参商品信息 缺失无法加载
    productList: [
      {
        // 商品id
        productId: 'SP0aJkxaY9QDZTLLM0LG',
        // 商品数量
        quantity: 2,
      },
      {
        // 商品id
        productId: 'SP0aJkxog1376liYn0ff',
        // 商品数量
        quantity: 1,
      },
    ],
    // 新增传参pi消费者ID或商户用户id   二选一    缺失无法加载
    piCustomerId: '',
    customerId: 'CI0aHCZb26T85iogrC1y111201',
    // 新增传参终端    缺失无法加载
    terminalId: '240000130001',
    // 商品清单是否显示：默认true显示
    showOrderSummary: true,
    // 优惠券是否展示使用：默认true显示
    showCoupon: true,
    // 是否加载国家地区：默认true显示
    countryRegion: true,
    // 设置为true 商品清单的高度能够根据内容自动进行调整 默认false
    orderSummaryAutosize: true,
  },
  {
    ready: function (key, val) {
      // 弹窗关闭
      $('#payinsider-loading').fadeOut(500)
      frameName.forEach((v) => {
        $('#' + v).removeClass('payinsider-error')
        $('#' + v)
          .find('.payinsider-hint')
          .remove()
      })
      if (val.code && val.code !== 200 && Array.isArray(val.data)) {
        frameName.forEach((v) => {
          if (val.data.filter((n) => n.name === v).length) {
            var msg = val.data.filter((n) => n.name === v)[0].msg
            $('#' + v).addClass('payinsider-error')
            $('#' + v).append(
              '<span class="payinsider-hint">' + msg + '</span>'
            )
          } else {
            $('#' + v).removeClass('payinsider-error')
            $('#' + v)
              .find('.payinsider-hint')
              .remove()
          }
        })
      }
    },
  }
)
// 样式覆盖
payinsider.elements({ appearance })
payinsider.init()

6、用户下单时点击按钮加载以下代码：

$('#submitButton').click((v) => {
  // 弹窗开启
  $('#payinsider-loading').fadeIn(500)
  let values = {
    requestId: 'f125ca9914a04a238975b39364e0fa1e',
    terminalId: '240000170001',
    orderNo: 'JL1725929856504',
    paymentMethod: 'Credit/Debit Card',
    billingFirstName: 'CL',
    billingLastName: 'BRW2',
    billingEmail: 'test@qq.com',
    billingPhone: '13612341234',
    billingCountry: 'US',
    billingState: 'TX',
    billingCity: 'CYPRESS',
    billingAddress: '142 MANOR CT',
    billingZip: '77429',
    shippingFirstName: 'CL',
    shippingLastName: 'BRW2',
    shippingPhone: '13612341234',
    shippingEmail: 'test@qq.com',
    shippingCountry: 'US',
    shippingState: 'TX',
    shippingCity: 'CYPRESS',
    shippingAddress: '142 MANOR CT',
    shippingZip: '77429',
    returnUrl: 'http://ckci.hr/ciryjcpr',
    noticeUrl: 'http://jvuzgyfu.nl/sctiztiir',
    customerIp: '121.35.58.156',
  }
  payinsider.checkout(values)
})

请求参数说明

字段名	类型	是否必填	规则描述
requestId	String(32)	Y	接口请求 ID,30 分钟内需唯一
timestamp	Timestamps1	Y	时间戳要求为 30 分钟内的时间，毫秒级时间戳，按照 UTC 时间生成，如：1725107628725
terminalId	String	Y	Payinsider 提供的终端号
orderNo	String(50)	Y	商户订单的唯一 ID
paymentMethod	String(20)	Y	信用卡传"Credit/Debit Card"
customerIp	String(64)	Y	消费者 IP
returnUrl	String(255)	Y	结果返回地址，用于交易结束时返回
billingFirstName	String(50)	Y	账单人名
billingLastName	String(50)	Y	账单人姓
billingEmail	String(255)	Y	账单邮箱
billingPhone	String(30)	N	账单手机号
billingCountry	String(2)	Y	账单国家
billingState	String(40)	N	账单州(如果有收集真实信息需如实填写，影响上游风控)
billingCity	String(40)	N	账单城市(如果有收集真实信息需如实填写，影响上游风控)
billingAddress	String(100)	N	账单地址(如果有收集真实信息需如实填写，影响上游风控)
billingZip	String(20)	Y	账单邮编
shippingFirstName	String(50)	N	收件人名
shippingLastName	String(50)	N	收件人姓
shippingPhone	String(30)	N	收件手机号
shippingEmail	String(255)	N	收件邮箱
shippingCountry	String(2)	N	收件国家
shippingState	String(40)	N	收件州
shippingCity	String(40)	N	收件城市
shippingAddress	String(100)	N	收件地址
shippingZip	String(20)	N	收件邮编

返回参数说明

返回参数	类型	描述
refId	String	商户订单的唯一 ID
orderId	String	Payinsider 唯一订单 ID
gatewayId	String	支付渠道交易 ID
amount	String	金额
currency	String	币种
status	Integer	状态:1 成功；2 失败；3 待处理
acquirer	String	上游渠道名称
acquirerResponseCode	String	上游渠道返回代码
acquirerResponseMessage	String	上游渠道返回消息
payinsiderResponseCode	String	Payinsider 返回代码
recurringToken	String	订阅交易凭证
payinsiderResponseMessage	String	Payinsider 返回消息
subscriptionId	String	订阅群组 Id
piCustomerId	String	Payinsider 平台订阅用户 ID
email	String	消费者邮箱

2、直连模式

对接步骤

1、商户在页面引用 Payinsider 自定义卡收集对接 js：

//此处示例代码为 Payinsider 沙盒环境 js 地址，如果对接正式环境，需要切换正式环境地址
<script src="https://sandbox.pay-insider.com/iframe/payinsider-pay.js"></script>

2、在页面内嵌 Payinsider 卡信息 Dom，下文代码中 id 部分不可变更，例：<div id="payinsider-number-frame"></div> ，其他代码可根据自己网站需求自定义:

<!-- 以下是卡信息 dom -->
<div class="payinsider-pay-test-frame">
  <div class="row-frame">
    <div class="row-pay-frame">
      <span>Card number</span>
      <div class="pay-frame">
        <div id="payinsider-number-frame"></div>
      </div>
    </div>
  </div>
  <div class="row-frame">
    <div class="row-pay-frame">
      <span>Expiry date</span>
      <div class="pay-frame">
        <div id="payinsider-date-frame"></div>
        <!-- <div id="payinsider-month-frame"></div> -->
        <!-- <div id="payinsider-year-frame"></div> -->
      </div>
    </div>
  </div>
  <div class="row-frame">
    <div class="row-pay-frame">
      <span>CVV</span>
      <div class="pay-frame">
        <div id="payinsider-cvv-frame"></div>
      </div>
    </div>
  </div>
  <input type="submit" id="submitButton" class="submitBtn" value="Submit" />
</div>
<!-- 以下是弹窗 dom -->
<div id="payinsider-loading" class="payinsider-loading">
  <div class="loading-container">
    <div class="spinnerOneBox spinnerMaxBox">
      <div class="spinnerOneBox spinnerMidBox">
        <div class="spinnerOneBox spinnerMinBox"></div>
      </div>
    </div>
  </div>
</div>

3、页面引入以下样式部分，并可以修改自定义：

<style>
body, html {
  margin: 0 auto;
  padding: 0;
  box-sizing: border-box;
  background-color: #FFFFFF;
}
.payinsider-pay-test-frame {
  width: 40em;
  padding: .85em;
  border-radius: .28em;
  border: 1px solid #DCDFE6;
  margin: 17em auto;
}
.row-frame {
  width: 100%;
  display: flex;
  align-items: center;
  margin-bottom: 1em;
}
.row-pay-frame {
  flex: 1;
  margin: 0 .48em;
  position: relative;
}
.row-pay-frame .pay-frame {
  height: 2.28em;
  line-height: 2.28em;
  margin: .57em 0;
  display: flex;
  align-items: center;
}
.row-pay-frame span {
  padding: 0.52em;
}
.row-pay-frame>span:after {
  content: '*';
  position: absolute;
  top: 0;
  left: 0;
  color: #000000;
}
.row-frame .pay-frame>div {
  flex: 1;
  height: 100%;
  padding: 0 .28em;
  border-radius: .28em;
  border: 1px solid #DCDFE6;
  position: relative;
}
.row-frame .pay-frame>div.payinsider-error {
  border-color: #FF4D4F;
}
.row-frame .pay-frame>div:first-child {
  margin-right: .57em;
}
.row-frame .pay-frame>div .payinsider-hint {
  width: 100%;
  font-size: .85em;
  white-space: nowrap;
  color: #FF4D4F;
  position: absolute;
  top: 100%;
  left: -.5em;
}
.submitBtn {
  color: #FFFFFF;
  font-weight: bold;
  width: 100%;
  height: 2.58em;
  border-radius: .28em;
  background: #000000;
  margin: .57em .28em;
  outline: none;
  cursor: pointer;
}
/* 以下是弹窗 css */
.payinsider-loading {
  width: 100%;
  height: 100%;
  background: rgba(0, 0, 0, 0.8);
  position: fixed;
  top: 0;
  left: 0;
  z-index: 99999;
  display: none;
}
.loading-container {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
}
.spinnerOneBox {
  align-items: center;
  border: 0.3em solid transparent;
  border-top: 0.3em solid #fff;
  border-right: 0.3em solid #fff;
  border-radius: 100%;
  display: flex;
  justify-content: center;
}
.spinnerMaxBox {
  animation: spinnerOne 3s linear infinite;
  height: 3em;
  width: 3em;
}
.spinnerMidBox {
  animation: spinnerOne 5s linear infinite;
  height: 2.4em;
  width: 2.4em;
}
.spinnerMinBox {
  animation: spinnerOne 5s linear infinite;
  height: 1.8em;
  width: 1.8em;
}
@keyframes spinnerOne {
  0% {
    transform: rotate(0deg);
  }
  100% {
    transform: rotate(360deg);
  }
}
</style>

4、页 面 初 始 化 时 需 要 每 次 在 服 务 端 请 求 以 下 接 口 获 取 AccessToken，该 AccessToken 有效期为 30 分钟，超过 30 分钟失 效则下单请求失败。secret-key 可在 Payinsider 后台设置种查看。

服务端请求以下接口,每笔交易都需要先请求获取 AccessToken

curl --request POST
--url 'https://sandbox.pay-insider.com/router/checkout/accessToken'
--header 'Content-Type: application/json'
--header 'terminal-id: 240000500001'
--header 'secret-key: lwQP3QdSbYdiYaLtyvyzDGZ'

5、页面初始化，在页面加入以下代码：

let payinsider = null
// 商 品 id 数 据 储 存 变 量 ----------------------------- 2024.11.06
// 确保 payinsider 已注册 destroy（注销） 推荐离开页面时使用
if (payinsider) payinsider.destroy()
let accessToken =
  'f72ac43559c58f2c2463b2cc7e9a7cccc767d14032a66614a45677ddb256a282'
let frameName = [
  'payinsider-number-frame',
  'payinsider-cvv-frame',
  'payinsider-month-frame',
  'payinsider-year-frame',
  'payinsider-date-frame',
]
payinsider = new PayinsiderPay(
  accessToken,
  {
    lang: 'zh',
    fontFamily: 'Roboto-Black-1',
    fontColor: 'red',
    fontPlaceholder: '#ccc',
    selectionColor: '',
    fontSize: 14, // 新增传参商品信息 缺失无法加载
  },
  {
    ready: function (key, val) {
      // 弹窗关闭
      $('#payinsider-loading').fadeOut(500)
      frameName.forEach((v) => {
        $('#' + v).removeClass('payinsider-error')
        $('#' + v)
          .find('.payinsider-hint')
          .remove()
      })
      if (val.code && val.code !== 200 && Array.isArray(val.data)) {
        frameName.forEach((v) => {
          if (val.data.filter((n) => n.name === v).length) {
            var msg = val.data.filter((n) => n.name === v)[0].msg
            $('#' + v).addClass('payinsider-error')
            $('#' + v).append(
              '<span class="payinsider-hint">' + msg + '</span>'
            )
          } else {
            $('#' + v).removeClass('payinsider-error')
            $('#' + v)
              .find('.payinsider-hint')
              .remove()
          }
        })
      }
    },
  }
)
payinsider.init()

6、用户下单时点击按钮加载以下代码：

$('#submitButton').click((v) => {
  // 弹窗开启
  $('#payinsider-loading').fadeIn(500)
  let values = {
    requestId: 'f125ca9914a04a238975b39364e0fa1e',
    terminalId: '240000170001',
    orderNo: 'JL1725929856504',
    paymentMethod: 'Credit/Debit Card',
    billingFirstName: 'CL',
    billingLastName: 'BRW2',
    billingEmail: 'test@qq.com',
    billingPhone: '13612341234',
    billingCountry: 'US',
    billingState: 'TX',
    billingCity: 'CYPRESS',
    billingAddress: '142 MANOR CT',
    billingZip: '77429',
    shippingLastName: 'BRW2',
    shippingPhone: '13612341234',
    shippingEmail: 'test@qq.com',
    hippingCountry: 'US',
    shippingState: 'TX',
    shippingCity: 'CYPRESS',
    shippingAddress: '142 MANOR CT',
    shippingZip: '77429',
    recurringType: 'init',
    billingInterval: 3,
    returnUrl: 'http://ckci.hr/ciryjcpr',
    noticeUrl: 'http://jvuzgyfu.nl/sctiztiir',
  }
  payinsider.checkout(values)
})

请求参数说明

字段名	类型	是否必填	规则描述
requestId	String(32)	Y	接口请求 ID,30 分钟内需唯一
timestamp	Timestamps1	Y	时间戳要求为 30 分钟内的时间，毫秒级时间戳，按照 UTC 时间生成，如：1725107628725
terminalId	String	Y	Payinsider 提供的终端号
orderNo	String(50)	Y	商户订单的唯一 ID
currency	String(3)	Y	3 位字母的交易币种 遵循 ISO4217
amount	String(10)	Y	交易金额，最多支持两位小数
paymentMethod	String(20)	Y	信用卡传"Credit/Debit Card"
customerIp	String(64)	Y	消费者 IP
returnUrl	String(255)	Y	结果返回地址，用于交易结束时返回
billingFirstName	String(50)	Y	账单人名
billingLastName	String(50)	Y	账单人姓
billingEmail	String(255)	Y	账单邮箱
billingPhone	String(30)	N	账单手机号
billingCountry	String(2)	Y	账单国家
billingState	String(40)	N	账单州(如果有收集真实信息需如实填写，影响上游风控)
billingCity	String(40)	N	账单城市(如果有收集真实信息需如实填写，影响上游风控)
billingAddress	String(100)	N	账单地址(如果有收集真实信息需如实填写，影响上游风控)
billingZip	String(20)	Y	账单邮编
shippingFirstName	String(50)	N	收件人名
shippingLastName	String(50)	N	收件人姓
shippingPhone	String(30)	N	收件手机号
shippingEmail	String(255)	N	收件邮箱
shippingCountry	String(2)	N	收件国家
shippingState	String(40)	N	收件州
shippingCity	String(40)	N	收件城市
shippingAddress	String(100)	N	收件地址
shippingZip	String(20)	N	收件邮编
customerId	String(64)	如交易为订阅类支 付，则必传	在商户网站消费者唯一标识
recurringType	String(10)	如交易为订阅类支 付，则必传	如为订阅交易，该字段传"init"
lineItems	Array	N	交易商品信息,json 格式的对 象数组字符：[{"name":"商品 名称"，"price":"商品单价"， "quantity":"商品数量"， "sku":"商品 sku"，"total":"商 品总价"}]
billingInterval	Integer	如交易为订阅类支 付，则必传	扣款频率(1:天,2:周,3:月,4: 季度,5:半年,6:年)
piSubscription	Integer	N	是否由 Payinsider 订阅续费 管理： 该字段不传默认后续由商户 自行发起订阅续费； 如果在 Payinsider 后台进行 订阅续费管理，则需要传值 为 1

返回参数说明

返回参数	类型	描述
refId	String	商户订单的唯一 ID
orderId	String	Payinsider 唯一订单 ID
gatewayId	String	支付渠道交易 ID
amount	String	金额
currency	String	币种
status	Integer	状态:1 成功；2 失败；3 待处理
acquirer	String	上游渠道名称
acquirerResponseCode	String	上游渠道返回代码
acquirerResponseMessage	String	上游渠道返回消息
payinsiderResponseCode	String	Payinsider 返回代码
recurringToken	String	订阅交易凭证
payinsiderResponseMessage	String	Payinsider 返回消息
subscriptionId	String	订阅群组 Id
piCustomerId	String	Payinsider 平台订阅用户 ID
email	String	消费者邮箱

三、支付页面示例文件

1、非直连模式

payinsider-pay-sandbox.html

2、直连模式

payinsider-pay-sandbox.html

订阅管理 API

一、订阅管理功能介绍

Payinsider 为订阅用户提供一套高效的订阅管理工具，涵盖续订 自动扣费及后续订阅信息更新等功能。用户既可以在 Payinsider 的 后台界面轻松修改订阅详情，也可以通过 API 接口发送请求来实现订 阅信息的灵活调整。

二、直连续订扣费接口

Payinsider 提供的续费扣款接口给到用户自行决定续费扣款的时间金额,payinsider 将不维护该续费订阅的相关后台信息

请求地址：{url}/router/direct/pay

请求方式：POST

{
  "requestId": "1724315547385",
  "timestamp": "1724315547385",
  "sign": "6d90aeec6d67ea589a567896090583da3da93c92fd6d1c42e4671f3007ab5842",
  "terminalId": "240000290002",
  "orderNo": "1724309379857",
  "currency": "USD",
  "amount": "1.00",
  "returnUrl": "http://jvuzgyfu.nl/sctiztiir",
  "customerIp": "157.87.126.76",
  "paymentMethod": "Credit/Debit Card",
  "recurringType":"recurring",
  "recurringToken": "f6b454ec7bad0e9fba834ecc54bf8d99db5adc3234e9faeb08760666bbb1915b",
  "lineItems":"[]"
}

字段名	类型	是否必填	规则描述
requestId	String(32)	Y	接口请求 ID,30 分钟内需唯一
timestamp	Timestamps1	Y	时间戳要求为 30 分钟内的时间，毫秒级时间戳，按照 UTC 时间生成，如：1725107628725
sign	String	Y	参与 sign 值计算的字段及拼接顺序为：amount、currency、orderNo、requestId、terminalId、timestamp
terminalId	String	Y	Payinsider 提供的终端号
orderNo	String(50)	Y	商户订单的唯一 ID
currency	String(3)	Y	3 位字母的交易币种 遵循 ISO4217
amount	String(10)	Y	交易金额，最多支持两位小数
paymentMethod	String(20)	Y	信用卡传"Credit/Debit Card"
customerIp	String(64)	N	消费者 IP
returnUrl	String(255)	N	结果返回地址，用于交易结束时返回
recurringType	String(10)	Y	订阅续费交易，该字段传"recurring"
recurringToken	String(64)	Y	首次订阅时返回的订阅交易凭证
lineItems	Array	N	交易商品信息,json 格式的对 象数组字符：[{"name":"商品 名称"，"price":"商品单价"， "quantity":"商品数量"， "sku":"商品 sku"，"total":"商 品总价"}]

返回参数	类型	描述
refId	String	商户订单的唯一 ID
orderId	String	Payinsider 唯一订单 ID
gatewayId	String	支付渠道交易 ID
amount	String	金额
currency	String	币种
status	Integer	状态:1 成功；2 失败；3 待处理
acquirer	String	上游渠道名称
acquirerResponseCode	String	上游渠道返回代码
acquirerResponseMessage	String	上游渠道返回消息
payinsiderResponseCode	String	Payinsider 返回代码
recurringToken	String	订阅交易凭证
payinsiderResponseMessage	String	Payinsider 返回消息
subscriptionId	String	订阅群组 Id
piCustomerId	String	Payinsider 平台订阅用户 ID
email	String	消费者邮箱

三、续订扣费推送

Payinsider 会在续订交易创建并扣款成功后发送续订订单异步 推送，推送共 5 次，首次在续订交易完成时异步推送，后续在 5 分 钟、10 分钟、15 分钟、30 分钟各推送一次，推送后需要使用完整 json 报文+secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值进行对比验证，并响应 200 返回码，Payinsider 收到响应后 会停止推送。示例代码如下：

{
  "event": "recurringUsed.result",
  "refId": "202492051179594",
  "orderId":"O24090200510225100004002",
  "transNo":"T24090200510441300004378",
  "gatewayId": "1830287271275139072",
  "amount":"20.00",
  "currency": "USD",
  "status": 1,
  "acquirer": "XX",
  "acquirerResponseCode": "S",
  "acquirerResponseMessage": "Payment successful",
  "payinsiderResponseCode": "",
  "payinsiderResponseMessage": "",
  "recurringToken": "a056855b4523453452425633eba01f3a4745331874348"，
  "subscriptionId": "S24091014002252200004812",
  "nextRecurringTime":"2024-09-23",
  "piCustomerId"："PDKHYelidihsai",
  "email"："xxx@xx.com",
  "productList":[
    {
      "currency": "USD", "lastAmount": 100, "lastDate": "2024-11-04", "nextAmount": 100, "nextDate": "2024-12-04", "price": 100, "productName": "monthly 100USD", "quantity": 1, "productId": "SP0aIrehCdJagGgs1hxY"
    },
    {
      "currency": "USD", "lastAmount": 100,"lastDate": "2024-11-04", "nextAmount": 100, "nextDate": "2025-11-04", "price": 100, "productName": "year 100USD", "quantity": 1, "productId": "SPiowueqoriuotyuyiu"
    }
  ]
}

字段名	类型	描述
event	String	推送事件，订阅交易续订推送事件为：recurringUsed.result
refId	String	商户的订单 ID
orderId	String	Payinsider 的订单 ID
transNo	String	Payinsider 的交易流水 ID
gatewayId	String	支付渠道商交易 ID
amount	String	交易金额，校验该字段中仅能包含数字和小数点
currency	String	交易币种
status	Integer	交易状态：1 成功 2 失败 3 待处理
acquirer	String	支付渠道商名称
acquirerResponseCode	String	支付渠道返回响应码
acquirerResponseMessage	String	支付渠道返回响应信息
payinsiderResponseCode	String	Payinsider 返回响应码
payinsiderResponseMessage	String	Payinsider 返回响应信息
以下字段为订阅交易推送附加字段
recurringToken	String	Payinsider 订阅 Token
subscriptionId	String	订阅群组 ID
nextRecurringTime	String	订阅交易下次扣款日期
productList	Array	productList 下的字段为多组产品数据，数组格式，支持多产品一笔订单订阅，里面包含多个 key 值，具体见以下 productList.xxx 字段
productList.currency	String	币种
productList.lastAmount	String	本次扣款金额
productList.lastDate	String	本次扣款日期
productList.nextAmount	String	下一次扣款金额
productList.nextDate	String	下一次扣款日期
productList.price	String	产品设定价格
productList.productName	String	产品名称
productList.quantity	String	产品数量
productList.productId	String	产品 ID
piCustomerId	String	Payinsider 平台订阅用户 ID
Email	String	消费者邮箱

四、暂停订阅

请求地址：{url}/router/subscription/pause

请求方式：POST

Header:
sign:sha256(RequestBody +"secretkey")

{
  "terminalId": "240000840001",
  "subscriptionId": "S24111014002252200004812",
  "pauseFlag": "2",
  "pauseStartDate": "2024-11-12",
  "pauseEndDate": "2024-11-15"
}

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 平台提供的终端号
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
pauseFlag	String	Y	暂停方式(1:立即暂停 2:自定义暂停)
pauseStartDate	String	C	计划暂停开始日期，当 cancelFlag 为 2 时必传，格式 YYYY-MM-DD
pauseEndDate	String	N	计划暂停结束日期，格式 YYYY-MM-DD

{
  "msg": "操作成功",
  "code": 200,
  "data": {
    "terminalId": "240000290002",
    "recurringToken": "21f5d4f7c2e0e42d66d71af9cf35bacca4cb98a28b7a37f2ab373feb2fe7ef66",
    "subscriptionId": "S2410251728094370001d416",
    "piCustomerId": "CI0aHNUKIOBEPP0ny2cc",
    "status": 1,
    "cancel": false,
    "expectedCancelDate": "",
    "pause": true,
    "expectedPauseStart": "2024-10-30",
    "expectedPauseEnd": "2024-11-10"
  }
}

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 提供的终端号
recurringToken	String	Y	Payinsider 订阅 Token
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
piCustomerId	String	Y	Payinsider 平台订阅用户 ID
status	String	Y	订阅状态：1.激活订阅 3.取消订阅 4.暂停订阅
cancel	boolean	Y	是否发起取消
expectedCancelDate	String	N	计划取消日期
pause	boolean	Y	是否发起暂停
expectedPauseStart	String	N	暂停开始日期
expectedPauseEnd	String	N	暂停结束日期

五、取消订阅

请求地址：{url}/router/subscription/cancel

请求方式：POST

Header:
sign:sha256(RequestBody +"secretkey")

{
"terminalId": "240000840001",
"subscriptionId": "S24111014002252200004812",
"cancelFlag": "3",
    "cancelDate": "2024-11-12"
}

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 平台提供的终端号
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
cancelFlag	String	Y	取消方式(1:立即取消 2:下期扣款取消 3:自定义取消)
cancelDate	String	C	计划取消日期，当 cancelFlag 为 3 时必传，格式 YYYY-MM-DD

{
  "msg": "操作成功",
  "code": 200,
  "data": {
    "terminalId": "240000290002",
    "recurringToken": "21f5d4f7c2e0e42d66d71af9cf35bacca4cb98a28b7a37f2ab373feb2fe7ef66",
    "subscriptionId": "S2410251728094370001d416",
    "piCustomerId": "CI0aHNUKIOBEPP0ny2cc",
    "status": "3",
    "cancel": true,
    "expectedCancelDate": "2024-10-30",
    "pause": false,
    "expectedPauseStart": "",
    "expectedPauseEnd": ""
  }
}

字段名	数据类型	是否必填	描述
terminalId	String Y	Payinsider 提供的终端号
recurringToken	String Y	Payinsider 订阅 Token
subscriptionId	String Y	订阅订单在 Payinsider 的订阅 ID
piCustomerId	String Y	Payinsider 平台订阅用户 ID
status	String Y	订阅状态：1.激活订阅 3.取消订阅 4.暂停订阅
cancel	boolean	Y	是否发起取消
expectedCancelDate	String N	计划取消日期
pause	boolean	Y	是否发起暂停
expectedPauseStart	String N	暂停开始日期
expectedPauseEnd	String N	暂停结束日期

六、恢复订阅

请求地址：{url}/router/subscription/resume

请求方式：POST

Header:
sign:sha256(RequestBody +"secretkey")

{
"terminalId": "240000840001",
"subscriptionId": "S24111014002252200004812",
"resumeFlag": "2",
    "resumeDate": "2024-11-12"
}

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 平台提供的终端号
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
resumeFlag	String	Y	恢复方式(1:立即恢复 2:自定义恢复)
resumeDate	String	C	计划恢复日期，当 resumeFlag 为 2 时必传，格式 YYYY-MM-DD

{
  "msg": "操作成功",
  "code": 200,
  "data": {
    "terminalId": "240000290002",
    "recurringToken": "21f5d4f7c2e0e42d66d71af9cf35bacca4cb98a28b7a37f2ab373feb2fe7ef66",
    "subscriptionId": "S2410251728094370001d416",
    "piCustomerId": "CI0aHNUKIOBEPP0ny2cc",
    "status": "1",
    "cancel": false,
    "expectedCancelDate": "",
    "pause": ture,
    "expectedPauseStart": "2024-10-30",
    "expectedPauseEnd": "2024-11-07"
  }
}

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 提供的终端号
recurringToken	String	Y	Payinsider 订阅 Token
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
piCustomerId	String	Y	Payinsider 平台订阅用户 ID
status	String	Y	订阅状态：1.激活订阅 3.取消订阅 4.暂停订阅
cancel	boolean	Y	是否发起取消
expectedCancelDate	String	N	计划取消日期
pause	boolean Y 是否发起暂停
expectedPauseStart	String	N	暂停开始日期
expectedPauseEnd	String	N	暂停结束日期

七、撤销取消订阅

请求地址：{url}/router/subscription/revokeCancel

请求方式：POST

Header:
sign:sha256(RequestBody +"secretkey")
{
  "terminalId": "240000840001",
  "subscriptionId": "S24111014002252200004812"
}

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 平台提供的终端号
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID

{
    "msg": "操作成功",
    "code": 200,
    "data": {
    	"terminalId": "240000290002",
    	"recurringToken": "21f5d4f7c2e0e42d66d71af9cf35bacca4cb98a28b7a37f2ab373feb2fe7ef66",
    	"subscriptionId": "S2410251728094370001d416",
    	"piCustomerId": "CI0aHNUKIOBEPP0ny2cc",
    	"status": "1",
    	"cancel": false,
    	"expectedCancelDate": "",
    	"pause": ture,
    	"expectedPauseStart": "2024-10-30",
    	"expectedPauseEnd": "2024-11-07"
}
}

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 提供的终端号
recurringToken	String	Y	Payinsider 订阅 Token
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
piCustomerId	String	Y	Payinsider 平台订阅用户 ID
status	String	Y	订阅状态：1.激活订阅 3.取消订阅 4.暂停订阅
cancel	boolean	Y	是否发起取消
expectedCancelDate	String	N	计划取消日期
pause	boolean	Y	是否发起暂停
expectedPauseStart	String	N	暂停开始日期
expectedPauseEnd	String	N	暂停结束日期

八、已订阅订单中商品信息新增

请求地址：{url}/router/subscription/product/add

请求方式：POST

Header:
sign:sha256(RequestBody +"secretkey")

{
"terminalId": "240000840001",
"subscriptionId": "S24111014002252200004812",
"productId": "SP0aHj8Ig9pdh6NLrgpv",
    "quantity": "1"
}

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 平台提供的终端号
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
productId	String	Y	Payinsider 平台的产品 ID
quantity	String	Y	产品数量

{
    "msg": "操作成功",
    "code": 200,
    "data": {
    	"terminalId": "240000290002",
    	"recurringToken": "21f5d4f7c2e0e42d66d71af9cf35bacca4cb98a28b7a37f2ab373feb2fe7ef66",
    	"subscriptionId": "S2410251728094370001d416",
    	"piCustomerId": "CI0aHNUKIOBEPP0ny2cc",
    	"status": "1",
    	"cancel": false,
    	"expectedCancelDate": "",
    	"pause": ture,
    	"expectedPauseStart": "2024-10-30",
    	"expectedPauseEnd": "2024-11-07",
        "product": {
            "productId": "SP0aHHcffdUXcjfpfPS6",
            "productName": "prod2",
            "price": 20,
            "quantity": 3,
            "currency": "USD",
            "lastAmount": 3,
            "lastDate": "2024-10-25",
            "nextAmount": 57,
            "nextDate": "2024-10-30"
        }
    }
}

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 提供的终端号
recurringToken	String	Y	Payinsider 订阅 Token
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
piCustomerId	String	Y	Payinsider 平台订阅用户 ID
status	String	Y	订阅状态：1.激活订阅 3.取消订阅 4.暂停订阅
cancel	boolean	Y	是否发起取消
expectedCancelDate	String	N	计划取消日期
pause	boolean	Y	是否发起暂停
expectedPauseStart	String	N	暂停开始日期
expectedPauseEnd	String	N	暂停结束日期
product.productId	String	Y	订阅订单中新增产品信息的产品 ID
product.productName	String	Y	订阅订单中新增产品信息的产品名称
product.price	String	Y	订阅订单中新增产品信息的价格
product.quantity	String	Y	订阅订单中新增产品信息的数量
product.currency	String	Y	订阅订单中新增产品信息的币种
product.lastAmount	String	Y	订阅订单中新增产品信息的最后一次扣款金额
product.lastDate	String	Y	订阅订单中新增产品信息的最后一次扣款时间
product.nextAmount	String	Y	订阅订单中新增产品信息的下次扣款金额
product.nextDate	String	Y	订阅订单中新增产品信息的下次扣款时间

九、已订阅订单中商品信息修改

{url}/router/subscription/product/modify

请求方式：POST

Header:
sign:sha256(RequestBody +"secretkey")

{
  "terminalId": "240000840001",
  "subscriptionId": "S24111014002252200004812",
  "productId": "SP0aHj8Ig9pdh6NLrgpv",
  "price": "1",
  "quantity": "1"，
  "priceAdjustmentStrategy": null，
}

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 平台提供的终端号
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
productId	String	Y	Payinsider 平台的产品 ID
price	Integer	Y	产品价格
quantity	Number	Y	产品数量
priceAdjustmentStrategy	Integer	N	价格调整策略 不传值:不调整; 1.立即调整; 2.调整至下期扣款;

{
    "msg": "操作成功",
    "code": 200,
    "data": {
    	"terminalId": "240000290002",
    	"recurringToken": "21f5d4f7c2e0e42d66d71af9cf35bacca4cb98a28b7a37f2ab373feb2fe7ef66",
    	"subscriptionId": "S2410251728094370001d416",
    	"piCustomerId": "CI0aHNUKIOBEPP0ny2cc",
    	"status": "1",
    	"cancel": false,
    	"expectedCancelDate": "",
    	"pause": ture,
    	"expectedPauseStart": "2024-10-30",
    	"expectedPauseEnd": "2024-11-07",
        "product": {
            "productId": "SP0aHHcffdUXcjfpfPS6",
            "productName": "prod2",
            "price": 20,
            "quantity": 3,
            "currency": "USD",
            "lastAmount": 3,
            "lastDate": "2024-10-25",
            "nextAmount": 57,
            "nextDate": "2024-10-30"
        }
    }
}

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 提供的终端号
recurringToken	String	Y	Payinsider 订阅 Token
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
piCustomerId	String	Y	Payinsider 平台订阅用户 ID
status	String	Y	订阅状态：1.激活订阅 3.取消订阅 4.暂停订阅
cancel	boolean	Y	是否发起取消
expectedCancelDate	String	N	计划取消日期

pause boolean Y 是否发起暂停 |expectedPauseStart | String | N | 暂停开始日期| |expectedPauseEnd | String | N | 暂停结束日期| |product.productId | String | Y | 订阅订单中修改产品信息的产品 ID| |product.productName | String | Y | 订阅订单中修改产品信息的产品名称| |product.price | String | Y | 订阅订单中修改产品信息的价格| |product.quantity | String | Y | 订阅订单中修改产品信息的数量| |product.currency | String | Y | 订阅订单中修改产品信息的币种| |product.lastAmount | String | Y | 订阅订单中修改产品信息的最后一次扣款金额| |product.lastDate | String | Y | 订阅订单中修改产品信息的最后一次扣款时间| |product.nextAmount | String | Y | 订阅订单中修改产品信息的下次扣款金额| |product.nextDate | String | Y | 订阅订单中修改产品信息的下次扣款时间|

十、已订阅订单中商品信息删除

请求地址：{url}/router/subscription/product/remove

请求方式：POST

Header:
sign:sha256(RequestBody +"secretkey")

{
"terminalId": "240000840001",
"subscriptionId": "S24111014002252200004812",
"productId": "SP0aHj8Ig9pdh6NLrgpv",
"priceAdjustmentStrategy":null,
}

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 平台提供的终端号
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
productId	String	Y	Payinsider 平台的产品 ID
priceAdjustmentStrategy	Integer	N	不传值:不调整; 1.立即调整

{
    "msg": "操作成功",
    "code": 200,
    "data": {
    	"terminalId": "240000290002",
    	"recurringToken": "21f5d4f7c2e0e42d66d71af9cf35bacca4cb98a28b7a37f2ab373feb2fe7ef66",
    	"subscriptionId": "S2410251728094370001d416",
    	"piCustomerId": "CI0aHNUKIOBEPP0ny2cc",
    	"status": "1",
    	"cancel": false,
    	"expectedCancelDate": "",
    	"pause": ture,
    	"expectedPauseStart": "2024-10-30",
    	"expectedPauseEnd": "2024-11-07",
        "product": {
            "productId": "SP0aHHcffdUXcjfpfPS6"
        }
    }
}

返回参数：

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 提供的终端号
recurringToken	String	Y	Payinsider 订阅 Token
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
piCustomerId	String	Y	Payinsider 平台订阅用户 ID
status	String	Y	订阅状态：1.激活订阅 3.取消订阅 4.暂停订阅
cancel	boolean	Y	是否发起取消
expectedCancelDate	String	N	计划取消日期
pause	boolean	Y	是否发起暂停
expectedPauseStart	String	N	暂停开始日期
expectedPauseEnd	String	N	暂停结束日期
product.productId	String	Y	订阅订单中删除产品信息的产品 ID

十一、订阅推送-暂停订阅

商户手动在 Payinsider 后台操作暂停订阅后会发送异步推送， 推送共 5 次，首次在完成操作时异步推送，后续在 5 分钟、10 分钟、 15 分钟、30 分钟各推送一次，推送后需要使用完整 json 报文 +secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值 进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止 推送。示例代码如下：

{
  "event": "subscription.paused",
  "terminalId": "240000290002",
  "recurringToken": "21f5d4f7c2e0e42d66d71af9cf35bacca4cb98a28b7a37f2ab373feb2fe7ef66",
  "subscriptionId": "S2410251728094370001d416",
  "piCustomerId": "CI0aHNUKIOBEPP0ny2cc",
  "status": "4"
}

字段名	数据类型	是否必填	描述
event	String	Y	subscription.paused
terminalId	String	Y	Payinsider 提供的终端号
recurringToken	String	Y	订阅订单 token 值
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
piCustomerId	String	Y	订阅用户 ID
status	String	Y	订阅状态：1.激活订阅 3.取消订阅 4.暂停订阅

十二、订阅推送-取消订阅

商户手动在 Payinsider 后台操作取消订阅后会发送异步推送， 推送共 5 次，首次在完成操作时异步推送，后续在 5 分钟、10 分钟、 15 分钟、30 分钟各推送一次，推送后需要使用完整 json 报文 +secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值 进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止 推送。示例代码如下：

{
  "event": "subscription.cancelled",
  "terminalId": "240000290002",
  "recurringToken": "21f5d4f7c2e0e42d66d71af9cf35bacca4cb98a28b7a37f2ab373feb2fe7ef66", "subscriptionId": "S2410251728094370001d416",
  "piCustomerId": "CI0aHNUKIOBEPP0ny2cc",
  "status": "3"
}

字段名	类型	是否必填	描述
event	String	Y	subscription.cancelled
terminalId	String	Y	Payinsider 提供的终端号
recurringToken	String	Y	订阅订单 token 值
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
piCustomerId	String	Y	订阅用户 ID
status	String	Y	订阅状态：1.激活订阅 3. 取消订阅 4.暂停订阅

十三、订阅推送-恢复订阅

商户手动在 Payinsider 后台操作恢复订阅后会发送异步推送， 推送共 5 次，首次在完成操作时异步推送，后续在 5 分钟、10 分钟、 15 分钟、30 分钟各推送一次，推送后需要使用完整 json 报文 +secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值 进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止 推送。示例代码如下：

{
  "event": "subscription.product.add",
  "terminalId": "240000290002",
  "recurringToken": "21f5d4f7c2e0e42d66d71af9cf35bacca4cb98a28b7a37f2ab373feb2fe7ef66",
  "subscriptionId": "S2410251728094370001d416",
  "piCustomerId": "CI0aHNUKIOBEPP0ny2cc",
  "status": "1"
}

字段名	类型	是否必填	描述
event	String	Y	subscription.resumed
terminalId	String	Y	Payinsider 提供的终端号
recurringToken	String	Y	订阅订单 token 值
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
piCustomerId	String	Y	订阅用户 ID
status	String	Y	订阅状态：1.激活订阅 3. 取消订阅 4.暂停订阅

十四、订阅推送-订阅更新

商户手动在 Payinsider 后台操作触发变更订阅后会发送异步推送，推送共 5 次，首次在完成操作时异步推送，后续在 5 分钟、10 分钟、15 分钟、30 分钟各推送一次，推送后需要使用完整 json 报文+secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止推送。示例

代码如下：

{
  "event": "subscription.updated",
  "terminalId": "240000290002",
  "recurringToken": "21f5d4f7c2e0e42d66d71af9cf35bacca4cb98a28b7a37f2ab373feb2fe7ef66",
  "subscriptionId": "S2410251728094370001d416",
  "piCustomerId": "CI0aHNUKIOBEPP0ny2cc",
  "status": "1",
  "cancel": false,
  "expectedCancelDate": "",
  "pause": ture,
  "expectedPauseStart": "2024-10-30",
  "expectedPauseEnd": "2024-11-07"
}

字段名	数据类型	是否必填	描述
event	String	Y	subscription.resumed
terminalId	String	Y	Payinsider 提供的终端号
recurringToken	String	Y	订阅订单 token 值
subscriptionId	String	Y	订阅订单在 Payinsider 的订阅 ID
piCustomerId	String	Y	订阅用户 ID
status	String	Y	订阅状态：1.激活订阅 3.取消订阅 4.暂停订阅
cancel	boolean	Y	是否发起取消
expectedCancelDate	String	N	计划取消日期
pause	boolean	Y	是否发起暂停
expectedPauseStart	String	N	暂停开始日期
expectedPauseEnd	String	N	暂停结束日期

十五、订阅推送-已订阅订单中商品信息新增推送

商户手动在 Payinsider 后台操作已订阅订单中的新增商品信息 后会发送异步推送，推送共 5 次，首次在完成操作时异步推送，后续 在 5 分钟、10 分钟、15 分钟、30 分钟各推送一次，推送后需要使 用完整 json 报文+secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止推送。示例代码如下：

{
  "event": "subscription..product.add",
  "terminalId": "240000290002",
  "recurringToken": "52430a5066f28707a406ddf6c7e60442f618f78d167765cbfede4d28b0b3b73d",
  "subscriptionId": "S2410251504243400001d121",
  "piCustomerId": "CI0aHNUKIOBEPP0ny2cc",
  "status": "1",
  "product": {
    "productId": "SP0aHj8Ig9pdh6NLrgpv",
    "productName": "prod2",
    "price": 20,
    "quantity": 3,
    "currency": "USD",
    "lastAmount": 3,
    "lastDate": "2024-10-25 15:04:18",
    "nextAmount": 57,
    "nextDate": "2024-10-30 15:04:18"
  }
}

字段名	类型	是否必填	描述
event	String	Y	subscription.product.add
terminalId	String	Y	Payinsider 提供的终端号
recurringToken	String	Y	Payinsider 平台对应的商品 ID
subscriptionId	String	Y	商品名称
piCustomerId	String	Y	订阅用户 ID
status	String	Y	订阅状态：1.激活订阅 3.取消订阅 4.暂停订阅
product.productId	String	Y	已订阅订单中产品信息的产品 ID
product.productName	String	Y	已订阅订单中产品信息的产品名称
product.price	String	Y	已订阅订单中产品信息的价格
product.quantity	String	Y	已订阅订单中产品信息的数量
product.currency	String	Y	已订阅订单中产品信息的币种
product.lastAmount	String	Y	已订阅订单中产品信息的最后一次扣款金额
product.lastDate	String	Y	已订阅订单中产品信息的最后一次扣款时间
product.nextAmount	String	Y	已订阅订单中产品信息的下次扣款金额
product.nextDate	String	Y	已订阅订单中产品信息的下次扣款时间

十六、订阅推送-已订阅订单中商品信息修改推送

商户手动在 Payinsider 后台操作已订阅订单中的修改商品信息 后会发送异步推送，推送共 5 次，首次在完成操作时异步推送，后续 在 5 分钟、10 分钟、15 分钟、30 分钟各推送一次，推送后需要使 用完整 json 报文+secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止推送。示例代码如下：

{
  "event": "subscription.product.updated",
  "terminalId": "240000290002", "recurringToken": "52430a5066f28707a406ddf6c7e60442f618f78d167765cbfede4d28b0b3b73d",
  "subscriptionId": "S2410251504243400001d121",
  "piCustomerId": "CI0aHNUKIOBEPP0ny2cc",
  "status":"1",
  "product": {
    "productId": "SP0aHj8Ig9pdh6NLrgpv",
    "productName": "prod2",
    "price": 20,
    "quantity": 3,
    "currency": "USD",
    "lastAmount": 3,
    "lastDate": "2024-10-25 15:04:18",
    "nextAmount": 57,
    "nextDate": "2024-10-30 15:04:18"
  }
}

字段名	数据类型	是否必填	描述
event	String	Y	subscription.product.updated
terminalId	String	Y	Payinsider 提供的终端号
recurringToken	String	Y	Payinsider 平台对应的商品 ID
subscriptionId	String	Y	商品名称
piCustomerId	String	Y	订阅用户 ID
status	String	Y	订阅状态：1.激活订阅 3.取消订阅 4.暂停订阅
product.productId	String	Y	已订阅订单中产品信息的产品 ID
product.productName	String	Y	已订阅订单中产品信息的产品名称
product.price	String	Y	已订阅订单中产品信息的价格
product.quantity	String	Y	已订阅订单中产品信息的数量
product.currency	String	Y	已订阅订单中产品信息的币种
product.lastAmount	String	Y	已订阅订单中产品信息的最后一次扣款金额
product.lastDate	String	Y	已订阅订单中产品信息的最后一次扣款时间
product.nextAmount	String	Y	已订阅订单中产品信息的下次扣款金额
product.nextDate	String	Y	已订阅订单中产品信息的下次扣款时间

十七、订阅推送-已订阅订单中商品信息删除推送

商户手动在 Payinsider 后台操作已订阅订单中的删除商品信息 后会发送异步推送，推送共 5 次，首次在完成操作时异步推送，后续 在 5 分钟、10 分钟、15 分钟、30 分钟各推送一次，推送后需要使 用完整 json 报文+secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止推送。示例代码如下：

{
  "event": "subscription.product.remove",
  "terminalId": "240000290002",
  "recurringToken": "52430a5066f28707a406ddf6c7e60442f618f78d167765cbfede4d28b0b3b73d",
  "subscriptionId": "S2410251504243400001d121",
  "piCustomerId": "CI0aHNUKIOBEPP0ny2cc",
  "status":"1",
  "product": {
    "productId": "SP0aHj8Ig9pdh6NLrgpv",
    "productName": "prod2",
    "price": 20,
    "quantity": 3,
    "currency": "USD",
    "lastAmount": 3,
    "lastDate": "2024-10-25 15:04:18",
    "nextAmount": 57,
    "nextDate": "2024-10-30 15:04:18"
  }
}

字段名	数据类型	是否必填	描述
event	String	Y	subscription.product.remove
terminalId	String	Y	Payinsider 提供的终端号
recurringToken	String	Y	Payinsider 平台对应的商品 ID
subscriptionId	String	Y	商品名称
piCustomerId	String	Y	订阅用户 ID
status	String	Y	订阅状态：1.激活订阅 3.取消订阅 4.暂停订阅
product.productId	String	Y	已订阅订单中产品信息的产品 ID
product.productName	String	Y	已订阅订单中产品信息的产品名称
product.price	String	Y	已订阅订单中产品信息的价格
product.quantity	String	Y	已订阅订单中产品信息的数量
product.currency	String	Y	已订阅订单中产品信息的币种
product.lastAmount	String	Y	已订阅订单中产品信息的最后一次扣款金额
product.lastDate	String	Y	已订阅订单中产品信息的最后一次扣款时间
product.nextAmount	String	Y	已订阅订单中产品信息的下次扣款金额
product.nextDate	String	Y	已订阅订单中产品信息的下次扣款时间

商品管理 API

一、商品管理说明

商品管理模块是 Payinsider 平台的核心功能之一，它允许用户统一管理其商品，并为商品设置订阅规则、优惠券、税费等附加属性。 本 API 专为商品的新增、修改及删除操作提供了便捷的对接功能。 注意：在商品管理中，商户预设的产品价格、说明等信息，其修改仅会作用于首次订阅时的取值，而不会影响后续续订的价格取值。 若需调整订阅订单的续订价格，请利用“订阅管理”中的“已订阅订单商品信息管理”功能（该功能当前仅开放于 Payinsider 管理平台， 暂未提供 API 接口）。管理平台处理完相关信息后，会自动将更新推送至商户指定的 Url。

二、商品新增

请求地址：{url}/router/subProductManage/add

请求方式：POST

Header:
sign:sha256("merchantId" +"secretkey")

{
  "merchantId": "24000084",
  "terminalId": "240000840001",
  "productName": "test5",
  "pictureLogo": "http://dummyimage.com/400x400", "pricingModel": "1",
  "price": "100",
  "priceIncludesTax": "1",
  "currency": "USD",
  "subPeriod": "1",
  "customValue": "",
  "customPeriod": "",
  "dosage": "", "dosageUnit": "",
  "trialPeriod": "",
  "trialIncludePayment": "",
  "trialPeriodDays": "",
  "trialPeriodPrice": "",
  "status": "1"，
  "sign": "ejiefjaij23588u865408jlwkajio0098734"
}

字段名	数据类型	是否必填	描述
merchantId	String(32)	Y	Payinsider 平台提供的商户号
terminalId	String(100)	Y	Payinsider 提供的终端号
productName	String(100)	Y	商品名称,不可包含特殊字符
pictureLogo	String(300)	Y	商品图片链接
pricingModel	String(1)	Y	订阅收费方式(1:周期 2:一次性 3:用户量 4:用量)
price	String(10)	Y	商品金额
priceIncludesTax	String(1)	N	金额是否含税(1:是 2:否)
currency	String(3)	Y	商品币种
subPeriod	String(1)	N	订阅周期(1:天 2:周 3:月 4:季度 5:半年 6:年 7:自定义)
customValue	String(3)	N	订阅周期自定义值
customPeriod	String(1)	N	自定义周期(1:天 2:周 3:月)
dosage	String(3)	N	用量(按用户量或按用量付费的用量)
dosageUnit	String(3)	N	用量单位(用于按用量付款场景)
trialPeriod	String(1)	N	试用期启用(1:开启 2：关闭)
trialIncludePayment	String(1)	N	试用类型(1:试用期费用不包含在首次扣款 2:包含)
trialPeriodDays	String(3)	N	试用期天数
trialPeriodPrice	String(10)	N	试用期价格
status	String(1)	Y	状态(1:启用 2:停用)

{
  "msg": "操作成功",
  "code": 200,
  "data": [
    {
      "productId": "SP0aJ5nqXQ55JkpN9FNY",
      "productName": "test110604",
      "terminalId": "240000840001"
    }
  ]
}

字段名	数据类型	是否必填	描述
terminalId	String(100)	Y	Payinsider 提供的终端号
productId	String(20)	Y	Payinsider 平台对应的商品 ID
productName	String(100)	Y	商品名称

三、商品修改

请求地址：{url}/router/subProductManage/modify

请求方式：POST

Header:
sign:sha256("merchantId" + "productId" +"secretkey")
{ "merchantId": "24000084", "terminalId": "240000840001", "productName": "test8", "productId": "SP16e36543ad720305", "pictureLogo": "http://dummyimage.com/400x400", "pricingModel": "1", "price": "999", "priceIncludesTax": "1", "currency": "USD", "subPeriod": "1", "customValue": "", "customPeriod": "", "dosage": "",
60
"dosageUnit": "", "trialPeriod": "", "trialIncludePayment": "", "trialPeriodDays": "", "trialPeriodPrice": "", "status": 1
}

字段名	数据类型	是否必填	描述
merchantId	String(32)	Y	Payinsider 平台提供的商户号
terminalId	String(100)	Y	Payinsider 提供的终端号
productId	String(20)	Y	Payinsider 平台对应的商品 ID
productName	String(100)	Y	商品名称,不可包含特殊字符
pictureLogo	String(300)	Y	商品图片链接
pricingModel	String(1)	Y	订阅收费方式(1:周期 2:一次性 3:用户量 4:用量)
price	String(10)	Y	商品金额
priceIncludesTax	String(1)	N	金额是否含税(1:是 2:否)
currency	String(3)	Y	商品币种
subPeriod	String(1)	N	订阅周期(1:天 2:周 3:月 4:季度 5:半年 6:年 7:自定义)
customValue	String(3)	N	订阅周期自定义值
customPeriod	String(1)	N	自定义周期(1:天 2:周 3:月)
dosage	String(3)	N	用量(按用户量或按用量付费的用量)
dosageUnit	String(3)	N	用量单位(用于按用量付款场景)
trialPeriod	String(1)	N	试用期启用(1:开启 2：关闭)
trialIncludePayment	String(1)	N	试用类型(1:试用期费用不包含在首次扣款 2:包含)
trialPeriodDays	String(3)	N	试用期天数
trialPeriodPrice	String(10)	N	试用期价格
status	String(1)	Y	状态(1:启用 2:停用)

{
  "msg": "操作成功", "code": 200
}

四、商品删除

请求地址：{url}/router/subProductManage/delete

请求方式：POST

Header:

sign:sha256("merchantId" + "productId" +"secretkey")

{
  "merchantId": "24000084",
  "terminalId": "240000840001",
  "productId": "SP0aHG5qDG2kGXE0Jiid"
}

字段名	数据类型	是否必填	描述
merchantId	String(32)	Y	Payinsider 平台提供的商户号
terminalId	String(100)	Y	Payinsider 提供的终端号
productId	String(20)	Y	Payinsider 平台对应的商品 ID

返回示例：
{
"msg": "操作成功", "code": 200
}

五、获取商品详情信息

请求地址：{url}/router/subProductManage/details

请求方式：POST

Header:
sign:sha256("merchantId" + "productId" +"secretkey")

{
  "merchantId": "24000084",
  "terminalId": "240000840001",
  "productId": "SP0aHG5qDG2kGXE0Jiid"
}

请求参数：

字段名	数据类型	是否必填	描述
merchantId	String(32)	Y	Payinsider 平台提供的商户号
terminalId	String(100)	Y	Payinsider 提供的终端号
productId	String(20)	Y	Payinsider 平台对应的商品 ID

{ "msg": "操作成功", "code": 200, "data": [
{ "productId": "SP0aIygjJxg0Mdi6k5Qm", "productName": "110504", "merchantId": "24000084", "terminalId": "240000840001", "terminalName": "zeroTestOne", "pricingModel": "1", "amount": 100.0, "priceIncludesTax": 1, "currency": "CNY", "status": "1", "pictureLogo": "", "subPeriod": 3, "customValue": null, "customPeriod": null, "dosage": null,
66
"dosageUnit": "", "trialPeriod": 2, "trialIncludePayment": null, "trialPeriodDays": null, "trialPeriodPrice": null
}
]
}

| 字段名 | 数据类型 | 是否必填 | 描述 | | ------------------- | ----------- | -------- | ----------------------------------------------------------------- | --- | | merchantId | String(32) | Y | 请求 ID,30 分钟内需唯一 | | terminalId | String(100) | Y | Payinsider 提供的终端号，支持多个终端号新增，可用英文逗号分割拼接 | | productId | String(20) | Y | Payinsider 平台对应的商品 ID | | productName | String(100) | Y | 商品名称,不可包含特殊字符 | | terminalName | String(100) | Y | 网站名称 | | pictureLogo | String(300) | Y | 商品图片链接 | | pricingModel | String(1) | Y | 订阅收费方式(1:周期 2:一次性 3:用户量 4:用量) | | price | String(10) | Y | 商品金额 | | priceIncludesTax | String(1) | N | 金额是否含税(1:是 2:否) | | currency | String(3) | Y | 商品币种 | | subPeriod | String(1) | N | 订阅周期(1:天 2:周 3:月 4:季度 5:半年 6:年 7:自定义) | | customValue | String(3) | N | 订阅周期自定义值 | | customPeriod | String(1) | N | 自定义周期(1:天 2:周 3:月) | | dosage | String(3) | N | 用量(按用户量或按用量付费的用量) | | dosageUnit | String(3) | N | 用量单位(用于按用量付款场景) | | trialPeriod | String(1) | N | 试用期启用(1:开启 2：关闭) | | | trialIncludePayment | String(1) | N | 试用类型(1:试用期费用不包含在首次扣款 2:包含) | | trialPeriodDays | String(3) | N | 试用期天数 | | trialPeriodPrice | String(10) | N | 试用期价格 | | status | String(1) | Y | 状态(1:启用 2:停用) |

六、商品推送-新增商品

商户手动在 Payinsider 后台操作新增商品后会发送异步推送，推送共 5 次，首次在完成操作时异步推送，后续在 15 分钟、30 分钟、45 分钟、60 分钟各推送一次，推送后需要使用完整 json 报文+secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值 进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止推送。 示例代码如下：

{
  "event":"subProductAdd.result",
  "productId": "SP0aHHcffdUXcjfpfPS6",
  "productName": "test6",
  "merchantId": "24000084",
  "terminalId": "240000840001",
  "terminalName": "zeroTestOne",
  "pricingModel": "1",
  "price": "100",
  "priceIncludesTax": "1",
  "currency": "USD",
  "status": "1",
  "pictureLogo": "http://dummyimage.com/400x400",
  "subPeriod": "1",
  "customValue": "1",
  "customPeriod": "1",
  "dosage": "1",
  "dosageUnit": "",
  "trialPeriod": "1",
  "trialIncludePayment": "1",
  "trialPeriodDays": "1",
  "trialPeriodPrice": "1"
}

字段名	数据类型	是否必填	描述
event	String(100)	Y	subProductAdd.result
merchantId	String(32)	Y	Payinsider 平台提供的商户号
terminalId	String(100)	Y	Payinsider 提供的终端号，支持多个终端号新增，可用英文逗号分割拼接
terminalName	String(100)	Y	终端号网站名称
productId	String(20)	Y	Payinsider 平台对应的商品 ID
productName	String(100)	Y	商品名称,不可包含特殊字符
pictureLogo	String(300)	Y	商品图片链接
pricingModel	String(1)	Y	订阅收费方式(1:周期 2:一次性 3:用户量 4:用量)
price	String(10)	Y	商品金额
priceIncludesTax	String(1)	N	金额是否含税(1:是 2:否)
currency	String(3)	Y	商品币种
subPeriod	String(1)	N	订阅周期(1:天 2:周 3:月 4:季度 5:半年 6:年 7:自定义)
customValue	String(3)	N	订阅周期自定义值
customPeriod	String(1)	N	自定义周期(1:天 2:周 3:月)
dosage	String(3)	N	用量(按用户量或按用量付费的用量)
dosageUnit	String(3)	N	用量单位(用于按用量付款场景)
trialPeriod	String(1)	N	试用期启用(1:开启 2：关闭)
trialIncludePayment	String(1)	N	试用类型(1:试用期费用不包含在首次扣款 2:包含)
trialPeriodDays	String(3)	N	试用期天数
trialPeriodPrice	String(10)	N	试用期价格
status	String(1)	Y	状态(1:启用 2:停用)

七、商品推送-修改商品

商户手动在 Payinsider 后台操作修改商品后会发送异步推送，推送共 5 次，首次在完成操作时异步推送，后续在 15 分钟、30 分钟、45 分钟、60 分钟各推送一次，推送后需要使用完整 json 报文+secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值 进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止推送。示例代码如下：

{
  "event":"subProductModify.result",
  "productId": "SP0aHHcffdUXcjfpfPS6",
  "productName": "test6",
  "merchantId": "24000084",
  "terminalId": "240000840001",
  "terminalName": "zeroTestOne",
  "pricingModel": "1",
  "price": "100",
  "priceIncludesTax": "1",
  "currency": "USD",
  "status": "1",
  "pictureLogo": "http://dummyimage.com/400x400",
  "subPeriod": "1",
  "customValue": "1",
  "customPeriod": "1",
  "dosage": "1",
  "dosageUnit": "",
  "trialPeriod": "1",
  "trialIncludePayment": "1",
  "trialPeriodDays": "1",
  "trialPeriodPrice":"1"
}

字段名	数据类型	是否必填	描述
event	String(100)	Y	subProductModify.result
merchantId	String(32)	Y	Payinsider 平台提供的商户号
terminalId	String(100)	Y	Payinsider 提供的终端号，支持多个终端号新增，可用英文逗号分割拼接
terminalName	String(100)	Y	终端号网站名称
productId	String(20)	Y	Payinsider 平台对应的商品 ID
productName	String(100)	Y	商品名称,不可包含特殊字符
pictureLogo	String(300)	Y	商品图片链接
pricingModel	String(1)	Y	订阅收费方式(1:周期 2:一次性 3:用户量 4:用量)
price	String(10)	Y	商品金额
priceIncludesTax	String(1)	N	金额是否含税(1:是 2:否)
currency	String(3)	Y	商品币种
subPeriod	String(1)	N	订阅周期(1:天 2:周 3:月 4:季度 5:半年 6:年 7:自定义)
customValue	String(3)	N	订阅周期自定义值
customPeriod	String(1)	N	自定义周期(1:天 2:周 3:月)
dosage	String(3)	N	用量(按用户量或按用量付费的用量)
dosageUnit	String(3)	N	用量单位(用于按用量付款场景)
trialPeriod	String(1)	N	试用期启用(1:开启 2：关闭)
trialIncludePayment	String(1)	N	试用类型(1:试用期费用不包含在首次扣款 2:包含)
trialPeriodDays	String(3)	N	试用期天数
trialPeriodPrice	String(10)	N	试用期价格
status	String(1)	Y	状态(1:启用 2:停用)

八、商品推送-删除商品

商户手动在 Payinsider 后台操作删除商品后会发送异步推送，推送共 5 次，首次在完成操作时异步推送，后续在 15 分钟、30 分钟、45 分钟、60 分钟各推送一次，推送后需要使用完整 json 报文+secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值 进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止推送。示例代码如下：

{
  "event":"subProductDelete.result",
  "productId": "SP0aHHcffdUXcjfpfPS6",
  "productName": "test6",
  "merchantId": "24000084",
  "terminalId": "240000840001",
  "terminalName": "zeroTestOne",
  "pricingModel": "1",
  "price": "100",
  "priceIncludesTax": "1",
  "currency": "USD",
  "status": "1",
  "pictureLogo": "http://dummyimage.com/400x400",
  "subPeriod": "1",
  "customValue": "1",
  "customPeriod": "1",
  "dosage": "1",
  "dosageUnit": "",
  "trialPeriod": "1",
  "trialIncludePayment": "1",
  "trialPeriodDays": "1",
  "trialPeriodPrice": "1"
}

字段名	数据类型	是否必填	描述
event	String(100)	Y	subProductDelete.result
merchantId	String(32)	Y	Payinsider 平台提供的商户号
terminalId	String(100)	Y	Payinsider 提供的终端号，支持多个终端号新增，可用英文逗号分割拼接
terminalName	String(100)	Y	终端号网站名称
productId	String(20)	Y	Payinsider 平台对应的商品 ID
productName	String(100)	Y	商品名称,不可包含特殊字符
pictureLogo	String(300)	Y	商品图片链接
pricingModel	String(1)	Y	订阅收费方式(1:周期 2:一次性 3:用户量 4:用量)
price	String(10)	Y	商品金额
priceIncludesTax	String(1)	N	金额是否含税(1:是 2:否)
currency	String(3)	Y	商品币种
subPeriod	String(1)	N	订阅周期(1:天 2:周 3:月 4:季度 5:半年 6:年 7:自定义)
customValue	String(3)	N	订阅周期自定义值
customPeriod	String(1)	N	自定义周期(1:天 2:周 3:月)
dosage	String(3)	N	用量(按用户量或按用量付费的用量)
dosageUnit	String(3)	N	用量单位(用于按用量付款场景)
trialPeriod	String(1)	N	试用期启用(1:开启 2：关闭)
trialIncludePayment	String(1)	N	试用类型(1:试用期费用不包含在首次扣款 2:包含)
trialPeriodDays	String(3)	N	试用期天数
trialPeriodPrice	String(10)	N	试用期价格
status	String(1)	Y	状态(1:启用 2:停用)

用户管理 API

一、用户管理功能介绍

针对订阅类交易的用户，进行用户信息新增、修改等。本 API 文档提供用户新增 API 接口，同时商户可在 Payinsider 管理平台对 用户进行新增、修改等操作，Payinsider 会在操作后推送对应信息至 商户指定 Url。 注：支持 PI 自动创建用户，在初始化页面时进行传参处理，可 参考第二章自定义卡收集对接代码。

二、用户新增

请求地址：{url}/router/subscription/createCustom

请求方式：POST

Header:
sign:sha256("merchantId" +"secretkey")
{ "merchantId": "24000001", "customerFirstName": "dddd", "customerLastName": "fffff", "customerEmail": "testApissss@qq.com", "terminalId": "240000010019", "customerBillingEmail": "testApissss@qq.com", "customerBillingPhone": "14858647130", "customerBillingAddress": "青海省北宁市清浦区", "customerBillingCountry": "US", "customerBillingState": "RA", "customerBillingCity": "西口市", "customerBillingZip": "518000"
}

字段名	数据类型	是否必填	描述
merchantId	String	Y	Payinsider 平台提供的商户号
customerFirstName	String	Y	用户 FirstName
customerLastName	String	Y	用户 LastName
customerEmail	String	Y	用户邮箱
terminalId	String	Y	Payinsider 提供的终端号
customerBillingEmail	String	Y	用户账单邮箱(支持跟用户邮箱不同)
customerBillingPhone	String	N	用户账单电话号码
customerBillingAddress	String	N	用户账单地址
customerBillingCountry	String	Y	用户账单国家
customerBillingState	String	N	用户账单州,国家为美国时必填
customerBillingCity	String	N	用户账单城市
customerBillingZip	String	Y	用户账单邮编
customerId	String	Y	用户 Id

{
  "msg": "操作成功",
  "code": 200,
  "data": {
    "piCustomerId": "CI0aJ7hlu5esKQopfrSo"
  }
}

字段名	数据类型	是否必填	描述
piCustomerId	String	Y	Payinsider 平台的用户 ID

三、获取用户详情信息

请求地址：{url}/router/subscription/custom

请求方式：POST

Header:
sign:sha256("merchantId" +"secretkey")

{
  "merchantId": "20014578",
  "terminalId": "240000010019",
  "piCustomerId": "CI0aJ7hlu5esKQopfrSo"
}

字段名	数据类型	是否必填	描述
merchantId	String	Y	Payinsider 平台提供的商户号
terminalId	String	Y	Payinsider 提供的终端号
piCustomerId	String	Y	Payinsider 平台对应的用户 ID

{
  "msg": "操作成功",
  "code": 200,
  "data": {
    "piCustomerId": "CI0aHUCr4DtwJAnGjoEe", // PI 用户 ID
    "customerId": "CI0a45634sdJAnGjoEe", // 用户 ID
    "terminalId": "240000010019", // 终端 ID
    "terminalName": "终端(App/网站)", // 终端名称
    "customerEmail": "", // 邮箱
    "customerFirstName": "api-marshal",
    "customerLastName": "api-test",
    "customerBillingEmail": "marshal@pay-insider.com",
    "customerBillingPhone": "14649471025",
    "customerBillingAddress": "江苏省济徽市务川仡佬族苗族自治县",
    "customerBillingCountry": "US",
    "customerBillingState": "esse", "customerBillingCity": "上京市",
    "customerBillingZip": "13972"
  }
}

字段名	数据类型	是否必填	描述
piCustomerId	String	Y	Payinsider 平台对应的用户 ID
customerId	String	Y	用户 ID
customerFirstName	String	Y	用户 FirstName
customerLastName	String	Y	用户 LastName
customerEmail	String	Y	用户邮箱
terminalId	String	Y	Payinsider 提供的终端号
terminalName	String	Y	Payinsider 终端号对应网站名称
customerBillingEmail	String	N	用户账单邮箱(支持跟用户邮箱不同)
customerBillingPhone	String	Y	用户账单电话号码
customerBillingAddress	String	N	用户账单地址
customerBillingCountry	String	Y	用户账单国家
customerBillingState	String	N	用户账单州
customerBillingCity	String	Y	用户账单城市
customerBillingZip	String	N	用户账单邮编

四、用户推送-新增

商户手动在 Payinsider 后台操作新增用户后会发送异步推送，推送共 5 次，首次在完成操作时异步推送，后续在 15 分钟、30 分钟、45 分钟、60 分钟各推送一次，推送后需要使用完整 json 报文+secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值 进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止推送。

示例代码如下：

{ "event": "subCustomAdd.result", "piCustomerId": "CI0aHUCr4DtwJAnGjoEe", "customerId": "CI0aH6465646twJAnGjoEe", "terminalId": "240000010019", "customerEmail": "marshal@pay-insider.com", "customerFirstName": "api-marshal", "customerLastName": "api-test", "customerBillingEmail": "marshal@pay-insider.com", "customerBillingPhone": "14649471025", "customerBillingAddress": "江苏省济徽市务川仡佬族苗族自治县", "customerBillingCountry": "US",
"customerBillingState": "esse", "customerBillingCity": "上京市", "customerBillingZip": "139.176.49.172"
}

字段名	数据类型	是否必填	描述
event	String	Y	subCustomAdd.result
piCustomerId	String	Y	Payinsider 平台对应的用户 ID
customerId	String	Y	用户 ID
customerFirstName	String	Y	用户 FirstName
customerLastName	String	Y	用户 LastName
customerEmail	String	Y	用户邮箱
terminalId	String	Y	Payinsider 提供的终端号
customerBillingEmail	String	N	用户账单邮箱(支持跟用户邮箱不同)
customerBillingPhone	String	Y	用户账单电话号码
customerBillingAddress	String	N	用户账单地址
customerBillingCountry	String	Y	用户账单国家
customerBillingState	String	N	用户账单州
customerBillingCity	String	Y	用户账单城市
customerBillingZip	String	N	用户账单邮编

五、用户推送-修改

商户手动在 Payinsider 后台操作新增用户后会发送异步推送，推送共 5 次，首次在完成操作时异步推送，后续在 15 分钟、30 分钟、45 分钟、60 分钟各推送一次，推送后需要使用完整 json 报文+secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值 进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止推送。

示例代码如下：

{
  "event": "subCustomAdd.result",
  "piCustomerId": "CI0aHUCr4DtwJAnGjoEe",
  "customerId": "CI0aHU645646JAnGjoEe",
  "terminalId": "240000010019",
  "customerEmail": "marshal@pay-insider.com",
  "customerFirstName": "api-marshal",
  "customerLastName": "api-test",
  "customerBillingEmail": "marshal@pay-insider.com",
  "customerBillingPhone": "14649471025",
  "customerBillingAddress": "江苏省济徽市务川仡佬族苗族自治县",
  "customerBillingCountry": "US",
  "customerBillingState": "esse",
  "customerBillingCity": "上京市",
  "customerBillingZip": "139.176.49.172"
}

字段名	数据类型	是否必填	描述
event	String	Y	subCustomModify.result
piCustomerId	String	Y	Payinsider 平台对应的用户 ID
customerId	String	Y	用户 ID
customerFirstName	String	Y	用户 FirstName
customerLastName	String	Y	用户 LastName
customerEmail	String	Y	用户邮箱
terminalId	String	Y	Payinsider 提供的终端号
customerBillingEmail	String	N	用户账单邮箱(支持跟用户邮箱不同)
customerBillingPhone	String	Y	用户账单电话号码
customerBillingAddress	String	N	用户账单地址
customerBillingCountry	String	Y	用户账单国家
customerBillingState	String	N	用户账单州
customerBillingCity	String	Y	用户账单城市
customerBillingZip	String	N	用户账单邮编

优惠券 SDK

一、优惠券功能介绍

商户可在 Payinsider 平台创建对应用户或商品的优惠券，设定规则，在 Payinsider 平台进行优惠券发放，该功能需在商户付款页面配合使用 Payinsider 优惠券组件功能，优惠券组件功能会处理消费者优惠券核销、使用优惠券及金额计算等。

下图示例：

二、页面优惠券功能启用

如需启用，需在初始化页面(new PayinsiderPay())时请把以下字段传值为 true //商品清单是否显示 默认 true 显示,false 不显示

showOrderSummary: true， //优惠券是否展示使用 默认 true 显示

showCoupon: true (注：完整代码可参考第二章自定义卡收集对接)

订单管理

一、退款管理

Payinsider 提供退款 API 接口给到用户进行管理退款，也可通过 Payinsider 后台直接发起退款。

请求地址：{url}/router/direct/refund

请求方式：POST

{
  "requestId": "1724315547385",
  "timestamp": "1724315547385",
  "sign": "6d90aeec6d67ea589a567896090583da3da93c92fd6d1c42e4671f3007ab5842", "terminalId": "240000290002",
  "orderNo": "1724309379857",
  "transNo": "",
  "currency": "USD",
  "amount": "1.00",
  "reason":"goods return"
}

字段名	数据类型	是否必填	描述
requestId	String(32)	Y	请求 ID,30 分钟内需要唯一
timestamp	Timestamps1	Y	毫秒级时间戳，按照 UTC 时间生成，如：1725107628725
sign	String	Y	参与 sign 值计算的字段及拼接顺序为：amount、currency、orderNo、requestId、terminalId、timestamp、transNo
terminalId	String	Y	Payinsider 提供的终端号
amount	String(10)	Y	退款金额,金额需小于订单金额，校验该字段中仅能包含数字和小数点
currency	String(3)	Y	退款币种
transNo	String(50)	Y(二者至少传一个)	Payinsider 订单号
orderNo	String(25)	Y(二者至少传一个)	商户订单 ID
reason	String	Y	退款原因

返回参数	描述
refId	商户订单号
orderId	payinsider 订单 ID
transNo	payinsider 交易 ID
gatewayId	支付渠道退款 ID
refundId	payinsider 退款 ID
amount	退款金额
currency	退款币种
status	退款状态（1:成功，2:失败，3:待处理）
acquirer	上游供应商
acquirerResponseCode	上游返回代码
acquirerResponseMessage	上游返回说明
payinsiderResponseCode	payinsider 返回代码
payinsiderResponseMessage	payinsider 返回说明

二、退款查询

请求地址：{url}/router/direct/refund/inquiry

请求方式：POST

Header:
sign:sha256(RequestBody +"secretkey")

{
  "terminalId": "1724315547385",
  "refundId": "1724315547385",
}

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 提供的终端号
refundId	String	Y	Payinsider 提供的退款 ID

返回参数	数据类型	是否必填	描述
refId	String	Y	商户订单号
orderId	String	Y	payinsider 订单 ID
transNo	String	Y	payinsider 交易 ID
gatewayId	String	Y	支付渠道退款 ID
refundId	String	Y	payinsider 退款 ID
amount	String	Y	退款金额
currency	String	Y	退款币种
status	String	Y	退款状态（1:成功，2:失败，3:待处理）
reason	String	Y	退款原因
acquirer	String	Y	上游供应商
acquirerResponseCode	String	Y	上游返回代码
acquirerResponseMessage	String	Y	上游返回说明
payinsiderResponseCode	String	Y	payinsider 返回代码
payinsiderResponseMessage	String	Y	payinsider 返回说明

三、订单查询

请求地址：{url}/router/order/inquiry

请求方式：POST

Header:
sign:sha256(RequestBody +"secretkey")

{
  "terminalId": "1724315547385",
  "refId": "1724315547385",
  "orderId": "1724315547385"
}

字段名	数据类型	是否必填	描述
terminalId	String	Y	Payinsider 提供的终端号
refId	String	Y (二者至少传一个)	商户订单号
orderId	String	Y (二者至少传一个)	Payinsider 提供的订单 ID

返回参数	数据类型	是否必填	描述
refId	String	Y	商户订单号
orderId	String	Y	payinsider 订单 ID
transNo	String	Y	payinsider 交易 ID
gatewayId	String	Y	支付渠道订单号
amount	String	Y	订单金额
currency	String	Y	订单币种
status	String	Y	订单状态（1:成功，2:失败，3:待处理）
acquirer	String	Y	上游供应商
piCustomerId	String	Y	payinsider 消费者 ID
email	String	Y	邮箱
piCustomerId	String	N	payinsider 消费者 ID
recurringType	String	N	订阅交易类型(init:首次订阅，recurring:续费订阅)
recurringToken	String	N	payinsider 订阅 Token
subscriptionId	String	N	payinsider 订阅 ID
acquirerResponseCode	String	Y	上游返回代码
acquirerResponseMessage	String	Y	上游返回说明
payinsiderResponseCode	String	Y	payinsider 返回代码
payinsiderResponseMessage	String	Y	payinsider 返回说明

订单类推送

一、推送说明

推送地址配置：可在 Payinsider 后台，支付管理->终端商城->终端(App/网站)->Webhook 进行配置(以终端维度进行动态配置)

二、交易推送

Payinsider 会在实时交易发生后发送异步推送，推送共 5 次，首次在续订交易完成时异步推送，后续在 5 分钟、10 分钟、15 分钟、30 分钟各推送一次，推送后需要使用完整 json 报文+secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值进行对比验证， 并响应 200 返回码，Payinsider 收到响应后会停止推送。

示例代码

如下：

{
  "event": "trans.result",
  "refId": "202492051179594", "orderId":"O24090200510225100004002",
  "transNo":"T24090200510441300004378",
  "gatewayId": "1830287271275139072",
  "amount": 20.00,
  "currency": "USD",
  "status": 1,
  "acquirer": "XX",
  "acquirerResponseCode": "S",
  "acquirerResponseMessage": "Payment successful",
  "payinsiderResponseCode": "",
  "payinsiderResponseMessage": "",
  "recurringToken": "a056855b4523453452425633eba01f3a4745331874348"，
  "subscriptionId": "S24091014002252200004812",
  "nextRecurringTime":"2024-09-23",
  "piCustomerId"："PDKHYelidihsai",
  "email"："xxx@xx.com",
  "productList":[
    {
      "currency": "USD",
      "lastAmount": 100,
      "lastDate": "2024-11-04",
      "nextAmount": 100,
      "nextDate": "2024-12-04",
      "price": 100,
      "productName": "monthly 100USD",
      "quantity": 1,
      "productId": "SP0aIrehCdJagGgs1hxY",
      "priceIncludesTax": 1,
      "taxAmount": 15,
      "goodsTax": 0.05
    },
    {
      "currency": "USD",
      "lastAmount": 100,
      "lastDate": "2024-11-04",
      "nextAmount": 100,
      "nextDate": "2025-11-04",
      "price": 100,
      "productName": "year 100USD",
      "quantity": 1,
      "productId": "SPiowueqoriuotyuyiu"，
      "priceIncludesTax": 1,
      "taxAmount": 15,
      "goodsTax": 0.05
    }
  ]
}

| 字段名 | 类型 | 描述 | | ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------- | --- | | event | String | 推送事件，交易推送事件为：trans.result | | refId | String | 商户的订单 ID | | orderId | String | Payinsider 的订单 ID | | transNo | String | Payinsider 的交易流水 ID | | gatewayId | String | 支付渠道商交易 ID | | amount | Number | 交易金额 | | currency | String | 交易币种 | | status | Integer | 交易状态：1 成功 2 失败 3 待处理 | | acquirer | String | 支付渠道商名称 | | acquirerResponseCode | String | 支付渠道返回响应码 | | acquirerResponseMessage | String | 支付渠道返回响应信息 | | payinsiderResponseCode | String | Payinsider 返回响应码 | | payinsiderResponseMessage | String | Payinsider 返回响应信息 | | 以下字段为订阅交易推送附加字段 | | recurringToken | String | Payinsider 订阅 Token | | subscriptionId | String | Payinsider 订阅群组 ID | | nextRecurringTime | String | 订阅交易下次扣款日期 | | piCustomerId | String | Payinsider 平台订阅用户 ID | | Email | String | 消费者邮箱 | | productList | Array | productList 下的字段为多组产品数据，数组格式，支持多产品一笔订单订阅，里面包含多个 key 值，具体见以下 productList.xxx 字段 | | productList.currency | String | 币种 | | productList.lastAmount | String | 本次扣款金额 | | productList.lastDate | String | 本次扣款日期 | | productList.nextAmount | String | 下一次扣款金额 | | productList.nextDate | String | 下一次扣款日期 | | productList.price | String | 产品设定价格 | | productList.productName | String | 产品名称 | | productList.quantity | String | 产品数量 | | productList.productId | String | 产品 | ID | | productList.priceIncludesTax | Integer | 1 含税，2 否 | | productList.taxAmount | String | 税额 | | productList.goodsTax | String | 税率 |

三、退款推送

Payinsider 会在退款发生后发送异步推送，推送共 5 次，首次在退款完成时异步推送，后续在 5 分钟、10 分钟、15 分钟、30 分钟各推送一次，推送后需要使用完整 json 报文+secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止推送。

示例代码如下：

{
  "event": "refund.result",
  "refId": "1724309379857",
  "orderId": "O2408221449480190001d298",
  "transNo": "T2408221450337640001d889",
  "gatewayId": "1826512268444434432",
  "refundId": "U2408221450337640001d889",
  "amount": 193,
  "currency": "USD",
  "status": 1,
  "acquirer": "XXX",
  "acquirerResponseCode": "S",
  "acquirerResponseMessage": "Refund successful",
  "payinsiderResponseCode": "",
  "payinsiderResponseMessage": ""
}

字段名	类型	描述
event	String	推送事件，退款推送事件为：refund.result
refId	String	商户的订单 ID
orderId	String	Payinsider 的订单 ID
transNo	String	Payinsider 的交易流水 ID
gatewayId	String	支付渠道商退款 ID
refundId	String	Payinsider 退款 ID
amount	Number	退款金额
currency	String	退款币种
status	integer	退款状态：1 成功 2 失败 3 待处理
acquirer	String	支付渠道商名称
acquirerResponseCode	String	支付渠道返回响应码
acquirerResponseMessage	String	支付渠道返回响应信息
payinsiderResponseCode	String	Payinsider 返回响应码
payinsiderResponseMessage	String	Payinsider 返回响应信息

四、拒付推送

Payinsider 会在收到上游拒付信息后发送异步推送，推送共 5 次，后续在 5 分钟、10 分钟、15 分钟、30 分钟各推送一次，推送后需要使用完整 json 报文+secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止推送。

示例代码如下：

{
  "event": "dispute.result",
  "refId": "1724309379857",
  "orderId": "O2408221449480190001d298",
  "gatewayId": "1826512268444434432",
  "arn": "32707574195000183564283",
  "amount": 193,
  "currency": "USD",
  "disputeDate": "2024-08-26 08:00:00",
  "dueDate": "2024-09-20 11:45:08",
  "stage": "PRE_ARBITRATION",
  "status": "Pending_Closure",
  "acquirer": "XXX",
  "acquirerResponseCode": "4837",
  "acquirerResponseMessage": "Fraud related chargebacks"
}

字段名	类型	描述
event	String	推送事件，拒付推送事件为：dispute.result
refId	String	商户的订单 ID
orderId	String	Payinsider 的订单 ID
gatewayId	String	支付渠道商订单 ID
arn	String	支付渠道商拒付 ARN
amount	Number	拒付金额
currency	String	拒付币种
disputeDate	Dates	拒付日期：2024-08-26 08:00:00
dueDate	Dates	到期时间：2024-09-20 11:45:08
stage	String	拒付处理阶段：CHARGEBACK 、PRE_ARBITRATION、ARBITRATION
status	String	拒付处理状态:New_Requires_response、NTF_Requires_response、Challenged、Accepted、Reversed、Won、Lost、Pending_Closure、Pending_Decision
acquirer	String	支付渠道商名称
acquirerResponseCode	String	支付渠道拒付代码
acquirerResponseMessage	String	支付渠道拒付描述

五、欺诈推送

Payinsider 会在收到上游欺诈信息后发送异步推送，推送共 5 次，后续在 5 分钟、10 分钟、15 分钟、30 分钟各推送一次，推送后需要使用完整 json 报文+secretkey 进行 SHA256 签名，与推送请求的 Header 中 sign 值进行对比验证，并响应 200 返回码，Payinsider 收到响应后会停止推送。

示例代码如下：

{
  "event": "fraud.result",
  "refId": "1724309379857",
  "orderId": "O2408221449480190001d298",
  "gatewayId": "1826512268444434432",
  "arn": "32707574195000183564283",
  "amount": 193,
  "currency": "USD",
  "cardBrand": "Visa",
  "noticeTime": "2024-09-20 11:45:08",
  "acquirer": "XXX",
  "acquirerResponseCode": "4837",
  "acquirerResponseMessage": "Fraud related chargebacks",
  "fraudId": "xxxxxxxx"
}

字段名	类型	描述
event	String	推送事件，拒付推送事件为：dispute.result
refId	String	商户的订单 ID
orderId	String	Payinsider 的订单 ID
gatewayId	String	支付渠道商订单 ID
arn	String	支付渠道商拒付 ARN
amount	Number	拒付金额
currency	String	拒付币种
cardBrand	String	卡种
noticeTime	Dates	通知时间：2024-08-26 08:00:00
acquirer	String	支付渠道商名称
acquirerResponseCode	String	支付渠道拒付代码
acquirerResponseMessage	String	支付渠道拒付描述
fraudId	String	欺诈 ID

优惠券&税计算

一、计算优惠券&税

请求地址：{url}/router/subCouponTax/details

请求方式：POST

Header:
sign:sha256(RequestBody +"secretkey")
{
    "productList": [
        {
            "productId": "SP0aJ5nqXQ55JkpN9FNY",
            "currency": "USD",
            "productName": "test110604",
            "quantity": 1,
            "price": 100,
            "trialPeriod": 2,  
            "trialIncludePayment": 2,
            "trialPeriodPrice": 80,
            "priceIncludesTax": 1,
            "pricingModel": "1"
        },
        {
            "productId": "SP0aJ5hxGzoSx2Jb5037",
            "currency": "USD",
            "productName": "test110603",
            "quantity": 2,
            "price": 100,
            "trialPeriod": 2,  
            "trialIncludePayment": 2,
            "trialPeriodPrice": 80,
            "priceIncludesTax": 2,
            "pricingModel": "1"
        }
    ],
    "exchangeRate": 1,
    "couponList": [
        "CP0aK555NHMX42BstnVT"
    ],
    "piCustomerId": "CI0aJdTsU0Z01xtZzMYy",
    "terminalId": "240000840001",
    "billingCountry": "US",
    "billingState": "CA",
    "merchantId": "24000084"
}

字段名	数据类型	是否必填	描述
merchantId	String(32)	Y	Payinsider 平台提供的商户号
terminalId	String(100)	Y	Payinsider 提供的终端号
piCustomerId	String	Y	Payinsider 平台订阅用户 ID
couponList	Array	N	优惠券列表，传值优惠券 Id
exchangeRate	String	N	优惠券币种(卖出)到商品币种(买入)汇率，若优惠券为固定金额且币种和商品币种不一致时必填
billingCountry	String(2)	Y	账单国家
billingState	String(40)	N	账单州(如果有收集真实信息需如实填写，影响上游风控)
productList	Array	Y	productList 下的字段为多组产品数据，数组格式，支持多产品一笔订单订阅，里面包含多个 key 值，具体见以下 productList.xxx 字段
productList.currency	String	Y	币种
productList.quantity	String	Y	产品数量
productList.productId	String	Y	产品 ID
productList.price	String	Y	产品设定价格
productList.trialPeriod	String(1)	N	试用期启用(1:开启 2：关闭)，试用期开启，则试用类型和试用期金额字段必填
productList.trialIncludePayment	String(1)	N	试用类型(1:试用期费用不包含在首次扣款 2:包含)
productList.trialPeriodPrice	String(10)	N	试用期价格
productList.priceIncludesTax	String(1)	N	金额是否含税(1:是 2:否)
productList.pricingModel	String(1)	Y	订阅收费方式(1:周期 2:一次性 3:用户量 4:用量)
productList.productName	String(100)	Y	商品名称,不可包含特殊字符

{
    "msg": "操作成功",
    "code": 200,
    "data": {
        "productList": [
            {
                "productId": "SP0aJ5nqXQ55JkpN9FNY",
                "currency": "USD",
                "productName": "test110604",
                "quantity": 1,
                "price": 100,
                "trialPeriod": 2,
                "trialIncludePayment": 2,
                "trialPeriodPrice": 80,
                "priceIncludesTax": 1,
                "taxAmount": 14.50
            },
            {
                "productId": "SP0aJ5hxGzoSx2Jb5037",
                "currency": "USD",
                "productName": "test110603",
                "quantity": 2,
                "price": 100,
                "trialPeriod": 2,
                "trialIncludePayment": 2,
                "trialPeriodPrice": 80,
                "priceIncludesTax": 2,
                "taxAmount": 25.22
            }
        ],
        "piCustomerId": "CI0aJdTsU0Z01xtZzMYy",
        "terminalId": "240000840001",
        "billingCountry": "US",
        "billingState": "CA",
        "merchantId": "24000084",
        "totalTaxAmount": 39.72,
        "goodsTax": 0.1500,
        "amount": 218.55
    }
}

字段名	数据类型	描述
merchantId	String(32)	Payinsider 平台提供的商户号
terminalId	String(100)	Payinsider 提供的终端号
piCustomerId	String	Payinsider 平台订阅用户 ID
billingCountry	String(2)	账单国家
billingState	String(40)	账单州(如果有收集真实信息需如实填写，影响上游风控)
totalTaxAmount	String	总税额
goodsTax	String	商品税率
amount	String	优惠后交易金额(未含税则累加税额)
productList	Array	productList 下的字段为多组产品数据，数组格式，支持多产品一笔订单订阅，里面包含多个 key 值，具体见以下 productList.xxx 字段
productList.currency	String	币种
productList.quantity	String	产品数量
productList.productId	String	产品 ID
productList.price	String	产品设定价格
productList.trialPeriod	String(1)	试用期启用(1:开启 2：关闭)，试用期开启，则试用类型和试用期金额字段必填
productList.trialIncludePayment	String(1)	试用类型(1:试用期费用不包含在首次扣款 2:包含)
productList.trialPeriodPrice	String(10)	试用期价格
productList.priceIncludesTax	String(1)	金额是否含税(1:是 2:否)
productList.taxAmount	String	商品税额
productList.productName	String(100)	商品名称,不可包含特殊字符