#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
| Field | Type | Required | Description |
|---|---|---|---|
| pageIndex | int | Yes | Page number (starting from 0 or 1, depending on server configuration) |
| pageSize | int | Yes | Number of records per page |
| orderNo | String | No | Original transaction order number |
| startCreateTime | Long | No | Channel chargeback creation time - start (timestamp, milliseconds) |
| endCreateTime | Long | No | Channel chargeback creation time - end (timestamp, milliseconds) |
| status | String | No | Merchant-side chargeback status, see MerchantChargebackStatusEnum |
| countryCode | String | Yes | Country code, see CountryEnum |
| currency | String | No | Currency 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
| Field | Type | Description |
|---|---|---|
| respCode | String | Response code |
| respMsg | String | Response message |
| data | PageWrapper<ChargebackMerchantOrderDto> | Paginated data |
PageWrapper Structure:
| Field | Type | Description |
|---|---|---|
| totalCount | Long | Total record count |
| pageSize | Integer | Records per page |
| pageIndex | Integer | Current page number |
| list | List<ChargebackMerchantOrderDto> | Data list |
ChargebackMerchantOrderDto Structure:
| Field | Type | Description |
|---|---|---|
| createTime | Long | Channel chargeback creation time (timestamp, milliseconds) |
| uniqBizId | String | Unique business ID |
| merchantId | String | Merchant ID |
| orderNo | String | Original transaction order number |
| orderAmount | Long | Original transaction amount (smallest unit, e.g. cents) |
| orderCurrency | String | Currency code |
| transactionTime | Long | Original transaction creation time (timestamp, milliseconds) |
| status | String | Merchant-side chargeback status, see MerchantChargebackStatusEnum |
| countryCode | String | Country code |
| remark | String | Remark |
| expirationTime | Long | Chargeback deadline (timestamp, milliseconds) |
| category | String | Chargeback stage category, see ChargebackCategoryEnum |
| chargebackReasonCode | String | Channel chargeback reason code (e.g. 81, 4837) |
| chargebackReasonDesc | String | Channel chargeback reason description |
| evidenceRequiredDesc | String | Description 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
| Field | Type | Required | Description |
|---|---|---|---|
| uniqBizId | String | Yes | Unique business ID |
| decision | String | Yes | Merchant decision result, see MerchantDecisionStatusEnum, options: ACCEPT, REJECT |
| decisionReason | String | No | Reason for rejection (recommended when decision is REJECT) |
| openAttachmentList | String | No | Attachment list (e.g. evidence image URLs),jason array |
| countryCode | String | Yes | Country 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
| Field | Type | Description |
|---|---|---|
| respCode | String | Response code |
| respMsg | String | Response message |
| data | null | No 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
| Field | Type | Required | Description |
|---|---|---|---|
| uniqBizId | String | Yes | Unique business ID |
| countryCode | String | Yes | Country 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
| Field | Type | Description |
|---|---|---|
| respCode | String | Response code |
| respMsg | String | Response message |
| data | ChargebackMerchantOrderDto | Chargeback 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
| Field | Type | Description |
|---|---|---|
| createTime | Long | Channel chargeback creation time (timestamp, milliseconds) |
| uniqBizId | String | Unique business ID |
| merchantId | String | Merchant ID |
| orderNo | String | Original transaction order number |
| orderAmount | Long | Original transaction amount (smallest unit, e.g. cents) |
| orderCurrency | String | Currency code |
| transactionTime | Long | Original transaction creation time (timestamp, milliseconds) |
| status | String | Merchant-side chargeback status, see MerchantChargebackStatusEnum |
| countryCode | String | Country code |
| remark | String | Remark |
| expirationTime | Long | Chargeback deadline (timestamp, milliseconds) |
| category | String | Chargeback stage category, see ChargebackCategoryEnum |
| chargebackReasonCode | String | Channel chargeback reason code |
| chargebackReasonDesc | String | Channel chargeback reason description |
| evidenceRequiredDesc | String | Description 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 Value | Description |
|---|---|
| ACCEPT | Accept (agree to refund) |
| REJECT | Reject (disagree to refund) |
#MerchantChargebackStatusEnum
Chargeback status displayed on the merchant platform, determined by the final chargeback status and the merchant's decision.
| Enum Value | Description |
|---|---|
| WAIT_DEAL | Pending (merchant has not yet decided) |
| PROCESSING | Processing (merchant has decided, chargeback not yet finalized) |
| ACCEPT | Accepted |
| REJECT | Rejected |
| TIME_OUT_REJECT | Auto-rejected due to timeout |
#ChargebackCategoryEnum
Chargeback stage category (response field category).
| Enum Value | Description |
|---|---|
| PRE_CHARGEBACK | Pre-chargeback stage |
| CHARGEBACK | Formal chargeback |
| FRAUD | Fraud |
| PRE_ARBITRATION | Pre-arbitration |
#CountryEnum
Country code, internal enumeration.
| Enum Value | Description |
|---|---|
| NG | Nigeria |
| GH | Ghana |
| ZA | South Africa |
#CurrencyEnum
Currency code, internal enumeration.
| Enum Value | Description |
|---|---|
| NGN | Nigerian Naira |
| GHS | Ghanaian Cedi |
| ZAR | South African Rand |
#Appendix B: Common Response Structure
All APIs use the unified RespResult<T> response wrapper.
{
"respCode": "000000",
"respMsg": "success",
"data": "<T>"
}| Field | Type | Description |
|---|---|---|
| respCode | String | Response code, 000000 indicates success |
| respMsg | String | Response description |
| data | T | Business data, type determined by the specific API |