• 简体中文
  • 拒付 API 文档

    本接口文档面向 PalmPay 商户,提供拒付单查询、决策处理、详情查询及异步通知能力。

    查询拒付单列表

    查询需要商户自主决策的拒付单,支持分页。

    /api/chargeback/merchant/query

    请求参数

    字段名类型必填说明
    pageIndexint是页码(从 0 或 1 开始,取决于服务端约定)
    pageSizeint是每页条数
    orderNoString否原交易单的订单号
    startCreateTimeLong否渠道拒付单创建时间 - 起始(时间戳,毫秒)
    endCreateTimeLong否渠道拒付单创建时间 - 截止(时间戳,毫秒)
    statusString否对商户的拒付状态,参见 MerchantChargebackStatusEnum
    countryCodeString是国家,参见 CountryEnum
    currencyString否币种,参见 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"
    }'

    响应参数

    字段名类型说明
    respCodeString响应码
    respMsgString响应信息
    dataPageWrapper<ChargebackMerchantOrderDto>分页数据

    PageWrapper 结构:

    字段名类型说明
    totalCountLong总记录数
    pageSizeInteger每页条数
    pageIndexInteger当前页码
    listList<ChargebackMerchantOrderDto>数据列表

    ChargebackMerchantOrderDto 结构:

    字段名类型说明
    createTimeLong渠道拒付单创建时间(时间戳,毫秒)
    uniqBizIdString业务唯一标识
    merchantIdString商户 ID
    orderNoString原交易单号
    orderAmountLong原交易单金额(最小单位,如分)
    orderCurrencyString币种
    transactionTimeLong原单交易创建时间(时间戳,毫秒)
    statusString商户侧拒付状态,参见 MerchantChargebackStatusEnum
    countryCodeString国家代码
    remarkString备注
    expirationTimeLong拒付截止时间(时间戳,毫秒)
    categoryString拒付阶段分类,参见 ChargebackCategoryEnum
    chargebackReasonCodeString渠道拒付原因码(如 81、4837)
    chargebackReasonDescString渠道拒付原因描述
    evidenceRequiredDescString争议原因所需凭证说明文案

    响应示例

    {
      "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

    请求参数

    字段名类型必填说明
    uniqBizIdString是业务唯一标识
    decisionString是商户决策结果,参见 MerchantDecisionStatusEnum,可选值:ACCEPT、REJECT
    decisionReasonString否拒绝退款原因(decision 为 REJECT 时建议填写)
    openAttachmentListString否扩展字段,JSON array格式
    countryCodeString是国家代码

    请求示例 - 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\"]"
        ]
    }'

    响应参数

    字段名类型说明
    respCodeString响应码
    respMsgString响应信息
    datanull无返回数据

    响应示例

    {
      "respCode": "000000",
      "respMsg": "success",
      "data": null
    }

    拒付单详情查询

    根据业务唯一标识查询拒付单详情。

    URL:POST /api/chargeback/merchant/detail

    请求参数

    字段名类型必填说明
    uniqBizIdString是业务唯一标识
    countryCodeString是国家代码

    请求示例

    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"
    }'

    响应参数

    字段名类型说明
    respCodeString响应码
    respMsgString响应信息
    dataChargebackMerchantOrderDto拒付单详情,结构同 查询接口的 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 次)重新推送。

    通知参数

    字段名类型说明
    createTimeLong渠道拒付单创建时间(时间戳,毫秒)
    uniqBizIdString业务唯一标识
    merchantIdString商户 ID
    orderNoString原交易单号
    orderAmountLong原交易单金额(最小单位,如分)
    orderCurrencyString币种
    transactionTimeLong原单交易创建时间(时间戳,毫秒)
    statusString商户侧拒付状态,参见 MerchantChargebackStatusEnum
    countryCodeString国家代码
    remarkString备注
    expirationTimeLong拒付截止时间(时间戳,毫秒)
    categoryString拒付阶段分类,参见 ChargebackCategoryEnum
    chargebackReasonCodeString渠道拒付原因码
    chargebackReasonDescString渠道拒付原因描述
    evidenceRequiredDescString争议原因所需凭证说明文案

    通知示例

    {
      "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>"
    }
    字段名类型说明
    respCodeString响应码,000000 表示成功
    respMsgString响应描述
    dataT业务数据,类型由具体接口决定