创建代付订单

1.请求地址（POST）

实时 API: https://api.futurepay.global/api/v1/payout/pay

沙盒 API: https://api.futurepay-develop.com/api/v1/payout/pay

认证方式：Bearer Token（需在Header中携带Authorization）

2.请求参数

参数名	类型	是否必填	描述
`merchantReference`	`string`	是	商户侧订单号，需保证唯一
`beneficiaryName`	`string`	是	收款人姓名
`accountNumber`	`string`	是	收款账户号码（账号格式要求请参考下方列表）
`bankName`	`string`	是	开户银行名称
`bankCode`	`string`	是	银行代码（请联系Futurepay团队获取）
`payoutType`	`string`	是	代付类型（如 `wallet`、`banktransfer`）
`payoutMethod`	`string`	是	付款方式（如 `Nuban`更多付款方式请参考付款方式列表）
`countryCode`	`string`	是	收款国家二字码（ISO标准，支持国家代码请参考付款方式列表）
`addresses`	`object`	否	收款人地址信息
↳ `line1`	`string`	否	地址第一行
↳ `line2`	`string`	否	地址第二行
↳ `city`	`string`	否	城市
↳ `state`	`string`	否	省/州
↳ `countryCode`	`string`	否	国家代码二字码（ISO标准）
↳ `postalCode`	`string`	否	邮政编码
`email`	`string`	否	收款人邮箱
`contactNumber`	`object`	否	收款人联系电话
↳ `countryCode`	`string`	是	国家区号（如 +86）
↳ `number`	`string`	是	电话号码
`identification`	`string`	否	收款人身份证号或护照号
`dateOfBirth`	`string`	否	收款人出生日期，格式：yyyy-MM-dd
`remitter`	`string`	是	付款人姓名
`remitterPhoneNum`	`string`	是	付款人联系电话
`remitterAddress`	`string`	是	付款人地址
`amount`	`BigDecimal`	是	打款金额
`currency`	`string`	是	币种（如 AED、NGN、USD）
`accountType`	`string`	是	账户类型（如个人 `individual` 或公司 `company`）
`narration`	`string`	否	付款说明
`clientIp`	`string`	是	客户端 IP，用于风控与日志记录
`returnUrl`	`string`	是	付款完成重定向地址

{
  "merchantReference": "MCH123456789",
  "beneficiaryName": "张三",
  "accountNumber": "6222021234567890",
  "bankName": "中国银行",
  "bankCode": "BOC123",
  "payoutType": "wallet",
  "payoutMethod": "Nuban",
  "countryCode": "HM",
  "addresses": {
    "line1": "北京市朝阳区建国门外大街甲6号",
    "line2": "中环世贸C座1201",
    "city": "北京",
    "state": "北京市",
    "countryCode": "CN",
    "postalCode": "100022"
  },
  "email": "[email protected]",
  "contactNumber": {
    "countryCode": "+86",
    "number": "13800138000"
  },
  "identification": "110101199001011234",
  "dateOfBirth": "1990-01-01",
  "remitter": "李四",
  "remitterPhoneNum": "+86-13900139000",
  "remitterAddress": "上海市浦东新区世纪大道88号",
  "amount": 1000.00,
  "currency": "AED",
  "accountType": "company",
  "narration": "工资发放",
  "merchantId":1,
  "clientIp":"127.0.0.1"
}

3.API响应错误内容

字段名	类型	描述
`code`	`string`	错误码/成功码（业务码）详情请见下错误码表格
`msg`	`string`	提示信息
`serverTime`	`long`	响应生成时间戳（毫秒）
`success`	`boolean`	请求是否成功，`false` 表示失败

{
    "code": "600006",
    "msg": "Payment failed.",
    "serverTime": 1748260895368,
    "success": false
}

3.1 错误码

错误码	含义说明（英文 msg）	中文注释
`600001`	Merchant is now invalid - Contact futurepay to enable the account.	商户已失效，请联系 Futurepay 启用账号
`600002`	The payout product for this account is not yet enabled - Please contact Futurepay to activate it.	当前商户尚未开通代付产品，请联系 Futurepay
`600003`	MerchantReference should be unique for each transaction.	商户订单号需全局唯一
`600004`	Unsupported country.	不支持的国家代码
`600005`	Unsupported currency.	不支持的币种
`600006`	Payment failed.	代付请求失败
`600007`	Missing Required Arguments.	缺少必要参数
`600008`	Insufficient Balance.	商户余额不足
`600009`	Failed to freeze the available balance of the merchant.	商户余额冻结失败
`600010`	The fee strategy has not been configured - Contact futurepay for configuration.	手续费策略未配置，请联系 Futurepay
`600011`	Failed to obtain the order rate.	获取费率失败
`600012`	Failed to notify the merchant.	商户通知失败
`600013`	Payout order not found.	代付订单不存在

4.正确响应内容

字段名	类型	说明	示例值
`merchantReference`	`String`	商户请求的唯一订单号	`MCH123456789`
`pspReference`	`String`	平台生成的订单编号（用于平台追踪）	`FP202405270001`
`resultCode`	`String`	订单状态码（如：SUCCESS、FAILED）	`SUCCESS`
`data`	`Object`	支付明细数据	—
├─ `paymentAmount`	`Object`	实际付款总金额（付款金额 + 手续费）	—
│ ├─ `currency`	`String`	支付币种	`AED`
│ └─ `value`	`String`	金额，单位保留两位小数（字符串格式）	`1050.00`
├─ `payeeAmount`	`Object`	收款方应收金额（不含手续费）	—
│ ├─ `currency`	`String`	币种	`AED`
│ └─ `value`	`String`	金额	`1000.00`
└─ `feeAmount`	`Object`	手续费金额	—
├─ `currency`	`String`	币种	`AED`
└─ `value`	`String`	金额	`50.00

{
  "merchantReference": "MCH123456789",
  "pspReference": "FP202405270001",
  "resultCode": "SUCCESS",
  "data": {
    "paymentAmount": {
      "currency": "AED",
      "value": "1050.00"
    },
    "payeeAmount": {
      "currency": "AED",
      "value": "1000.00"
    },
    "feeAmount": {
      "currency": "AED",
      "value": "50.00"
    }
  }
}

5.付款方式说明列表

付款方式枚举	付款支持的国家	支持的币种
`Nuban`	NG（尼日利亚）	NGN
`MobileMoney`	GH（加纳）、KE（肯尼亚）、TZ（坦桑尼亚）、UG（乌干达）、BJ（贝宁）、CI（科特迪瓦）、CM（喀麦隆）	GHS、KES、TZS、UGX、XOF、XAF
`Ghipps`	GH（加纳）	GHS
`Tiss`	TZ（坦桑尼亚）	TZS
`Kepss`	KE（肯尼亚）	KES
`Wave`	CI（科特迪瓦）	XOF

收款账号格式要求

付款方式枚举	国家代码（中文）	币种	收款账号格式说明	示例账号
`Nuban`	NG（尼日利亚）	NGN	10位数字	1234567890
`Kepss`	KE（肯尼亚）	KES	10位数字	1234567890
`MobileMoney`	GH（加纳）	GHS	12位数字，以国家代码233开头	233XXXXXXXXX
`MobileMoney`	KE（肯尼亚）	KES	12位数字，以国家代码254开头	254XXXXXXXXX
`MobileMoney`	UG（乌干达）	UGX	12位数字，以国家代码256开头	256XXXXXXXXX
`MobileMoney`	TZ（坦桑尼亚）	TZS	12位数字，以国家代码255开头	255XXXXXXXXX
`MobileMoney`	BJ（贝宁）	XOF	12位数字，以国家代码229开头	229XXXXXXXXX
`MobileMoney`	CI（科特迪瓦）	XOF	12位数字，以国家代码225开头	225XXXXXXXXX
`MobileMoney`	CM（喀麦隆）	XAF	12位数字，以国家代码237开头	237XXXXXXXXX
`Ghipps`	GH（加纳）	GHS	具体格式视银行规则（通常为银行账户号）	（依银行规则）
`Tiss`	TZ（坦桑尼亚）	TZS	具体格式视银行规则（通常为银行账户号）	（依银行规则）
`Wave`	CI（科特迪瓦）	XOF	12位数字，以国家代码225开头	225XXXXXXXXX