创建代付订单

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.请求参数

2.1主体参数

参数名	类型	是否必填	说明
merchantReference	String	是	商户订单号，全局唯一
beneficiary	Object	是	受益人信息，见下文
remitter	Object	埃及必填，其余选填	付款人信息，见下文
amount	BigDecimal	是	付款金额，不能小于 1
countryCode	String	是	收款国家代码（ISO 3166-1 alpha-2 格式），如：`TZ`
currency	String	是	扣款币种，最多 3 位，如：`TZS`
accountType	String	是	付款方类型：`company` 企业 / `individual` 个人
payoutMethod	String	是	代付方式：`MobileMoney` 或 `BankTransfer`
webhookUrl	String	否	交易完成后回调通知地址
narration	String	是	附言/备注，最多 255 字符，埃及支持附言见下文
clientIp	String	是	客户端IP地址

2.2 Beneficiary（受益人信息）

字段名	类型	是否必填	说明
name	String	是	受益人全名（可选用 `firstName` + `lastName` 组合）
firstName	String	南非BankTransfer必填，其余选填	名
lastName	String	南非BankTransfer必填，其余选填	姓
idNumber	String	埃及必填，其余选填	身份证号码
accountNumber	String	是	银行账户或钱包账号
bankName	String	否	银行名称（可选）
bankCode	String	是	银行代码（来自代付银行查询接口），加纳BankTransfer需要传支行编码，埃及MobileMoney固定传`EGPWALLETS`
address	Address	南非BankTransfer必填，其余选填	地址信息对象
email	String	南非BankTransfer必填，其余选填	邮箱地址
contactNumber	ContactNumber	南非BankTransfer、埃及必填，其余选填	联系电话对象
identification	String	否	身份证编号
dateOfBirth	String	否	出生日期，格式：yyyy-MM-dd

2.3 Remitter（付款人信息）

字段名	类型	是否必填	说明
name	String	是	付款人姓名
phoneNum	String	是	电话号码，格式建议："区号-手机号"
address	String	是	地址
email	String	否	邮箱
countryCode	String	否	国家代码（ISO 格式）
city	String	是	城市
idType	String	是	身份证件类型，见下文说明
idNumber	String	是	身份证号码
idExpiry	String	是	身份证有效期，格式：yyyy-MM-dd
dateOfBirth	String	是	出生日期，格式：yyyy-MM-dd

2.4 ContactNumber（联系号码对象）

字段名	类型	是否必填	说明
countryCode	String	否	国家代码
number	String	否	电话号码

2.5 Address（地址对象）

字段名	类型	是否必填	说明
line1	String	南非BankTransfer必填，其余选填	地址行 1
line2	String	南非BankTransfer必填，其余选填	地址行 2
city	String	南非BankTransfer必填，其余选填	城市
state	String	南非BankTransfer必填，其余选填	州/省份
countryCode	String	南非BankTransfer必填，其余选填	国家代码
postalCode	String	南非BankTransfer必填，其余选填	邮政编码

{
  "merchantReference": "MCHREF202506240001",
  "amount": 100.00,
  "countryCode": "TZ",
  "currency": "TZS",
  "accountType": "individual",
  "payoutMethod": "MobileMoney",
  "webhookUrl": "https://yourdomain.com/callback",
  "narration": "Salary payment for June",
  "clientIp": "127.0.0.1",

  "beneficiary": {
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "idNumber": "ID1234567890",
    "accountNumber": "255712345678",
    "bankName": "TIGO",
    "bankCode": "TIGTZA",
    "email": "[email protected]",
    "dateOfBirth": "1990-01-01",
    "identification": "ID9876543210",

    "contactNumber": {
      "countryCode": "+255",
      "number": "712345678"
    },

    "address": {
      "line1": "123 Main Street",
      "line2": "Apartment 4B",
      "city": "Dar es Salaam",
      "state": "Dar",
      "countryCode": "TZ",
      "postalCode": "14111"
    }
  },

  "remitter": {
    "name": "FuturePay Ltd.",
    "phoneNum": "+255-789123456",
    "email": "[email protected]",
    "address": "Plot 10, Tech Park, Dar",
    "countryCode": "TZ",
    "city": "Dar es Salaam",
    "idType": "01",
    "idNumber": "P123456789",
    "idExpiry": "2030-12-31",
    "dateOfBirth": "1985-05-20"
  }
}

3.正确响应内容

字段名	类型	说明	示例值
`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"
    }
  }
}

4.API响应错误内容

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

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

4.1 错误码

错误码	描述	中文说明
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.	商户订单号重复，`merchantReference` 应唯一
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.	未找到代付订单
600014	Payout amount invalid.	金额不合法（如为负、为 0、小于限额等）
600015	Payout method invalid.	无效的代付方式，仅支持 `MobileMoney` 或 `BankTransfer`
600016	Account number cannot be blank.	银行账户不能为空
600017	Bank code invalid.	银行代码无效
600018	The current bank code does not support proxy payment.	当前银行不支持代付
600019	Unsupported country or currency.	国家或币种不受支持

5.付款方式说明列表

付款方式枚举	付款支持的国家	支持的币种
`MobileMoney`	GH（加纳）、KE（肯尼亚）、TZ（坦桑尼亚）、UG（乌干达）、BJ（贝宁）、CI（科特迪瓦）、CM（喀麦隆）、EG（埃及）	GHS、KES、TZS、UGX、XOF、XAF、EGP
`BankTransfer`	ZA（南非）、GH（加纳）、NG（尼日利亚）、GH（加纳）、TZ（坦桑尼亚）、KE（肯尼亚）、EG（埃及）	ZAR、GHS、NGN、GHS、TZS、XOF、KES、EGP

收款账号格式要求

付款方式枚举	国家代码（中文）	币种	收款账号格式说明	示例账号
`BankTransfer`	NG（尼日利亚）	NGN	10位数字	1234567890
`BankTransfer`	KE（肯尼亚）	KES	10位数字	1234567890
`BankTransfer`	GH（加纳）	GHS	具体格式视银行规则（通常为银行账户号）	（依银行规则）
`BankTransfer`	TZ（坦桑尼亚）	TZS	具体格式视银行规则（通常为银行账户号）	（依银行规则）
`BankTransfer`	EG（埃及）	EGP	8-32位数字	5XXXXXXXXX
`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
`MobileMoney`	EG（埃及）	EGP	6-25位数字，以国家代码20开头	20XXXXXXXXXX

idType身份证类型列表

idType取值	说明
01	PASSPORT（护照）
02	DRIVING_LICENSE（驾驶执照）
03	ID_CARD（身份证）
04	VOTER_CARD（选民卡）
05	LABOUR_CARD（劳工卡）
06	BAR_ASSOCIATION_CARD（律师协会卡）
07	DEFENCE_PERSONNEL_IDENTITY（国防人员身份证）
08	GOVT_ID（政府身份证）
09	OTHER（其他）
10	PAN_CARD（PAN卡/印度税务身份证）
11	RATION_CARD_WITH_PHOTO（配给卡-带照片）
12	IBL_CUSTOMER（IBL客户卡）
13	IQAMA（沙特居留证）
14	CITIZENSHIP_CARD（公民身份证）
15	FEDERAL_ID（联邦身份证）
16	MILITARY_IDENTIFICATION_CARD（军人身份证）
17	COMMERCIAL_REGISTRATION（商业登记证）
18	CNIC（巴基斯坦国民身份证）
19	WORK_PERMIT（工作许可证）
20	BIRTH_CERTIFICATE（出生证明）
21	BUSINESS_REGISTRATION_LICENCE（商业登记/许可证）
22	SOCIAL_SECURITY（社会保障卡）
23	STUDENT_ID（学生证）
24	BORDER_PAPER（边境通行证）
25	ROYAL_DECREE（皇家法令）
26	LICENSE_PERMIT（许可证）
27	GCC_IDENTITY_DOCUMENT（海湾合作委员会身份证件）
28	SAUDI_FAMILY_BOOK（沙特家庭簿）
29	ENTRY_PERMIT（入境许可）
30	NATIONAL_ID（国民身份证）

narration 埃及付款目的列表

说明	narration取值
EPFAMT	EPFAMT