创建代收订单
HTTP请求信息
TIP
POST baseUrl
+ /api/payIn
HTTP请求头
请求头 | 必选 | 值 |
---|---|---|
Content-Type | Y | application/json |
MerchantId | Y | MerchantId |
Sign | Y | Sign |
HTTP请求体
参数名 | 必选 | 类型 | 示例值 | 字段说明 |
---|---|---|---|---|
currency | Y | string(32) | PHP | 货币代码 |
payType | Y | int | 401 | 请查看 代收PayType枚举 |
amount | Y | decimal(20,2) | 100-50000 | 金额 |
reusableStatus | Y | boolean | false | 目前只能是false |
mchOrderNo | Y | string(32) | mch12345 | 商户订单号(不允许重复) |
expireTime | Y | long | 3600 | 过期时间(单位:秒)默认3600秒 不一定有效,部分通道支持 |
notifyUrl | Y | string(250) | https://acb.com/ | 回调地址 |
nonceStr | Y | string(32) | 162838128 | 随机数 |
remark | Y | string(32) | remark | 备注 (请使用英文字符或不带重音的西语) |
realName | Y | string(32) | firstName-middleName-lastName | 代收付款人姓名 |
payerAddress | Y | string(256) | province-city-line1(line1为代收付款人的简略地址) | 代收付款人地址,当使用还款码收款时(payType=410)必传 |
phone | Y | string(32) | 09123456789 | 代收付款人手机号 |
email | Y | string(64) | example@maildomain.com | 邮箱 |
idType | Y | string(32) | 请参考代收付款人证件类型 | 代收付款人证件类型 |
idCard | Y | string(32) | 付款人证件号 | |
goodsSubject | N | string(32) | apple | 商户标题 |
goodsBody | N | string(32) | apple | 商品描述 |
INFO
realName的firstName,middleName,lastName请使用-连接。若没有middleName可以使用空字符串代替。
INFO
payerAddress为代收收款人地址,以province
-city
-line1
格式拼接。此字段仅做只做格式校验,不做真实性校验。当使用还款码收款时(payType=410)必传。
省,市,收款人地址请使用-进行链接。省-市必须要是菲律宾的合法地区名。line1为代收付款人的简略地址,line1中如果有-符号需要替换为空格。
例如 收款人位于Abra
省,Tayum
市的 No. 12 Central Street
,那么payerAddress为 Abra-Tayum-No.12 Central Street
例如 收款人位于Abra
省,Tayum
市的 No. 12 Central-Street
,那么payerAddress为 Abra-Tayum-No.12 Central Street
TIP
注意回调地址仅支持https
或者http
协议的地址,如果地址是ip
地址,请务必使用公网域名。
HTTP响应体
JSON 示例
{
"msg": "SUCCESS",
"code": 200,
"data": {
"merchantId": "100001",
"mchOrderNo": "M1656908719283",
"orderNo": "PAYIN8232154612109344768",
"payCode": "646012000000015942",
"payUrl": null,
"amount": 100
}
}
2
3
4
5
6
7
8
9
10
11
12
参数名 | 类型 | 说明 |
---|---|---|
merchantId | long | 商户Id |
mchOrderNo | string(32) | 商户订单号 |
orderNo | string(32) | 平台订单号 |
amount | decimal(20,2) | 金额 |
orderFee | decimal(20,2) | 手续费 |
payCode | string(32) | 付款账户VA |
biller | string(32) | 收款机构,在使用refNo/bankVa收款时使用 |
payUrl | string(250) | 支付信息展示页/支付跳转URL |
TIP
请根据实际选择的 代收PayType枚举 使用payCode
, biller
, payUrl
等字段。 如果您不想自己渲染展示信息,Cashy提供了一个展示页面,商户可以使用payUrl
字段直接跳转到该页面,为用户展示支付信息。具体支持列表见下表。
payType值 | 说明 | payCode | payUrl | biller |
---|---|---|---|---|
401 | QRPH_STATIC | 二维码原始文本 | Cashy提供的展示页面 | 不生效 |
402 | QRPH_DYNAMIC | 二维码原始文本 | Cashy提供的展示页面 | 不生效 |
403 | BANK_TRANSFER_INSTA | 银行VA账号 | Cashy提供的展示页面 | 收款机构 |
404 | BANK_TRANSFER_PESONET | 银行VA账号 | Cashy提供的展示页面 | 收款机构 |
410 | RefNo (Bill Payment) | 还款码 | Cashy提供的展示页面 | 收款机构 ,线下使用时需要告知收银人员 |
431 | GCASH_WEB_ONLINE | 不生效 | 支付URL | 不生效 |
432 | PAYMAYA_WEB_ONLINE | 不生效 | 支付URL | 不生效 |
433 | COINS_WEB_ONLINE | 不生效 | 支付URL | 不生效 |
434 | GRABPAY_WEB_ONLINE | 不生效 | 支付URL | 不生效 |
435 | BPIA_WEB_ONLINE | 不生效 | 支付URL | 不生效 |
436 | UBPB_WEB_ONLINE | 不生效 | 支付URL | 不生效 |
查询代收订单
HTTP请求信息
TIP
POST baseUrl
+ /api/payInQuery
HTTP请求头
请求头 | 必选 | 值 |
---|---|---|
Content-Type | Y | application/json |
MerchantId | Y | MerchantId |
Sign | Y | Sign |
HTTP请求体
参数名 | 必选 | 类型 | 示例值 | 字段说明 |
---|---|---|---|---|
mchOrderNo | N | string(32) | P123456 | 商户订单号 |
orderNo | N | string(32) | PAYIN12345 | 平台订单号 |
nonceStr | Y | string(32) | 1628381288000 | 随机数 |
TIP
我们建议优先使用orderNo(平台订单号),平台订单号和商户订单号至少需要传递一个。
HTTP响应体
{
"msg": "SUCCESS",
"code": 200,
"data": {
"merchantId": "100001",
"mchOrderNo": "M1656752128806",
"orderNo": "PAYIN8231497473279467520",
"payType": "1",
"payCode": "646012000000015887",
"payUrl": null,
"payDeskUrl": null,
"amount": 100.0,
"patchOrderNo": "PAYIN82xxxxxxxxx",
"orderType": "PATCH",
"fee": null,
"orderStatus": "PAYING",
"completionTime": null
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
参数名 | 类型 | 字段说明 |
---|---|---|
merchantId | int | 商户Id |
mchOrderNo | string(32) | 商户订单号 |
orderNo | string(32) | 平台订单号 |
channelOrderNo | string(32) | 渠道订单号 |
payType | string(32) | 请查看 代收PayType枚举 |
payCode | string(32) | 支付码 |
payUrl | string(250) | 付款二维码 |
payDeskUrl | string(250) | 收银台地址 |
amount | decimal(20,2) | 金额 |
fee | decimal(20,4) | 手续费 |
orderStatus | string(32) | 订单状态 代收订单状态枚举 |
completionTime | date | 完成时间 |
patchOrderNo | string(32) | 关联的原订单的平台订单号 |
patchMchOrderNo | string(32) | 关联的原订单的商户订单号 |
orderType | string(32) | API=API接口 MCH=商户后台 DESK=收银台 PATCH=补单 |
关于orderType
为PATCH
时的补充说明
用户不按照订单金额付款或者重复付款会出现补单订单,此时补单订单的orderType
为PATCH
:
orderNo
是针对这笔订单新生成的平台订单号。patchOrderNo
为关联的原订单的平台订单号,patchMchOrderNo
为关联的原订单的商户订单号。mchOrderNo
为关联的原订单的商户订单号(带序列号标识)。注意,此时回调返回的mchOrderNo
末尾会增加序列号标识,用于区分多笔部分还款的订单。
例如您的商户订单号是MCH20230088
,当产生第一笔部分支付时,我们会在原订单的商户订单号mchOrderNo
末尾增加序列号00001
,您收到的回调的mchOrderNo
就是MCH2023008800001
,以此类推。
当发生补单行为时,我们的机器人也会在对应的商户群进行通知,通知会包含所有您需要的信息。
订单的orderType
为API
时:
patchOrderNo
和orderNo相同patchMchOrderNo
和mchOrderNo相同
此时上述参数没有额外的意义。
TIP
fee
和 completionTime
仅在订单成功支付时有值。completionTime
的格式为 yyyy-MM-dd HH:mm:ss
。
异步回调通知
异步通知请求
TIP
POST : notifyUrl
回调地址由商户提供或透传。
异步通知请求头
HeaderName | Required | Value |
---|---|---|
Content-Type | Y | application/json |
MerchantId | Y | MerchantId |
Sign | Y | Sign |
异步通知请求体
{
"orderStatus": "SUCCESS",
"amount": 10000.0,
"fee": 0,
"mchOrderNo": "2a6421c4-3758-4d1a-b47e-f7d0e7133f9e",
"merchantId": "100001",
"payDeskUrl": null,
"orderNo": "PAYDESKxxxxxxxxxxx",
"payUrl": "xxxxxxxxxxxx",
"patchOrderNo": "PAYIN82xxxxxxxxx",
"orderType": "PATCH",
"completionTime": "2022-08-08 08:08:08",
"nonceStr": "xxxxxxxxxx"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
参数名 | 类型 | 说明 |
---|---|---|
merchantId | int | 商户Id |
mchOrderNo | string(32) | 商户订单号 |
orderNo | string(32) | 平台订单号 |
amount | decimal(20,2) | 金额 |
fee | decimal(20,4) | 手续费 |
payUrl | string(32) | 收银台Url |
payDeskUrl | string(250) | 收银台地址 |
orderStatus | string(32) | 订单状态,请参考代收订单状态枚举 |
completionTime | date | 完成时间 |
nonceStr | string(32) | 随机数 |
patchOrderNo | string(32) | 关联的原订单的平台订单号 |
patchMchOrderNo | string(32) | 关联的原订单的商户订单号 |
orderType | string(32) | API=API接口 MCH=商户后台 DESK=收银台 PATCH=补单 |
TIP
fee
和 completionTime
仅在订单成功支付时有值。completionTime
的格式为 yyyy-MM-dd HH:mm:ss
。patchMchOrderNo
字段目前仅墨西哥有,其他国家暂不支持。
关于orderType
为PATCH
时的补充说明
用户不按照订单金额付款或者重复付款会出现补单订单,此时补单订单的orderType
为PATCH
:
orderNo
是针对这笔订单新生成的平台订单号。patchOrderNo
为关联的原订单的平台订单号,patchMchOrderNo
为关联的原订单的商户订单号。mchOrderNo
为关联的原订单的商户订单号(带序列号标识)。注意,此时回调返回的mchOrderNo
末尾会增加序列号标识,用于区分多笔部分还款的订单。
例如您的商户订单号是MCH20230088
,当产生第一笔部分支付时,我们会在原订单的商户订单号mchOrderNo
末尾增加序列号00001
,您收到的回调的mchOrderNo
就是MCH2023008800001
,以此类推。
当发生补单行为时,我们的机器人也会在对应的商户群进行通知,通知会包含所有您需要的信息。
订单的orderType
为API
时:
patchOrderNo
和orderNo相同patchMchOrderNo
和mchOrderNo相同
此时上述参数没有额外的意义。
TIP
Http响应状态码为200、301或302表示已正常发送回调,其它状态码我们会认为回调失败。回调失败后会在1,2,4,8,16,32,64,128,256,512分钟
重试,一共重试回调10次。