文档
Start typing to search…

创建代付订单

该接口由 FuturePay 团队开发，主要用于发起代付请求，支持向指定收款账户进行付款操作。调用方可通过此接口创建一笔新的代付订单，系统将按配置的代付渠道进行处理与分发。 接口支持参数校验、签名验证及回调通知，适用于各类业务系统对接企业付款、结算、代发工资等场景。

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主体参数

参数名类型是否必填说明
merchantReferenceString是商户订单号，全局唯一
beneficiaryObject是受益人信息，见下文
remitterObject是付款人信息，见下文
amountBigDecimal是付款金额，不能小于 1 对于印度尼西亚银行只能为正整数. bankCode后缀为"-P00017"代付金额要超过50000(T1-T3 工作日到账),bankCode后缀为"-P00016"代付金额要不超过50000(实时到账)
countryCodeString是收款国家代码（ISO 3166-1 alpha-2 格式），如：TZ
currencyString是扣款币种，最多 3 位，如：TZS
accountTypeString是付款方类型：company 企业 / individual 个人
payoutMethodString是代付方式：MobileMoney 或 BankTransfer
webhookUrlString否交易完成后回调通知地址
narrationString是附言/备注，最多 255 字符，埃及支持附言见下文
clientIpString是客户端IP地址

2.2 Beneficiary（受益人信息）

字段名类型是否必填说明
nameString是受益人全名（可选用 firstName + lastName 组合）
firstNameString南非BankTransfer必填，其余选填名
lastNameString南非BankTransfer必填，其余选填姓
idNumberString埃及必填，其余选填身份证号码
accountNumberString是银行账户或钱包账号
bankNameString否银行名称（可选）
bankCodeString是银行代码（来自代付银行查询接口），埃及的MobileMoney固定传EGPWALLETS
addressAddress南非BankTransfer、bankCode(P00020.P00018、P00019、P00021、P00022、以及bankCode后缀为"-P00017"和"-P00016")必填，其余选填地址信息对象
emailString南非BankTransfer、印度尼西亚必填，其余选填邮箱地址
contactNumberContactNumber南非BankTransfer、埃及、bankCode(P00020.P00018、P00019、P00021、P00022、以及bankCode后缀为"-P00017"和"-P00016")必填，其余选填联系电话对象
identificationString否身份证编号
dateOfBirthString否出生日期，格式：yyyy-MM-dd

2.3 Remitter（付款人信息）

字段名类型是否必填说明
nameString是付款人姓名
phoneNumString是电话号码，格式建议："区号-手机号"
addressString是地址
emailString否邮箱
countryCodeString否国家代码（ISO 格式）
cityString是城市
idTypeString是身份证件类型，见下文说明
idNumberString是身份证号码
idExpiryString是身份证有效期，格式：yyyy-MM-dd
dateOfBirthString是出生日期，格式：yyyy-MM-dd

2.4 ContactNumber（联系号码对象）

字段名类型是否必填说明
countryCodeString否国家代码
numberString否电话号码

2.5 Address（地址对象）

字段名类型是否必填说明
line1String南非BankTransfer、bankCode(P00020.P00018、P00019、P00021、P00022、以及bankCode后缀为"-P00017"和"-P00016")必填，其余选填地址行 1
line2String南非BankTransfer、bankCode(P00020.P00018、P00019、P00021、P00022、以及bankCode后缀为"-P00017"和"-P00016")必填，其余选填地址行 2
cityString南非BankTransfer、bankCode(P00020.P00018、P00019、P00021、P00022、以及bankCode后缀为"-P00017"和"-P00016")必填，其余选填城市
stateString南非BankTransfer、bankCode(P00020.P00018、P00019、P00021、P00022、以及bankCode后缀为"-P00017"和"-P00016")必填，其余选填州/省份
countryCodeString南非BankTransfer、bankCode(P00020.P00018、P00019、P00021、P00022、以及bankCode后缀为"-P00017"和"-P00016")必填，其余选填国家代码
postalCodeString南非BankTransfer、bankCode(P00020.P00018、P00019、P00021、P00022、以及bankCode后缀为"-P00017"和"-P00016")必填，其余选填邮政编码
{
  "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.正确响应内容

字段名类型说明示例值
merchantReferenceString商户请求的唯一订单号MCH123456789
pspReferenceString平台生成的订单编号（用于平台追踪）FP202405270001
resultCodeString订单状态码（如：SUCCESS、FAILED）SUCCESS
dataObject支付明细数据—
├─ paymentAmountObject实际付款总金额（付款金额 + 手续费）—
│ ├─ currencyString支付币种AED
│ └─ valueString金额，单位保留两位小数（字符串格式）1050.00
├─ payeeAmountObject收款方应收金额（不含手续费）—
│ ├─ currencyString币种AED
│ └─ valueString金额1000.00
└─ feeAmountObject手续费金额—
├─ currencyString币种AED
└─ valueString金额`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响应错误内容

字段名类型描述
codestring错误码/成功码（业务码）详情请见下错误码表格
msgstring提示信息
serverTimelong响应生成时间戳（毫秒）
successboolean请求是否成功，false 表示失败
{
    "code": "600006",
    "msg": "Payment failed.",
    "serverTime": 1748260895368,
    "success": false
}

4.1 错误码

错误码描述中文说明
600001Merchant is now invalid - Contact futurepay to enable the account.商户状态无效，请联系 FuturePay 启用该账户
600002The payout product for this account is not yet enabled - Please contact Futurepay to activate it.当前账户尚未开通代付产品，请联系 FuturePay 开通
600003MerchantReference should be unique for each transaction.商户订单号重复，merchantReference 应唯一
600004Unsupported country.不支持的国家
600005Unsupported currency.不支持的币种
600006Payment failed.通道支付失败
600007Missing Required Arguments.缺少必要参数
600008Insufficient Balance.商户余额不足
600009Failed to freeze the available balance of the merchant.商户可用余额冻结失败
600010The fee strategy has not been configured - Contact futurepay for configuration.未配置手续费策略，请联系 FuturePay 处理
600011Failed to obtain the order rate.获取订单汇率失败
600012Failed to notify the merchant.回调通知商户失败
600013Payout order not found.未找到代付订单
600014Payout amount invalid.金额不合法（如为负、为 0、小于限额等）
600015Payout method invalid.无效的代付方式，仅支持 MobileMoney 或 BankTransfer
600016Account number cannot be blank.银行账户不能为空
600017Bank code invalid.银行代码无效
600018The current bank code does not support proxy payment.当前银行不支持代付
600019Unsupported country or currency.国家或币种不受支持

5.付款方式说明列表

付款方式枚举付款支持的国家支持的币种
MobileMoneyGH（加纳）、KE（肯尼亚）、TZ（坦桑尼亚）、UG（乌干达）、BJ（贝宁）、CI（科特迪瓦）、塞内加尔（SN）、CM（喀麦隆）、ZM（赞比亚）、RW（卢旺达）、EG（埃及）、PH（菲律宾）、ID（印度尼西亚）GHS、KES、TZS、UGX、XOF、XAF、ZMW、RWF、EGP、PHP、IDR
BankTransferZA（南非）、GH（加纳）、KE（肯尼亚）、TZ（坦桑尼亚）、UG（乌干达）、NG（尼日利亚）、CI（科特迪瓦）、塞内加尔（SN）、CM（喀麦隆）、ZM（赞比亚）、RW（卢旺达）、EG（埃及）、MY（马来西亚）、PH（菲律宾）、ID（印度尼西亚）ZAR、GHS、KES、TZS、UGX、NGN、XOF、XAF、ZMW、RWF、EGP、MYR、PHP、IDR

收款账号格式要求

付款方式枚举国家代码（中文）币种收款账号格式说明示例账号
BankTransferNG（尼日利亚）NGN10位数字1234567890
BankTransferKE（肯尼亚）KES10位数字1234567890
BankTransferGH（加纳）GHS具体格式视银行规则（通常为银行账户号）（依银行规则）
BankTransferTZ（坦桑尼亚）TZS具体格式视银行规则（通常为银行账户号）（依银行规则）
BankTransferEG（埃及）EGP8-32位数字5XXXXXXXXX
MobileMoneyGH（加纳）GHS9位本地号码，国际格式以 +233 开头，总长度 12 位+233XXXXXXXXX
MobileMoneyKE（肯尼亚）KES9位本地号码，国际格式以 +254 开头，总长度 12 位+254XXXXXXXXX
MobileMoneyUG（乌干达）UGX9位本地号码，国际格式以 +256 开头，总长度 12 位+256XXXXXXXXX
MobileMoneyTZ（坦桑尼亚）TZS9位本地号码，国际格式以 +255 开头，总长度 12 位+255XXXXXXXXX
MobileMoneyBJ（贝宁）XOF9位本地号码，国际格式以 +229 开头，总长度 12 位+229XXXXXXXXX
MobileMoneyCI（科特迪瓦）XOF10位本地号码，国际格式以 +225 开头，总长度 13 位+225XXXXXXXXX
MobileMoneyCM（喀麦隆）XAF9位本地号码，国际格式以 +237 开头，总长度 12 位+237XXXXXXXXX
MobileMoneyEG（埃及）EGP8-25位本地号码，国际格式以 +20 开头，总长度 10-27 位+20XXXXXXXXXX
MobileMoneySN（塞内加尔）XOF9位本地号码，国际格式以 +221 开头，总长度 12 位+221XXXXXXXXX

idType身份证类型列表

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

narration 埃及付款目的列表

说明narration取值
EPFAMTEPFAMT

菲律宾代付银行说明

bankCode说明示例
"xxxx-P00017"bankCode后缀为"-P00017"代付金额要超过50000(T1-T3 工作日到账)BDOU-P00017
"xxxx-P00016"bankCode后缀为"-P00016"代付金额要不超过50000(实时到账)BDO-P00016

印度尼西亚代付银行说明

BankTransfer 最低交易限额 Rp10000

MobileMoney 最低交易限额 Rp100

最高交易限额见列表

Bank CodeBank NameTransaction Limit(MAX)payoutMethod
244002BRIRp250,000,000BankTransfer
244008Bank MandiriRp250,000,000BankTransfer
244009Bank Negara IndonesiaRp250,000,000BankTransfer
244011Bank DanamonRp250,000,000BankTransfer
244013Bank PermataRp250,000,000BankTransfer
244014BCARp250,000,000BankTransfer
244016BII MaybankRp250,000,000BankTransfer
244019Bank PaninRp250,000,000BankTransfer
244022CIMB NiagaRp250,000,000BankTransfer
244023Bank UOB IndonesiaRp250,000,000BankTransfer
244028Bank OCBC NISPRp250,000,000BankTransfer
244031CitibankRp50,000,000BankTransfer
244032JPMorgan Chase BankRp250,000,000BankTransfer
244036Bank China Construction Bank IndonesiaRp50,000,000BankTransfer
244037Bank Artha Graha InternasionalRp250,000,000BankTransfer
244042MUFG BankRp250,000,000BankTransfer
244046Bank DBS IndonesiaRp250,000,000BankTransfer
244050Standard CharteredRp250,000,000BankTransfer
244054Bank Capital IndonesiaRp250,000,000BankTransfer
244061ANZ IndonesiaRp250,000,000BankTransfer
244067Deutsche Bank AGRp50,000,000BankTransfer
244069Bank OF ChinaRp250,000,000BankTransfer
244076Bank Bumi ArtaRp250,000,000BankTransfer
244087Bank HSBC IndonesiaRp250,000,000BankTransfer
244088Bank AntardaerahRp50,000,000BankTransfer
244089Bank RabobankRp50,000,000BankTransfer
244095Bank Jtrust IndonesiaRp250,000,000BankTransfer
244097Bank Mayapada InternationalRp250,000,000BankTransfer
244110BJBRp250,000,000BankTransfer
244111Bank DKIRp250,000,000BankTransfer
244112Bank DIYRp250,000,000BankTransfer
244112SBank DIY SyariahRp250,000,000BankTransfer
244113Bank JatengRp250,000,000BankTransfer
244114Bank JatimRp250,000,000BankTransfer
244114SBank Jatim SyariahRp250,000,000BankTransfer
244115Bank JambiRp250,000,000BankTransfer
244115SBank Jambi SyariahRp250,000,000BankTransfer
244116Bank AcehRp250,000,000BankTransfer
244117Bank SumutRp250,000,000BankTransfer
244117SBank Sumut SyariahRp250,000,000BankTransfer
244118Bank NagariRp250,000,000BankTransfer
244118SBank Nagari SyariahRp250,000,000BankTransfer
244119Bank RiauRp250,000,000BankTransfer
244120Bank Sumsel BabelRp250,000,000BankTransfer
244120SBank Sumsel Babel SyariahRp250,000,000BankTransfer
244121Bank LampungRp250,000,000BankTransfer
244122Bank KalselRp250,000,000BankTransfer
244122SBank Kalsel SyariahRp250,000,000BankTransfer
244123Bank KalbarRp250,000,000BankTransfer
244123SBank Kalbar SyariahRp250,000,000BankTransfer
244124Bank KaltimRp250,000,000BankTransfer
244124SBank Kaltim SyariahRp250,000,000BankTransfer
244125Bank KaltengRp250,000,000BankTransfer
244126Bank SulselbarRp250,000,000BankTransfer
244126SBank Sulselbar SyariahRp250,000,000BankTransfer
244127Bank SulutRp250,000,000BankTransfer
244128Bank NTBRp250,000,000BankTransfer
244129Bank BaliRp250,000,000BankTransfer
244130Bank NTTRp250,000,000BankTransfer
244131Bank MalukuRp250,000,000BankTransfer
244132Bank PapuaRp250,000,000BankTransfer
244133Bank BengkuluRp250,000,000BankTransfer
244134Bank SultengRp250,000,000BankTransfer
244135Bank SultraRp250,000,000BankTransfer
244137Bank BantenRp250,000,000BankTransfer
244145Bank Nusantara ParahyanganRp50,000,000BankTransfer
244146Bank Of India IndonesiaRp50,000,000BankTransfer
244147Bank MuamalatRp250,000,000BankTransfer
244151Bank MestikaRp250,000,000BankTransfer
244152Bank ShinhanRp250,000,000BankTransfer
244153Bank SinarmasRp250,000,000BankTransfer
244157Bank Maspion IndonesiaRp250,000,000BankTransfer
244161Bank GaneshaRp250,000,000BankTransfer
244164Bank ICBC IndonesiaRp250,000,000BankTransfer
244167Bank QNB IndonesiaRp250,000,000BankTransfer
244200BTNRp250,000,000BankTransfer
244200SBTN SyariahRp250,000,000BankTransfer
244212Bank Woori SaudaraRp250,000,000BankTransfer
244213Bank SMBC IndonesiaRp250,000,000BankTransfer
244405Bank Victoria SyariahRp250,000,000BankTransfer
244425BJB SyariahRp250,000,000BankTransfer
244426Bank MegaRp250,000,000BankTransfer
244441Bank BukopinRp250,000,000BankTransfer
244451Bank Syariah IndonesiaRp250,000,000BankTransfer
244459Krom Bank IndonesiaRp250,000,000BankTransfer
244472Bank Jasa JakartaRp250,000,000BankTransfer
244484Bank KEB HanaRp250,000,000BankTransfer
244485Bank MNCRp250,000,000BankTransfer
244490Bank Neo CommerceRp250,000,000BankTransfer
244494Bank Raya IndonesiaRp250,000,000BankTransfer
244498Bank SBI IndonesiaRp250,000,000BankTransfer
244501BCA DigitalRp250,000,000BankTransfer
244503Bank National NobuRp250,000,000BankTransfer
244506Bank Mega SyariahRp250,000,000BankTransfer
244513Bank INARp250,000,000BankTransfer
244517Bank Panin SyariahRp250,000,000BankTransfer
244520Bank PrimaRp250,000,000BankTransfer
244521Bank Syariah BukopinRp250,000,000BankTransfer
244523Bank Sahabat SampoernaRp250,000,000BankTransfer
244526Bank Oke IndonesiaRp250,000,000BankTransfer
244535Bank Seabank IndonesiaRp250,000,000BankTransfer
244536Bank BCA SyariahRp250,000,000BankTransfer
244542Bank JagoRp250,000,000BankTransfer
244542SBank Jago SyariahRp250,000,000BankTransfer
244547Bank BTPN SyariahRp250,000,000BankTransfer
244548Bank Multiarta SentosaRp250,000,000BankTransfer
244553Bank Hibank IndonesiaRp250,000,000BankTransfer
244555Bank IndexRp250,000,000BankTransfer
244559Bank CNBRp50,000,000BankTransfer
244562SuperbankRp250,000,000BankTransfer
244564Bank Mandiri TaspenRp250,000,000BankTransfer
244566Bank Victoria InternationalRp250,000,000BankTransfer
244567Allo BankRp250,000,000BankTransfer
244600ATMB LSBRp250,000,000BankTransfer
244688BPR KSRp250,000,000BankTransfer
244724Bank DKI SyariahRp250,000,000BankTransfer
244725Bank Jateng SyariahRp250,000,000BankTransfer
244734Bank Sinarmas SyariahRp250,000,000BankTransfer
244777FinnetRp50,000,000BankTransfer
244867Bank EkaRp250,000,000BankTransfer
244945Bank IBK IndonesiaRp50,000,000BankTransfer
244949Bank CTBC IndonesiaRp250,000,000BankTransfer
244950Bank CommonwealthRp50,000,000BankTransfer
244987ATMB PlusRp250,000,000BankTransfer
danaDANARp20,000,000MobileMoney
gopayGoPayRp20,000,000MobileMoney
linkajaLinkAjaRp10,000,000MobileMoney
ovoOVORp20,000,000MobileMoney
shopeepayShopeepayRp20,000,000MobileMoney

Updated 5 days ago