Chargebacks
Chargebacks are disputes that your customers raise through their banks.
Typically, When a customer has some grievances regarding a transaction, they raise this with the merchant first. If ignored, this is escalated to their banks and a chargeback is raised against the merchant.
When a chargeback is raised, it has to be settled properly. The merchant can choose to accept the chargeback and return the customer's money or they can refute it, providing evidence of value provided for the transaction.
The chargeback lifecycle
-
The customer reports the transaction at their Bank.
-
The customer’s issuing bank initiates a chargeback request through Flutterwave’s acquiring bank.
-
Our acquiring bank debits the chargeback value from Flutterwave’s account.
-
Flutterwave notifies the merchant about the chargeback raised, requesting proof of service/value and supporting documents. The expected response timeline from the merchant is 48 hours from the notification time.
-
Flutterwave responds to the acquiring bank using the merchant’s response.
-
If the evidence provided is accepted, the issuing bank is debited and the credit is passed on to the merchant's settlement. Otherwise, the chargeback transaction is accepted.
Managing your chargebacks
Nobody hopes to receive a chargeback, however if you receive one here's how you can resolve it:
-
Review the reported transaction and gather enough evidence and information to address the chargeback.
-
Accept or decline the transaction based on the information you have:
- In cases where the customer actually did not get value for the payment, you should accept the chargeback.
- For transactions where you have evidence of providing value, decline the chargeback using the evidence you have gathered.
Accepting Chargebacks
To accept a chargeback, you'll need to first get the chargeback information. There are three ways to fetch the chargeback details:
-
Flutterwave notifies you about chargebacks via your email. You can get the
chargeback_idfrom the email sent.- We also send webhooks to your server when a chargeback is raised. This notification service is available on request.
-
You can query the get all chargeback endpoint to fetch details of all chargebacks raised against your account.
// chargeback query response
{
"status": "success",
"message": "Chargebacks fetched",
"meta": {
"page_info": {
"total": 3,
"current_page": 1,
"total_pages": 1,
"page_size": 20
}
},
"data": [
{
"id": 2221,
"amount": 3000,
"flw_ref": "0550726510071683619721660",
"status": "lost",
"stage": "pre-arbitration",
"comment": "Product/service not received",
"meta": {
"uploaded_proof": null,
"history": [
{
"merchant_type": "RR",
"date": "2024-08-01T04:58:20.000Z"
},
{
"action": "notification",
"date": "2024-08-01T04:58:25.000Z",
"description": "Email Notification Sent"
},
{
"action": "hooknotifier",
"status": "initiated",
"url": "https://webhook.site/6dcb649f-e3b5-47c1-8ce6-aa356dd913c5",
"date": "2024-08-01T04:58:26.000Z",
"description": "Hook Notification Successful"
},
{
"action": "lost",
"stage": "pre-arbitration",
"date": "2024-08-04T06:49:49.000Z",
"description": "No merchant response",
"source": "availablebalance"
},
{
"action": "hooknotifier",
"status": "lost",
"url": "https://webhook.site/6dcb649f-e3b5-47c1-8ce6-aa356dd913c5",
"date": "2024-08-04T06:50:14.000Z",
"description": "Hook Notification Successful"
}
]
},
"due_date": "2024-08-03T15:59:59.000Z",
"settlement_id": "N/A",
"created_at": "2024-08-01T16:58:20.000Z",
"transaction_id": 674630970,
"tx_ref": "TEST-1683619718017"
},
{
"id": 2209,
"amount": 3000,
"flw_ref": "0550726510071683619721660",
"status": "declined",
"stage": "new",
"comment": "Cancelled merchandise/Service",
"meta": {
"uploaded_proof": "https://cdn.filestackcontent.com/k7QmL7JnT2Gir8NAcDLV",
"history": [
{
"merchant_type": "RR",
"date": "2024-06-29T10:18:20.000Z"
},
{
"action": "notification",
"date": "2024-06-29T10:18:24.000Z",
"description": "Email Notification Sent"
},
{
"action": "hooknotifier",
"status": "initiated",
"url": "https://webhook.site/af39071c-990f-4c6e-8519-ce4ce8c7e0dd",
"date": "2024-06-29T10:18:25.000Z",
"description": "Hook Notification Failed"
},
{
"action": "decline",
"stage": "second",
"url": "https://cdn.filestackcontent.com/k7QmL7JnT2Gir8NAcDLV",
"date": "2024-06-29T10:19:16.000Z",
"description": "Merchant denies claim with a proof",
"comment": "Goods or services not provided"
},
{
"action": "hooknotifier",
"status": "declined",
"url": "https://webhook.site/af39071c-990f-4c6e-8519-ce4ce8c7e0dd",
"date": "2024-06-29T10:19:19.000Z",
"description": "Hook Notification Failed"
},
{
"action": "update",
"stage": "new",
"date": "2024-08-01T04:57:10.000Z",
"description": "Chargeback stage moved from second to new"
}
]
},
"due_date": "2024-07-02T15:59:59.000Z",
"settlement_id": null,
"created_at": "2024-06-29T22:18:20.000Z",
"transaction_id": 674630970,
"tx_ref": "TEST-1683619718017"
},
{
"id": 2208,
"amount": 12,
"flw_ref": "1678612858171667820797946",
"status": "declined",
"stage": "second",
"comment": "Cancelled merchandise/Service",
"meta": {
"uploaded_proof": "https://cdn.filestackcontent.com/k7QmL7JnT2Gir8NAcDLV",
"history": [
{
"merchant_type": "RR",
"date": "2024-06-27T02:52:42.000Z"
},
{
"action": "notification",
"date": "2024-06-27T02:52:47.000Z",
"description": "Email Notification Sent"
},
{
"action": "hooknotifier",
"status": "initiated",
"url": "https://webhook.site/af39071c-990f-4c6e-8519-ce4ce8c7e0dd",
"date": "2024-06-27T02:52:47.000Z",
"description": "Hook Notification Failed"
},
{
"action": "decline",
"stage": "second",
"url": "https://cdn.filestackcontent.com/6afXmGsURPmsW04L3jbj",
"date": "2024-06-27T02:54:54.000Z",
"description": "Merchant denies claim with a proof",
"comment": "Dispute not remedied"
},
{
"action": "hooknotifier",
"status": "declined",
"url": "https://webhook.site/af39071c-990f-4c6e-8519-ce4ce8c7e0dd",
"date": "2024-06-27T02:54:58.000Z",
"description": "Hook Notification Failed"
}
]
},
"due_date": "2024-07-01T15:59:59.000Z",
"settlement_id": null,
"created_at": "2024-06-27T14:52:42.000Z",
"transaction_id": 674619323,
"tx_ref": "TEST-1667820797124"
}
]
}
After you have gotten your chargeback id, send accept as the action to the accept chargeback endpoint.
{
"action": "accept",
"comment": "We provided value to the customer for the reported transaction. See image in proof for more information"
}
{
"status":"success",
"message":"Chargeback accepted",
"data":{
"id":1189809,
"amount":700,
"flw_ref":"1557524181291683290514710",
"status":"accepted",
"stage":"new",
"comment":"testing",
"due_date":"2023-09-30T15:59:59.000Z",
"settlement_id":"N/A",
"created_at":"2023-09-29T08:15:46.000Z",
"meta":{
"uploaded_proof":"https//www.example.com/prooflink",
"history":[
{
"action":"comment",
"stage":"new",
"date":"2023-09-29T08:17:50.000Z",
"description":"A comment has been added to the chargeback log"
},
{
"action":"update",
"stage":"second",
"date":"2023-09-29T08:18:28.000Z",
"description":"Chargeback comment updated from testing... to testing"
},
{
"action":"update",
"stage":"new",
"date":"2023-09-29T08:19:14.000Z",
"description":"Chargeback comment updated from testing to testing..."
},
{
"action":"update",
"stage":"new",
"date":"2023-09-29T08:20:04.000Z",
"description":"Chargeback comment updated from testing... to testing"
},
{
"action":"initiated",
"stage":"new",
"date":"2023-09-29T08:20:26.000Z",
"description":"Debit and hold chargeback amount"
},
{
"action":"accept",
"stage":"new",
"date":"2023-09-29T08:20:57.000Z",
"description":"Merchant Accepts"
}
]
}
}
}
{
"event":"chargeback.accepted",
"data":{
"id":1189809,
"flw_ref":"JXPS53161680612784483225",
"amount":180,
"comment":"Internal test of chargeback webhooks",
"status":"accepted",
"stage":"new",
"due_date":"2023-04-19T15:59:59.000Z",
"type":"local",
"created_at":"2023-04-18T12:13:01.000Z",
"account_id":1829290
}
}
Declining a Chargeback
Refuting a chargeback requires some proof. You'll need to first upload the evidence. Use these tips to properly provide evidence:
-
Combine all relevant documents into a single file, you can scan multiple documents and merge them together.
-
Label the document clearly and append the chargeback_id for easy identification.
-
Share the proof using the upload proof endpoint.
After you successfully upload your evidence, we would return a success response:
{
"status":"success",
"message":"Image sucessfully uploaded",
"data":"https://cdn.filestackcontent.com/UQbCwqvSvyf2AsTffV2D"
}
Using the chargeback_id and the prooflink, you can decline the chargeback. Send your evidence, action (decline) and comment to the decline chargeback endpoint.
{
"action":"decline",
"prooflink":"https://cdn.filestackcontent.com/UQbCwqvSvyf2AsTffV2D",
"comment":"The Service has been provided, refer to the proof for more details."
}
{
"Status":"success",
"message":"Chargeback declined",
"data":{
"id":2109,
"amount":700,
"flw_ref":"1557524181291683290514710",
"status":"declined",
"stage":"new",
"comment":"testing",
"due_date":"2023-09-30T15:59:59.000Z",
"settlement_id":"N/A",
"created_at":"2023-09-29T08:15:46.000Z",
"meta":{
"uploaded_proof":"https//www.example.com/prooflink",
"history":[
{
"action":"comment",
"stage":"new",
"date":"2023-09-29T08:17:50.000Z",
"description":"A comment has been added to the chargeback log"
},
{
"action":"update",
"stage":"second",
"date":"2023-09-29T08:18:28.000Z",
"description":"Chargeback comment updated from testing... to testing"
},
{
"action":"update",
"stage":"prearbitary",
"date":"2023-09-29T08:19:14.000Z",
"description":"Chargeback comment updated from testing to testing..."
},
{
"action":"update",
"stage":"new",
"date":"2023-09-29T08:20:04.000Z",
"description":"Chargeback comment updated from testing... to testing"
},
{
"action":"initiated",
"stage":"new",
"date":"2023-09-29T08:20:26.000Z",
"description":"Debit and hold chargeback amount"
},
{
"action":"decline",
"stage":"new",
"date":"2023-09-29T08:20:57.000Z",
"description":"Merchant denies claim with a proof"
}
]
}
}
}
{
"event":"chargeback.declined",
"data":{
"id":1189808,
"flw_ref":"SZFY85201680612767705172",
"amount":170,
"comment":"Internal test of chargeback webhooks",
"status":"declined",
"stage":"new",
"due_date":"2023-04-19T15:59:59.000Z",
"type":"local",
"created_at":"2023-04-18T12:10:52.000Z",
"account_id":1829290
}
}
Chargeback status and stages
When you decline the chargeback, we'll notify you via email but this is not the end of the process. The customer's bank may provide more information and take this to arbitration.
To make this seamless, Flutterwave updates you at every step of the dispute resolution process. These are some of the status and stages to keep an eye out for.
| Chargeback Status | Meaning |
|---|---|
| Initiated | The customer's bank has raised a chargeback against FLW acquirer bank and right amount withheld from merchant balance. Merchant is notified. |
| Pending | Flutterwave has notified the merchant, but no action has been taken yet. |
| Accepted | The merchant accepts the chargeback. |
| Declined | The merchant denies the chargeback with a claim of proof. |
| Won | The Merchant’s proof for denying the claim has been accepted, hence the customer will not be refunded. |
| Lost | The dispute failed, and the customer will receive a refund or lack of response from the merchant before the due date(48hours). |
| Reversed | The amount withheld from the merchant's balance has been restored. |
| Chargeback Stages | Meaning |
|---|---|
| New | A new chargeback with no previous occurrence. |
| Second | Relogging a chargeback on the same transaction after the first (New) is closed. |
| Pre-Arbitration | The final opportunity to resolve a chargeback dispute before it escalates to arbitration. It allows for the submission of new evidence and requires careful consideration by the merchant. |
Chargeback Webhooks
We send webhooks to notify you about status changes for your chargebacks, these examples illustrate some of the webhooks we send:
{
"event":"chargeback.initiated",
"data":{
"id":22221,
"flw_ref":"0550726510071683619721660",
"amount":500,
"comment":"Product/service not received",
"status":"initiated",
"stage":"new",
"due_date":"2024-08-03T15:59:59.000Z",
"type":"local",
"created_at":"2024-08-01T16:58:20.000Z",
"account_id":1092727
}
}
{
"event":"chargeback.accepted",
"data":{
"id":1189809,
"flw_ref":"JXPS53161680612784483225",
"amount":180,
"comment":"Internal test of chargeback webhooks",
"status":"accepted",
"stage":"new",
"due_date":"2023-04-19T15:59:59.000Z",
"type":"local",
"created_at":"2023-04-18T12:13:01.000Z",
"account_id":1829290
}
}
{
"event":"chargeback.declined",
"data":{
"id":1189808,
"flw_ref":"SZFY85201680612767705172",
"amount":170,
"comment":"Internal test of chargeback webhooks",
"status":"declined",
"stage":"new",
"due_date":"2023-04-19T15:59:59.000Z",
"type":"local",
"created_at":"2023-04-18T12:10:52.000Z",
"account_id":1829290
}
}
{
"event":"chargeback.lost",
"data":{
"id":1189812,
"flw_ref":"VCEJ34271680612798237173",
"amount":190,
"comment":"Final test of chargeback webhooks",
"status":"lost",
"stage":"new",
"due_date":"2023-04-19T15:59:59.000Z",
"type":"local",
"created_at":"2023-04-18T13:55:42.000Z",
"account_id":1829290
}
}