# 发起付款

::: tip  
发起付款接口是在对外付款时必须接入的接口能力。

PayerMax提供了全球`150`余个国家的支付方式，每个支付方式要求的字段可能不同。在接入前，请参考[支付方式列表](https://docs.payermax.com/202606-version/disbursement/payment-methods.md)来明确对接的支付方式。
:::

## 1. 交互流程

```mermaid
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant MServer as 商户服务端
    participant PMServer as PayerMax 服务端

    %% 交易查询流程
    MServer->>PMServer: 1.1 发起单笔付款请求
    PMServer-->>MServer: 1.2 返回受理结果
    PMServer->>MServer: 1.3 通知付款结果
    MServer->>PMServer: 1.4 返回响应
```

## 2. 下单请求

:: warning  注意：
1. 对于不同地区，不同付款方式，付款要素（请求参数）要求有差异。
付款要素可具体参考：[《付款申请模板及填写规范》](https://docs.payermax.com/202606-version/appendix/disbursement/disbursement-application-template.md)；
2. 根据付款要素，构造详细的API参数请参考 [申请付款 API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-paymentOrderPay/post)。

:::

- 参考《付款申请模板及填写规范》-「填写规范」表格，其中粉色背景为必填参数 ，构建API 接口。

- 比如：按照[《付款申请模板及填写规范》](https://docs.payermax.com/202606-version/appendix/disbursement/disbursement-application-template.md)，韩国（KR）的 BANK_TRANSFER 付款方式 payeeInfo.accountInfo.accountNo 为必填，接口请求时则必须传该字段

![](https://img-cdn-sg.payermax.com/public/20260526-a0bb3916-e76a-41e4-90f1-1b9a543a095d.png)

- 您也可在下方选择对接的支付方式来获取您需要送的参数：

*Data unavailable*

 

## 3.下单响应

### 3.1 下单成功响应

当收到响应中`code` = `APPLY_SUCCESS`、`msg` = `Success.`时，代表请求成功，并不代表交易成功。需要根据返回`data`体中的`status`字段来判断交易的状态。详情请参考 [申请付款 API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-paymentOrderPay/post)。

### 3.2 下单失败响应

#### 3.2.1 服务端请求限制

在发起付款申请时，您可能遇到的「**服务端请求限制**」类的错误码如下：

| 分类           | 错误码             | 错误描述                                      | 备注                                                       |
| -------------- | ------------------ | --------------------------------------------- | ---------------------------------------------------------- |
|                | REQ_TIME_OVER_TIME | requestTime effective in two minutes          | 请求时间与服务端偏差超过2分钟，请检查requestTime后重新发起 |
| 服务端请求限制 | ILLEGAL_IP_REQUEST | illegal ip request                            | 请求IP需要加入白名单，请联系PayerMax                       |
|                | TOO_MANY_REQUEST   | Exceed request limitation, please retry later | 触发接口并发限流,请稍后重试                                |

#### 3.2.2 商户配置校验

在发起付款申请时，您可能遇到的「**商户配置校验**」类的错误码如下：

| 分类         | 子分类            | 错误码               | 错误描述                                                 | 备注                                         |
| ------------ | ----------------- | -------------------- | -------------------------------------------------------- | -------------------------------------------- |
|              | 签名/密钥配置校验 | MERCHANT_APP_INVALID | Signature key is not configured.                         | 密钥未配置，请尽快配置秘钥                   |
| 商户配置校验 |                   | SIGN_VERIFY_FAILED   | The signature verify failed.                             | 验签失败，请检查秘钥或签名逻辑               |
|              | 合约可用性校验    | CONTRACT_INVALID     | Merchant has not signed the contract or payment methods. | 未签约或未开通该支付方式，请检查合约开通情况 |
|              |                   | MERCHANT_INVALID     | The merchant has been offline.                           | 商户已下线，如有疑问请联系PayerMax           |

#### 3.2.3 订单信息接收

在发起付款申请时，您可能遇到的「**订单信息接收**」类的错误码如下：

| 分类         | 子分类       | 错误码           | 错误描述                                      | 备注                                                                                                                                                                                                    |
| ------------ | ------------ | ---------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|              |              | PARAMS_INVALID   | The {field} is incorrect.                     | 【字段】校验不符合规则，请参考[《付款申请模板及填写规范》](https://docs.payermax.com/202606-version/appendix/disbursement/disbursement-application-template.md)查看对应支付方式下的字段规则           |
|              | 请求参数校验 | PARAMS_INVALID   | The {field} is incorrect，you should fill {?} | 【字段】校验不符合规则，请根据提示并参考[《付款申请模板及填写规范》](https://docs.payermax.com/202606-version/appendix/disbursement/disbursement-application-template.md)查看对应支付方式下的字段规则 |
| 订单信息接收 |              | ORDER_REPEAT     | The order number repeat.                      | 订单号重复，请修改后重新发起                                                                                                                                                                            |
|              |              | UNSUPPORTED_BANK | Bank account invalid or bank not supported    | 不支持的银行或账号无效，请检查后重新发起                                                                                                                                                                |
|              | 其他异常     | SYSTEM_ERROR     | System is busy, Please try again later.       | 系统异常，请检查订单状态，如落单失败则重新发起                                                                                                                                                          |