Chargebacks
Chargebacks happen when your customers dispute a transaction with their bank.
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 from the transaction.
The Chargeback Lifecycle
- First, the customer reports the transaction to 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 timeline to get a response 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 Chargebacks
If you receive a chargeback, 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 did not get the expected value from 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.
Integration Tips
These tips also apply when managing your chargebacks on your Flutterwave dashboard
Accepting a Chargeback
To accept a chargeback, you'll need to first get the chargeback information. There are three ways to fetch it:
- 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 make a request to the get all chargeback endpoint to fetch details of all chargebacks raised against your account.
Here's what the response would look like:
// 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"
}
You'll get a response like this:
{
"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
To dispute a chargeback, you need to provide proof. Start by uploading the necessary evidence. Use these tips to ensure you submit it correctly:
- Combine all relevant documents into a single file. You can scan multiple documents and merge them.
- Label the document clearly and append the
chargeback_idfor easy identification. - Share the proof using the uploaded proof endpoint.
Document Upload
The upload proof endpoint supports JPEG, JPG, PNG and PDF files. Your document should be less than 8MB.
After you've successfully uploaded your evidence, we'll return a successful 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. 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. Here are some of the statuses and stages to keep an eye out for.
| Chargeback Statuses | Meaning |
|---|---|
| initiated | The customer's bank has raised a chargeback against FLW acquirer bank, and the right amount is withheld from the merchant's 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 of 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(48 hours). |
| 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 Webhook
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
}
}
Updated about 1 month ago