• English
  • Chargeback API Documentation

    This API documentation is intended for PalmPay merchants, providing chargeback inquiry, decision processing, detail inquiry, and asynchronous notification capabilities.

    Query Chargeback List

    Query chargebacks that require merchant decision, with pagination support.

    /api/chargeback/merchant/query

    Request Parameters

    FieldTypeRequiredDescription
    pageIndexintYesPage number (starting from 0 or 1, depending on server configuration)
    pageSizeintYesNumber of records per page
    orderNoStringNoOriginal transaction order number
    startCreateTimeLongNoChannel chargeback creation time - start (timestamp, milliseconds)
    endCreateTimeLongNoChannel chargeback creation time - end (timestamp, milliseconds)
    statusStringNoMerchant-side chargeback status, see MerchantChargebackStatusEnum
    countryCodeStringYesCountry code, see CountryEnum
    currencyStringNoCurrency code, see CurrencyEnum

    Request Example

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

    Response Parameters

    FieldTypeDescription
    respCodeStringResponse code
    respMsgStringResponse message
    dataPageWrapper<ChargebackMerchantOrderDto>Paginated data

    PageWrapper Structure:

    FieldTypeDescription
    totalCountLongTotal record count
    pageSizeIntegerRecords per page
    pageIndexIntegerCurrent page number
    listList<ChargebackMerchantOrderDto>Data list

    ChargebackMerchantOrderDto Structure:

    FieldTypeDescription
    createTimeLongChannel chargeback creation time (timestamp, milliseconds)
    uniqBizIdStringUnique business ID
    merchantIdStringMerchant ID
    orderNoStringOriginal transaction order number
    orderAmountLongOriginal transaction amount (smallest unit, e.g. cents)
    orderCurrencyStringCurrency code
    transactionTimeLongOriginal transaction creation time (timestamp, milliseconds)
    statusStringMerchant-side chargeback status, see MerchantChargebackStatusEnum
    countryCodeStringCountry code
    remarkStringRemark
    expirationTimeLongChargeback deadline (timestamp, milliseconds)
    categoryStringChargeback stage category, see ChargebackCategoryEnum
    chargebackReasonCodeStringChannel chargeback reason code (e.g. 81, 4837)
    chargebackReasonDescStringChannel chargeback reason description
    evidenceRequiredDescStringDescription of evidence required for dispute

    Response Example

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

    Merchant Decision

    Merchant accepts or rejects a chargeback.

    URL: POST /api/chargeback/merchant/decision

    Request Parameters

    FieldTypeRequiredDescription
    uniqBizIdStringYesUnique business ID
    decisionStringYesMerchant decision result, see MerchantDecisionStatusEnum, options: ACCEPT, REJECT
    decisionReasonStringNoReason for rejection (recommended when decision is REJECT)
    openAttachmentListStringNoAttachment list (e.g. evidence image URLs),jason array
    countryCodeStringYesCountry code

    Request Example - url upload

    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": "Goods delivered on time, delivery confirmation received",
        "countryCode": "NG",
        "openAttachmentList": [
            "https://example.com/evidence1.png",
            "https://example.com/evidence2.pdf"
        ]
    }'

    Request Example - base64 upload

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

    Response Parameters

    FieldTypeDescription
    respCodeStringResponse code
    respMsgStringResponse message
    datanullNo data returned

    Response Example

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

    Chargeback Detail Inquiry

    Query chargeback details by unique business ID.

    URL: POST /api/chargeback/merchant/detail

    Request Parameters

    FieldTypeRequiredDescription
    uniqBizIdStringYesUnique business ID
    countryCodeStringYesCountry code

    Request Example

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

    Response Parameters

    FieldTypeDescription
    respCodeStringResponse code
    respMsgStringResponse message
    dataChargebackMerchantOrderDtoChargeback details, same structure as DTO description in query API

    Response Example

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

    Chargeback Notification (Async Callback)

    When a chargeback status changes, PalmPay sends an asynchronous notification to the merchant's registered callback URL.

    Merchants must return HTTP 200 OK upon receiving the notification to confirm receipt. If 200 is not returned, PalmPay will retry according to the retry policy (10-minute intervals, up to 3 retries).

    Notification Parameters

    FieldTypeDescription
    createTimeLongChannel chargeback creation time (timestamp, milliseconds)
    uniqBizIdStringUnique business ID
    merchantIdStringMerchant ID
    orderNoStringOriginal transaction order number
    orderAmountLongOriginal transaction amount (smallest unit, e.g. cents)
    orderCurrencyStringCurrency code
    transactionTimeLongOriginal transaction creation time (timestamp, milliseconds)
    statusStringMerchant-side chargeback status, see MerchantChargebackStatusEnum
    countryCodeStringCountry code
    remarkStringRemark
    expirationTimeLongChargeback deadline (timestamp, milliseconds)
    categoryStringChargeback stage category, see ChargebackCategoryEnum
    chargebackReasonCodeStringChannel chargeback reason code
    chargebackReasonDescStringChannel chargeback reason description
    evidenceRequiredDescStringDescription of evidence required for dispute

    Notification Example

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

    Appendix A: Enum Definitions

    MerchantDecisionStatusEnum

    Merchant decision status.

    Enum ValueDescription
    ACCEPTAccept (agree to refund)
    REJECTReject (disagree to refund)

    MerchantChargebackStatusEnum

    Chargeback status displayed on the merchant platform, determined by the final chargeback status and the merchant's decision.

    Enum ValueDescription
    WAIT_DEALPending (merchant has not yet decided)
    PROCESSINGProcessing (merchant has decided, chargeback not yet finalized)
    ACCEPTAccepted
    REJECTRejected
    TIME_OUT_REJECTAuto-rejected due to timeout

    ChargebackCategoryEnum

    Chargeback stage category (response field category).

    Enum ValueDescription
    PRE_CHARGEBACKPre-chargeback stage
    CHARGEBACKFormal chargeback
    FRAUDFraud
    PRE_ARBITRATIONPre-arbitration

    CountryEnum

    Country code, internal enumeration.

    Enum ValueDescription
    NGNigeria
    GHGhana
    ZASouth Africa

    CurrencyEnum

    Currency code, internal enumeration.

    Enum ValueDescription
    NGNNigerian Naira
    GHSGhanaian Cedi
    ZARSouth African Rand

    Appendix B: Common Response Structure

    All APIs use the unified RespResult<T> response wrapper.

    {
      "respCode": "000000",
      "respMsg": "success",
      "data": "<T>"
    }
    FieldTypeDescription
    respCodeStringResponse code, 000000 indicates success
    respMsgStringResponse description
    dataTBusiness data, type determined by the specific API