集成步骤
1. 实现流程
1.1 获取 clientKey 和 sessionKey
接口详细说明请参阅：接口参数。
(a) 请求API；环境及地址如下：
| 请求环境 | 请求地址 |
| Test | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/applyDropinSession |
| Live | https://pay-gate.payermax.com/aggregate-pay/api/gateway/applyDropinSession |
(b) 从返回值获取 clientKey 和 sessionKey。
注意：
服务端获取到的 clientKey、sessionKey 返回给前端用于组件初始化。
请求Header示例：
{
'Content-Type': 'application/json;charset=utf-8',
'Accept': 'application/json',
'sign': <参考：https://docs-v2.payermax.com/doc-center/developer/config-settings.html>
};请求Body示例：
request.body =
{
"version": "1.1",
"keyVersion": "1",
"requestTime": <替换>,
"merchantNo": <替换>,
"appId": <替换>,
"data": {
"country": "MY",
"currency": "MYR",
"totalAmount":"50",
"userId": "20220622_00086",
"componentList":["APPLEPAY","CARD"]
}
}
response={
"msg": "",
"code": "APPLY_SUCCESS",
"data": {
"sessionKey": "bf2c47b085e24c299e45dd56fd751a70",
"clientKey": "bbd8d2639a7c4dfd8df7d005294390df"
}
}1.2 渲染组件
- 前端示例
下载Demo示例，替换 clientKey 和 sessionKey 后，可以本地打开看到效果。
- 前端集成步骤
(a) 在相关 HTML 页面上引入 CDN 包；
<script src="https://cdn.payermax.com/dropin/js/pmdropin.min.js"></script>(b) 通过 div 标签嵌入一个 iframes；
<div class="frame-card">
<!-- form will be added here -->
</div>(c) 初始化 PayerMax Frames；
// 初始化卡组件
const card = PMdropin.create('card', {
clientKey: "客户端公钥", // 在步骤1.1中获取到的 data.clientKey
sessionKey: "会话令牌", // 在步骤1.1中获取到的 data.sessionKey
sandbox: false, // 默认是 false，即生产环境
hideSaveCard: false, //是否隐藏保存卡信息选项，默认是false展示
hideCardBrands: false, //是否隐藏左上角卡品牌的Logo，默认是false展示
});
// 挂载实例
card.mount('.frame-card'); // 将挂载至匹配到的第一个dom元素上
// 组件加载完成时机
card.on('ready', () => {
// 移除自定义loading
})(d) 监听表单填写状态（可选）；
注意：
状态变更时将实时回调，可以由此决定支付按钮是否可点击。
card.on('form-check', (res) => {
// res.isFormValid 为表单状态 false/true
// true 表示表单校验通过,可尝试支付；false 表示校验未通过，无法点击支付按钮
console.log('[dropin][form-check]:', res)
})(e) 检查是否可支付 & 获取支付 token；
特别提醒：
调用支付接口前务必检查是否可支付；可支付时，将获取到 paymentToken, 用于发起支付接口。
card.emit('setDisabled', true) // 点击支付按钮后冻结表单，防止重复提交支付过程
card.emit('canMakePayment')
.then(res => {
if (res.code === 'APPLY_SUCCESS') {
const paymentToken = res?.data?.paymentToken // 支付 token，支付接口使用
// ❗️发起支付接口
// 商户自己请求后端接口进行下单,
// 商户自己用params构造请求参数，需要带上paymentToken
_postapi('orderAndPay',params).then(res =>{
const code = (res || {}).code
//商户将支付结果返回到前端
if (code == 'APPLY_SUCCESS') {
//支付成功，展示支付结果
} else {
//支付失败，展示支付结果
}
}
card.emit('setDisabled', false) // ❗️支付接口完成后解冻表单
}
})
.catch(err => {
card.emit('setDisabled', false) // 发生异常后解冻表单
})(f) 发起支付，具体可查看1.3中的服务端发起支付。
1.3 商户后台下单
- 下单时机
请在前端回调 card.emit('canMakePayment') 后，当 response.code 为 'APPLY_SUCCESS' 时发起下单请求，此时可从 canMakePayment 方法获取到 paymentToken，用在后续下单接口入参。
- 下单步骤
(a) 户前端向商户后端发起下单，传入 canMakePayment 方法获取到的 paymentToken；
(b) 商户服务端生成订单号（outTradeNo）后向 PayerMax 服务端发起支付请求；
(c) 处理 PayerMax 响应结果。
- 响应处理
服务端下单如果返回 redirectUrl 并且 status=PENDING 时，前端需要打开该 redirectUrl，用户可在该页面做 3ds 校验并完成支付，其他情况直接拿到支付结果。
- API 环境及地址
| 请求环境 | 请求地址 |
| Test | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay |
| Prod | https://pay-gate.payermax.com/aggregate-pay/api/gateway/orderAndPay |
请求Header示例：
sign 字段的取值请参阅【配置与签名】。
{
'Content-Type': 'application/json;charset=utf-8',
'Accept': 'application/json',
'sign': <XXX>
};请求Body示例：
下单详细字段请参阅接口参数。
{
"appId": <替换>,
"version": "1.4",
"merchantNo": <替换>,
"requestTime": "2024-06-05T10:46:01.694+08:00",
"keyVersion": "1",
"data": {
"totalAmount": 77.44,
"country": "HK",
"expireTime": "7200",
"paymentDetail": {
"paymentToken": "332e4cc1af1740aeafe9e7df82aeb5a1",
"buyerInfo": {
"clientIp": "59.82.59.92",
"userAgent": "Chrome"
},
"sessionKey": "86409e2c04b44536a484caa5ce3ce0e9"
},
"frontCallbackUrl": <替换>,
"subject": "GoGeal PTE. LTD.",
"outTradeNo": <商户订单号，需唯一>,
"notifyUrl": <替换>,
"currency": "HKD",
"userId": "3ff0495692d152be96d84dbc9352dc57",
"integrate": "Direct_Payment",
"terminalType": "WEB"
}
}