# 集成步骤

![](https://img-cdn-sg.payermax.com/public/20240801-4389defd-d7ff-4473-8f9e-213b76e0ca85.jpg)

### 1. 实现流程

#### 1.1 获取 clientKey 和 sessionKey

接口详细说明请参阅：[接口参数](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-applyDropinSession/post)。

(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。

::: warning 注意：
服务端获取到的 clientKey、sessionKey 返回给前端用于组件初始化。
:::

请求Header示例：

```json
{
    'Content-Type': 'application/json;charset=utf-8',
    'Accept': 'application/json',
    'sign': <参考：https://docs-v2.payermax.com/202606-version/developer/config-settings.html>
};
```

请求Body示例：

```json
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示例](https://img-cdn-sg.payermax.com/public/20240731-4dc2acec-f6f4-4131-bad2-9096ec84c764.zip)，替换 clientKey 和 sessionKey 后，可以本地打开看到效果。

+ **前端集成步骤**

(a) 在相关 HTML 页面上引入 CDN 包；

```html

```

(b) 通过 div 标签嵌入一个 iframes；

```html

  

```

(c) 初始化 PayerMax Frames；

```js
// 初始化卡组件
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) 监听表单填写状态（可选）；

::: warning 注意：
状态变更时将实时回调，可以由此决定支付按钮是否可点击。
:::

```js
card.on('form-check', (res) => {
  // res.isFormValid 为表单状态 false/true
  // true 表示表单校验通过,可尝试支付；false 表示校验未通过，无法点击支付按钮
  console.log('[dropin][form-check]:', res)
})
```

(e) 检查是否可支付 & 获取支付 token；

::: danger 特别提醒：
调用支付接口前务必检查是否可支付；可支付时，将获取到 `paymentToken`, 用于发起支付接口。
:::

```js
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 字段的取值请参阅【[配置与签名](/202606-version/developer/config-settings.md)】。

```json
{
    'Content-Type': 'application/json;charset=utf-8',
    'Accept': 'application/json',
    'sign': <XXX>
};
```

请求Body示例：

下单详细字段请参阅[接口参数](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay(for-drop-dont-copy-me)/post)。

```json
{
    "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"
	}
}
```
### 2. 其他定制

前端接口详情请参阅【[卡支付前端接口](/202606-version/receipt/front-end-component/configuration-card.md)】文档；前端样式调整请参阅卡支付【[定制化](/202606-version/receipt/front-end-component/customization.md)】文档。