申请提现/付款

POST /v1/mid-open-api/trade/payout/applyPay
需要验证签名

接口描述

该接口支持人民币和外币的提现（收款账户和KYC主体同名）和付款（收款账户和KYC主体非同名）业务。针对文档说明对请求参数做核验（非空、长度以及合法性校验），同时会对请求单号做唯一性校验，验证失败同步响应失败（详情参考错误码说明），验证通过同步响应受理成功。受理请求后，异步执行代发交易，订单结果以异步方式回调通知（建议长时间未接收到回调通知通过提现/付款结果查询接口获取结果信息）。

提示

只有当收款人和客户是同名同主体时交易类型为提现，其他（支付给他人）为付款。对于提现或付款为CNY(在岸人民币，不包括CNH) 时，必须要求客户的KYC主体在PingPong的合作渠道完成入网登记，系统在客户绑定第一张CNY收款卡时自动触发渠道的入网登记。因客户信息缺失导致无法完成渠道入网登记时由PingPong联系合作方补全客户信息并再次向渠道申请入网登记成功后，客户方可发起CNY的提现或付款。
交易手续费（包含PingPong手续费+合作方手续费）是由合作方指定，PingPong统一代扣。【注：交易账户支出金额包含交易手续费】。
目标金额为理论应到账金额，即目标金额=(交易账户支出金额-手续费) X 汇率，实际到账金额=(交易账户支出金额-手续费) X 汇率-渠道手续费。一般情况目标金额为CNY时渠道手续费为0，非CNY时，取决于手续费承担方式（请参考取值说明）。
支付订单的实际付款人默认为PingPong，若客户需要指定付款人(即指定抬头)，必须指定付款人或代付款人名称（payer_name）。
收款行名称为固定的全称或标准银行名称，境内银行如中国建设银行股份有限公司、中国建设银行，禁止"工行"、"工商银行"等非标准名称。
客户提现/付款CNY时，取决于CNY结汇订单额度，该额度对应订单贸易类型分类，目前分为货物贸易、服务贸易和一般贸易。 提现业务可不指定贸易类型，默认所有贸易类型额度可以混用，但可能会根据贸易类型将交易单拆分为多笔支付单据，即可能一次提现多笔到账。 付款业务一般默认一笔到账，则需要指定贸易类型（单一贸易类型可保障一笔到账）。

请求头

Parameter	Type	Required	Description
Authorization	string	M	access_token
Content-Type	string	M	application/json

请求参数

Parameter	Type	Required	Description
client_id	string(64)	M	客户号
partner_order_id	string(64)	M	交易请求单号【唯一性】
payout_type	string(32)	M	交易类型【取值请见附录】
pay_currency	string(3)	M	交易账户币种
pay_amount	decimal(18,2)	M	交易账户支出金额【大于0，精确到小数点后2位】
fee_amount	decimal(18,2)	M	交易手续费金额【大于等于0，精确到小数点后2位，同交易账户币种】
target_currency	string(3)	M	目标币种
target_amount	decimal(18,2)	M	目标金额【大于0，精确到小数点后2位(四舍五入) 注：target_currency为 JPY,KRW,IDR,VND,PHP 时必须为正整数】
fx_rate_id	string(64)	C	汇率ID【pay_currency和target_currency不一致时必须】
fx_rate	decimal(18,9)	C	汇率【大于0，精确到小数点后9位，pay_currency和target_currency不一致时必须】
payer_name	string(255)	O	指定付款人或代付款人名称【指定抬头】
charges_indicator	string(3)	C	手续费承担方式【target_currency为非CNY时必须，取值请见附录】
receiver_card_id	string(64)	C	收款卡ID【提现必填，即绑卡成功对应的card_id】
trade_code	string(16)	C	交易编码【注：target_currency为非CNY且收款行国家/地区为 CN,IN,ID,TH,AE,KR 必须， target_currency为CNY时付款必填，提现选填，取值请见附录】
remark	string(255)	O	交易附言
extend_info	string(1024)	O	扩展信息【JSON格式： {"receiver_phone": "138xxxxxxxx"}】

extend_info【扩展信息】

Parameter	Type	Required	Description
receiver_phone	string(32)	C	收款人手机号【注：收款行国家/地区为 CN 且 target_currency=CNH 且 holder_type=PERSON 必须】

返回响应

Parameter	Type	Required	Description
order_id	string	M	PingPong唯一单号
partner_order_id	string	M	交易请求单号
status	string	M	订单状态: PROCESSING-处理中

返回示例

成功
失败

{
    "code": 200,
    "data": {
        "order_id": "20220620151628",
        "partner_order_id": "PO20220620151628",
        "status": "PROCESSING"
    },
    "message": "SUCCESS"
}

{
    "code": 900002,
    "data": null,
    "message": "参数不合法"
}

附录

payout_type【交易类型】

enum	Description	remark
WITHDRAW	提现	收款账户和KYC主体同名
PAY	付款	收款账户和KYC主体非同名

charges_indicator【手续费承担方式】

enum	Description	remark
OUR	付款方承担	PingPong承担手续费，实际到账金额=目标金额
SHA	收款方和付款方AA	PingPong和客户平分手续费，实际到账金额=目标金额-手续费（一半）
BEN	收款方承担	客户承担手续费，实际到账金额=目标金额-手续费（全）

receiver_holder_type【收款类型】

enum	Description	remark
ENTERPRISE	企业	对公
PERSON	个人	对私

account_type【账户类型】

外币卡

value	Description	remark
CURRENT	现金账户
SAVING	储蓄账户

人民币卡

value	Description	remark
CREDIT	贷记卡
DEBIT	借记卡
VIRTUAL	虚拟卡	如：网商银行，苏宁银行等非实体卡

trade_code【交易编码】

非人民币代发(包含境内外币)

area	value	Description	remark
CN	GOODS	Goods	货物贸易
CN	SERVICES	Services	服务贸易
KR	GOODS	Goods	货物贸易
KR	SERVICES	Services	服务贸易
AE	GOODS	Services	服务贸易
AE	SERVICES	Services	服务贸易
AE	FINANCIAL	Financial Services	金融服务
AE	TAX	TAX Payment	纳税
AE	CAPITAL	Capital	证券服务
AE	OTS	Other modes of transport	航旅、运输
AE	ACM	Agency Commissions	代理佣金

人民币代发

value	Description	remark
121010	一般贸易
122030	未纳入海关统计的网络购物
222019	海运运输费、海运港口仓储费、船舶维修
222029	空运运输费、空运港口仓储费
222039	陆运运输费
227020	计算机服务
228024	广告服务
228025	展会服务
228039	设计认证费
228050	佣金收入

错误码

返回码	描述	建议
900000	system error	系统错误，请联系PingPong人员核查或相同单号重新发起请求或调用查询接口
900001	repeated request	订单已存在，请勿当作失败处理！建议调用查询接口查询
900002	illegal param	参数错误，请根据提示更正信息
910001	user not exist	用户不存在，请核对client_id是否正确
910002	user status abnormal	用户状态异常，请核对
920000	account not exist	账户不存在，请核对后再发起
920001	account status abnormal	账户状态异常，请核对
920002	account balance is not enough	账户余额不足，请核对后再发起
920003	account currency not match	账户币种不匹配，请联系PingPong人员核查
920004	account operate deny	账户交易受限，请核对后再发起
953000	rate validation failure	汇率验证失败，请核对后再发起
953001	rate validation is illegal	汇率不合法，请核对后再发起
953002	rate validation is not exist	汇率ID无效，请核对后再发起
954100	withdraw is invalid	提现收款人和KYC主体不匹配
954201	the CNY payment quota is insufficient	CNY可用额度不足，请补充材料

更新日志

2024-04-01

删除receiver_address字段。
删除receiver_card字段。
receiver_card_id字段由条件（提现）必填改为必填

接口描述​

请求头​

请求参数​

extend_info【扩展信息】

返回响应​

返回示例​

附录​

payout_type【交易类型】​

charges_indicator【手续费承担方式】​

receiver_holder_type【收款类型】​

account_type【账户类型】​

trade_code【交易编码】​

错误码​

更新日志​