#拒付 API 文档
本接口文档面向 PalmPay 商户,提供拒付单查询、决策处理、详情查询及异步通知能力。
#查询拒付单列表
查询需要商户自主决策的拒付单,支持分页。
/api/chargeback/merchant/query#请求参数
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pageIndex | int | 是 | 页码(从 0 或 1 开始,取决于服务端约定) |
| pageSize | int | 是 | 每页条数 |
| orderNo | String | 否 | 原交易单的订单号 |
| startCreateTime | Long | 否 | 渠道拒付单创建时间 - 起始(时间戳,毫秒) |
| endCreateTime | Long | 否 | 渠道拒付单创建时间 - 截止(时间戳,毫秒) |
| status | String | 否 | 对商户的拒付状态,参见 MerchantChargebackStatusEnum |
| countryCode | String | 是 | 国家,参见 CountryEnum |
| currency | String | 否 | 币种,参见 CurrencyEnum |
#请求示例
curl --location 'https://open-gw-daily.palmpay-inc.com/api/chargeback/merchant/query' \
--header 'CountryCode: NG' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxx' \
--header 'Signature: LefRbaLVfuh3xe8F707xaO2GiX/XJJbXNDB3HfVfwt+Uo+IMXrfG7Lxj7vkT5b9Rloqtkb80HZ4OiRR+ksrM33JOULDFyY0DUvLYzopvrnv4as4d9ZIlQnkrUxLX0nFXf4B/gQDoD4/qggpucf8WMaICAq6TP4v4kS04IgItase8uDeBcgryOP3DTYHdWMXFISSsqLtPbXEI12RF0JrzrWCQKbNJ5ljo2Qa9TFmOr0ZnHw7hQkc2pdYt+CXrYXHNyC+YRSMoniQUC1Ptph/4DgB4cnvbBOhRbahZp0Q36uXh+dTlOy5uECKft1z7nm9AVQ8pLUHnuNPc+/7SFgg7UA==' \
--data '{
"requestTime": 1761099558226,
"version": "V1.1",
"nonceStr": "rNsxYX3Rkkktqq5NG3kkllppwF8LGDvLugF",
"pageIndex": 1,
"pageSize": 10,
"orderNo": "ORD20250101001",
"startCreateTime": 1704067200000,
"endCreateTime": 1706745600000,
"status": "WAIT_DEAL",
"countryCode": "NG",
"currency": "NGN"
}'#响应参数
| 字段名 | 类型 | 说明 |
|---|---|---|
| respCode | String | 响应码 |
| respMsg | String | 响应信息 |
| data | PageWrapper<ChargebackMerchantOrderDto> | 分页数据 |
PageWrapper 结构:
| 字段名 | 类型 | 说明 |
|---|---|---|
| totalCount | Long | 总记录数 |
| pageSize | Integer | 每页条数 |
| pageIndex | Integer | 当前页码 |
| list | List<ChargebackMerchantOrderDto> | 数据列表 |
ChargebackMerchantOrderDto 结构:
| 字段名 | 类型 | 说明 |
|---|---|---|
| createTime | Long | 渠道拒付单创建时间(时间戳,毫秒) |
| uniqBizId | String | 业务唯一标识 |
| merchantId | String | 商户 ID |
| orderNo | String | 原交易单号 |
| orderAmount | Long | 原交易单金额(最小单位,如分) |
| orderCurrency | String | 币种 |
| transactionTime | Long | 原单交易创建时间(时间戳,毫秒) |
| status | String | 商户侧拒付状态,参见 MerchantChargebackStatusEnum |
| countryCode | String | 国家代码 |
| remark | String | 备注 |
| expirationTime | Long | 拒付截止时间(时间戳,毫秒) |
| category | String | 拒付阶段分类,参见 ChargebackCategoryEnum |
| chargebackReasonCode | String | 渠道拒付原因码(如 81、4837) |
| chargebackReasonDesc | String | 渠道拒付原因描述 |
| evidenceRequiredDesc | String | 争议原因所需凭证说明文案 |
#响应示例
{
"respCode": "000000",
"respMsg": "success",
"data": {
"totalCount": 50,
"pageSize": 10,
"pageIndex": 1,
"list": [
{
"createTime": 1704067200000,
"uniqBizId": "CB202501010001",
"merchantId": "M100001",
"orderNo": "ORD20250101001",
"orderAmount": 500000,
"orderCurrency": "NGN",
"transactionTime": 1703980800000,
"status": "WAIT_DEAL",
"countryCode": "NG",
"remark": null,
"expirationTime": 1706745600000,
"category": "CHARGEBACK",
"chargebackReasonCode": "81",
"chargebackReasonDesc": "Suspiciously charged without authorisation, fraud suspected",
"evidenceRequiredDesc": "Order confirmation, subscription confirmation, 3DS or other payment authentication data"
}
]
}
}#商户自主决策处理
商户对拒付单进行接受 / 拒绝决策。
URL:POST /api/chargeback/merchant/decision
#请求参数
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| uniqBizId | String | 是 | 业务唯一标识 |
| decision | String | 是 | 商户决策结果,参见 MerchantDecisionStatusEnum,可选值:ACCEPT、REJECT |
| decisionReason | String | 否 | 拒绝退款原因(decision 为 REJECT 时建议填写) |
| openAttachmentList | String | 否 | 扩展字段,JSON array格式 |
| countryCode | String | 是 | 国家代码 |
#请求示例 - Url上传
curl --location 'https://open-gw-daily.palmpay-inc.com/api/chargeback/merchant/decision' \
--header 'CountryCode: NG' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxx' \
--header 'Signature: LefRbaLVfuh3xe8F707xaO2GiX/XJJbXNDB3HfVfwt+Uo+IMXrfG7Lxj7vkT5b9Rloqtkb80HZ4OiRR+ksrM33JOULDFyY0DUvLYzopvrnv4as4d9ZIlQnkrUxLX0nFXf4B/gQDoD4/qggpucf8WMaICAq6TP4v4kS04IgItase8uDeBcgryOP3DTYHdWMXFISSsqLtPbXEI12RF0JrzrWCQKbNJ5ljo2Qa9TFmOr0ZnHw7hQkc2pdYt+CXrYXHNyC+YRSMoniQUC1Ptph/4DgB4cnvbBOhRbahZp0Q36uXh+dTlOy5uECKft1z7nm9AVQ8pLUHnuNPc+/7SFgg7UA==' \
--data '{
"requestTime": 1761099558226,
"version": "V1.1",
"nonceStr": "rNsxYX3Rkkktqq5NG3kkllppwF8LGDvLugF",
"uniqBizId": "CB202501010001",
"decision": "REJECT",
"orderNo": "ORD20250101001",
"decisionReason": "商品已按时交付,物流签收正常",
"countryCode": "NG",
"openAttachmentList": [
"https://example.com/evidence1.png",
"https://example.com/evidence2.pdf"
]
}'#请求示例 - base64上传
curl --location 'https://open-gw-daily.palmpay-inc.com/api/chargeback/merchant/decision' \
--header 'CountryCode: NG' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxx' \
--header 'Signature: LefRbaLVfuh3xe8F707xaO2GiX/XJJbXNDB3HfVfwt+Uo+IMXrfG7Lxj7vkT5b9Rloqtkb80HZ4OiRR+ksrM33JOULDFyY0DUvLYzopvrnv4as4d9ZIlQnkrUxLX0nFXf4B/gQDoD4/qggpucf8WMaICAq6TP4v4kS04IgItase8uDeBcgryOP3DTYHdWMXFISSsqLtPbXEI12RF0JrzrWCQKbNJ5ljo2Qa9TFmOr0ZnHw7hQkc2pdYt+CXrYXHNyC+YRSMoniQUC1Ptph/4DgB4cnvbBOhRbahZp0Q36uXh+dTlOy5uECKft1z7nm9AVQ8pLUHnuNPc+/7SFgg7UA==' \
--data '{
"requestTime": 1788994800000,
"version": "V1.1",
"nonceStr": "rNsxYX3Rkkktqq5NG3kkllppwF8LGDvLugF",
"uniqBizId": "Chargebacktest-20260908-4",
"decision": "REJECT",
"orderNo": "24260831090256527628",
"decisionReason": "Goods delivered on time, delivery confirmation received",
"countryCode": "ZA",
"openAttachmentList":"[\"iVBORw0KGgoAAAANSUhEUgAAAJ8AAAAvCAIAAABys4/CAAAACXBIWXMAAA7EAAAOxAGVKw4bAAACHElEQVR4nO2bXZaDIAyFidNFdPa/N13FHOahPZZKiPITQLjfU0ewdbxcAjGStdZMw7Ztz+dz/5OIGl5MBZbWF1AbV9HhR/Z06k5FR+paB9Ufmse+j9YXYAx3i19Hho+L2rT3ruAePWO9xg0RjT2AGqvr6sfea22Bx6alugdp9w+H+z52aFSl/cxs5rBRE7pQ1wf2LUIX6kI8JbpQlwX2zUdxv8vq4WpGRHsfay3kLI6Wd0PaXNzd7p/nyStpoKKuLAO7EdqbKmQi50E37pKDe1wQ+HC63AHI1FtVxQoMUfPJXVVFpfvdZZTflHklwKeMd9MiJeKrNrX3uwkexSBIJlddWa3TLS/bwV05X1x/AZbuclXsrhekUUzdkMnS7Ov3h3EToHVdM7/iNK/ECiN3YL8TxPIwP79C85WwR3s3N4fsnGvZc13Leq1akv5t8v87GMGZ2c8InuYIoyqkYMoK8OoWqWSDfs1h1E2oZAtO2njC05SjupmVbNenbohdgWCeudS8esgtIwDXJGK/K9v39EFebBPIR1ozF/wZf25HgqICcbmqK9FXGBahh/lAiUWYYEMvb4G7sJhylWxwZG+8Z+aylWyweCd84i4q2cYjuKpKq2SD6l3xEF4ISJYKGneClIlMA9L2w2JQyTYuJ8+I3IOoZLsdb3WvlzbCtTci/V0EuLZ/PjOzkIM8ZIaRKL4LEd6Forfja1UF/QbjH6fpQzx+5ItPAAAAAElFTkSuQmCC\"]"
]
}'#响应参数
| 字段名 | 类型 | 说明 |
|---|---|---|
| respCode | String | 响应码 |
| respMsg | String | 响应信息 |
| data | null | 无返回数据 |
#响应示例
{
"respCode": "000000",
"respMsg": "success",
"data": null
}#拒付单详情查询
根据业务唯一标识查询拒付单详情。
URL:POST /api/chargeback/merchant/detail
#请求参数
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| uniqBizId | String | 是 | 业务唯一标识 |
| countryCode | String | 是 | 国家代码 |
#请求示例
curl --location 'https://open-gw-daily.palmpay-inc.com/api/chargeback/merchant/detail' \
--header 'CountryCode: NG' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxx' \
--header 'Signature: LefRbaLVfuh3xe8F707xaO2GiX/XJJbXNDB3HfVfwt+Uo+IMXrfG7Lxj7vkT5b9Rloqtkb80HZ4OiRR+ksrM33JOULDFyY0DUvLYzopvrnv4as4d9ZIlQnkrUxLX0nFXf4B/gQDoD4/qggpucf8WMaICAq6TP4v4kS04IgItase8uDeBcgryOP3DTYHdWMXFISSsqLtPbXEI12RF0JrzrWCQKbNJ5ljo2Qa9TFmOr0ZnHw7hQkc2pdYt+CXrYXHNyC+YRSMoniQUC1Ptph/4DgB4cnvbBOhRbahZp0Q36uXh+dTlOy5uECKft1z7nm9AVQ8pLUHnuNPc+/7SFgg7UA==' \
--data '{
"requestTime": 1761099558226,
"version": "V1.1",
"nonceStr": "rNsxYX3Rkkktqq5NG3kkllppwF8LGDvLugF",
"uniqBizId": "CB202501010001",
"countryCode": "NG"
}'#响应参数
| 字段名 | 类型 | 说明 |
|---|---|---|
| respCode | String | 响应码 |
| respMsg | String | 响应信息 |
| data | ChargebackMerchantOrderDto | 拒付单详情,结构同 查询接口的 DTO 说明 |
#响应示例
{
"respCode": "000000",
"respMsg": "success",
"data": {
"createTime": 1704067200000,
"uniqBizId": "CB202501010001",
"merchantId": "M100001",
"orderNo": "ORD20250101001",
"orderAmount": 500000,
"orderCurrency": "NGN",
"transactionTime": 1703980800000,
"status": "WAIT_DEAL",
"countryCode": "NG",
"remark": null,
"expirationTime": 1706745600000,
"category": "CHARGEBACK",
"chargebackReasonCode": "81",
"chargebackReasonDesc": "Suspiciously charged without authorisation, fraud suspected",
"evidenceRequiredDesc": "Order confirmation, subscription confirmation, 3DS or other payment authentication data"
}
}#拒付通知(异步回调)
当拒付单状态变更时,PalmPay 会向商户注册的回调地址发送异步通知。
商户需在收到通知后返回 HTTP 200 OK 以确认接收。若未返回 200,PalmPay 将按照重试策略(间隔 10 分钟,最多 3 次)重新推送。
#通知参数
| 字段名 | 类型 | 说明 |
|---|---|---|
| createTime | Long | 渠道拒付单创建时间(时间戳,毫秒) |
| uniqBizId | String | 业务唯一标识 |
| merchantId | String | 商户 ID |
| orderNo | String | 原交易单号 |
| orderAmount | Long | 原交易单金额(最小单位,如分) |
| orderCurrency | String | 币种 |
| transactionTime | Long | 原单交易创建时间(时间戳,毫秒) |
| status | String | 商户侧拒付状态,参见 MerchantChargebackStatusEnum |
| countryCode | String | 国家代码 |
| remark | String | 备注 |
| expirationTime | Long | 拒付截止时间(时间戳,毫秒) |
| category | String | 拒付阶段分类,参见 ChargebackCategoryEnum |
| chargebackReasonCode | String | 渠道拒付原因码 |
| chargebackReasonDesc | String | 渠道拒付原因描述 |
| evidenceRequiredDesc | String | 争议原因所需凭证说明文案 |
#通知示例
{
"createTime": 1704067200000,
"uniqBizId": "CB202501010001",
"merchantId": "M100001",
"orderNo": "ORD20250101001",
"orderAmount": 500000,
"orderCurrency": "NGN",
"transactionTime": 1703980800000,
"status": "WAIT_DEAL",
"countryCode": "NG",
"remark": null,
"expirationTime": 1706745600000,
"category": "CHARGEBACK",
"chargebackReasonCode": "81",
"chargebackReasonDesc": "Suspiciously charged without authorisation, fraud suspected",
"evidenceRequiredDesc": "Order confirmation, subscription confirmation, 3DS or other payment authentication data"
}#附录 A:枚举值定义
#MerchantDecisionStatusEnum
商户决策结果状态。
| 枚举值 | 说明 |
|---|---|
| ACCEPT | 接受(同意退款) |
| REJECT | 拒绝(不同意退款) |
#MerchantChargebackStatusEnum
商户平台展示的拒付状态,由拒付最终状态与商户决策结果共同决定。
| 枚举值 | 说明 |
|---|---|
| WAIT_DEAL | 待处理(商户尚未决策) |
| PROCESSING | 处理中(商户已决策,拒付单尚未终结) |
| ACCEPT | 已接受 |
| REJECT | 已拒绝 |
| TIME_OUT_REJECT | 超时自动拒绝 |
#ChargebackCategoryEnum
拒付单阶段分类(响应字段 category)。
| 枚举值 | 说明 |
|---|---|
| PRE_CHARGEBACK | 正式拒付前阶段 |
| CHARGEBACK | 正式拒付 |
| FRAUD | 欺诈 |
| PRE_ARBITRATION | 预仲裁 |
#CountryEnum
国家码,内部通用的枚举。
| 枚举值 | 说明 |
|---|---|
| NG | 尼日利亚 |
| GH | 加纳 |
| ZA | 南非 |
#CurrencyEnum
币种码,内部通用的枚举。
| 枚举值 | 说明 |
|---|---|
| NGN | 尼日利亚奈拉 |
| GHS | 加纳塞地 |
| ZAR | 南非兰特 |
#附录 B:通用响应结构
所有接口统一使用 RespResult<T> 包装响应。
{
"respCode": "000000",
"respMsg": "success",
"data": "<T>"
}| 字段名 | 类型 | 说明 |
|---|---|---|
| respCode | String | 响应码,000000 表示成功 |
| respMsg | String | 响应描述 |
| data | T | 业务数据,类型由具体接口决定 |