获取支付结果集成
该文档介绍获取支付结果的集成流程。
1. 集成准备
上传测试商户公钥,获取平台公钥、AppID、测试商户号等集成信息;
配置回调地址(WebHook),包括支付结果回调地址、退款结果回调地址等;
理解请求报文加签和验签的原理,用于生成每次HTTP请求Header的
sign
签名字符串;如果商户服务器对外部IP地址访问有限制,则需要将PayerMax服务器IP地址添加到商户服务器的白名单中,生产环境和测试环境IP地址请咨询PayerMax技术支持。
2. 交互流程
3. 接口列表
关联交互时序 | 调用方向 | 接口PATH |
1.1 支付结果通知 | PayerMax -> 商户 | /collectResultNotifyUrl |
2.1 查询支付交易 | 商户 -> PayerMax | /orderQuery |
4. 集成步骤
PayerMax支持两种方式获取支付结果。支付的结果状态包括如下:
状态 | 描述 | 备注 |
SUCCESS | 交易成功 | 用户支付成功 |
PENDING | 交易处理中 | 等待用户完成支付 |
FAILED | 交易失败 | 支付失败 |
CLOSED | 交易关单 | 用户在有效期内未完成支付 |
4.1 通过支付结果通知
支付完成后,PayerMax会主动回调商户指定的回调地址,发起支付结果通知 API。PayerMax可能会多次回调通知商户,直到接收到商户的成功响应。
商户可以通过两种方式设置支付结果回调地址:
通过接口参数指定:创建支付时,设置/orderAndPay API 请求入参
notifyUrl
。该配置仅对单笔支付生效,可覆盖全局配置。通过商户平台配置:通过PayerMax商户平台,配置统一的支付回调结果地址。该配置对所有支付交易生效。
支付结果通知 API 请求示例:
curl --request POST \
--url https://pay-gate-uat.payermax.com/collectResultNotifyUrl \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'sign: FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==' \
--data '{
"code": "APPLY_SUCCESS",
"msg": "",
"keyVersion": "1",
"appId": "3b242b56a8b64274bcc37dac281120e3",
"merchantNo": "020213827212251",
"notifyTime": "2022-01-17T09:33:54.540+00:00",
"notifyType": "PAYMENT",
"data": {
"outTradeNo": "P1642410680681",
"tradeToken": "T2024062702289232000001",
"totalAmount": 10000,
"currency": "IDR",
"country": "ID",
"status": "SUCCESS",
"completeTime": "2023-10-20T03:28:23.092Z",
"paymentDetails": [
{
"paymentMethodType": "WALLET",
"targetOrg": "DANA",
"paymentTokenID": "PMTOKEN20230710080439571142400031000"
}
],
"reference": "020213827524152"
}
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
商户可以通过data.status
判定退款状态。
支付结果通知 API 响应示例:
-- 响应成功
{
"msg": "Success",
"code": "SUCCESS" # PayerMax依赖code判定是否通知成功,如果非SUCCESS,则判定通知失败,PayerMax重发。
}
2
3
4
5
商户接收到支付结果通知后,可返回成功或失败。如果商户未响应或响应失败,则PayerMax会尝试重发支付结果通知,通知频率为0s/30s/300s/600s/3600s/43200s
,最多重试6次
。
在订单状态不明或者没有收到PayerMax支付结果通知的情况下,商户主动通过支付订单查询,获取支付结果。
4.2 通过支付订单查询
商户还可以通过调用交易查询/orderQuery API 接口,获取支付结果。
交易查询/orderQuery API 接口请求示例:
curl --request POST \
--url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderQuery \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'sign: FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==' \
--data '{
"version": "1.4",
"keyVersion": "1",
"requestTime": "2022-01-17T07:51:15.597+00:00",
"appId": "a0dddd1f622243cb9aa1b676e808b5f8",
"merchantNo": "02021382719993",
"data": {
"outTradeNo": "P1642410680681" # 商户单号
}
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
交易查询/orderQuery API 接口响应示例:
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
"reference": "reference查询和回调返回",
"country": "SA",
"totalAmount": 10,
"outTradeNo": "DEVTest1669616467952",
"currency": "SAR",
"channelNo": "DMCP000000000177005",
"thirdChannelNo": "4ikqJ6ktEqyRawE1dvqb9c",
"paymentCode": "2312121212",
"tradeToken": "T2024062702289232000001",
"completeTime": "2023-10-20T03:28:23.092Z",
"paymentDetails": [
{
"targetOrg": "*",
"cardInfo": {
"cardOrg": "VISA",
"country": "SA",
"cardIdentifierNo": "400555******0001",
"cardIdentifierName": "**ngwei"
},
"payAmount": 10,
"exchangeRate": "1",
"paymentMethod": "CARD",
"payCurrency": "SAR",
"paymentMethodType": "CARD"
}
],
"fees": {
"merFee": {
"url": "https://cashier-n-test-new.payermax.com/static/invoice.html?country=AE&merchantNo=P01010113843429×tamp=1687769788704&version=1.0&orderTaxToken=XWXFKKBOPExplK4aX0r7wgiMtiAMLBKObPFdCMpM9HmCq3AAOob%252BcAZOkP27Kh3W",
"amount": "100",
"currency": "SAR"
}
},
"status": "SUCCESS",
"resultMsg": ""
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
商户可以通过请求响应中的code
判定本次查询请求是否成功,通过data.status
进一步判定退款状态,请勿使用code
或msg
或data.resultMsg
判定退款状态。
5. 测试上线
在商户完成上述集成步骤后,可以发起实际支付请求进行初步测试验证,具体步骤请查看集成测试-发起测试。
在测试通过后,最终发布上线前,须联系PayerMax技术支持,提交测试的订单信息,以便于PayerMax检查请求日志和数据,确认您已经正确集成相关能力,具体步骤请查看集成测试-发起验收。
验收通过后,商户可以配置生产环境的集成信息,并准备开量事宜。
另外,在收单产品集成下有PayerMax支持的各类支付方式的集成文档,其中包含每种支付方式的测试上线说明。
6. 错误排除
测试或验收过程中的响应错误,可以查看错误排查-错误码。同时,在常见问题中,总结列举各类常见的问题及其处理方式。
您还可以直接联系PayerMax技术支持团队,咨询集成、测试、验收过程中的任何问题。