Dispute chargebacks
Embed the Chargeback Report Component in your platform to dispute chargebacks
A chargeback occurs when a customer contacts their issuing bank (e.g. Capital One, American Express, Chase) and disputes a payment on their credit card. Head over to the understanding chargebacks guide to learn more about chargebacks and their phases.
Chargebacks can be actioned using Rainforest's reporting components:
- Chargeback Report Component
- Chargeback Details in the Payment Report Component
- Chargeback Respond Component
Embed the chargeback report
Session authentication
Create a session to grant the chargeback report component permissions to view and action chargebacks. The session should include at least the following permissions to view chargebacks and their related payins and refunds:
curl --location 'https://api.rainforestpay.com/v1/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{api_key}}' \
--data '{
"ttl": 86400,
"statements": [
{
"permissions": ["group#chargeback_report_component"]
}
]
}'
Session constraints
If the component permissions are constrained to a specific resource, data filters will need to be applied to give the chargeback report component the same level of permissions.
Commonly, the chargeback report is pre-loaded to show chargebacks for a single merchant. The session should be constrained to a specific merchant to ensure this session only has permissions to view the chargebacks associated to the merchant:
curl --location 'https://api.rainforestpay.com/v1/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{api_key}}' \
--data '{
"ttl": 86400,
"statements": [
{
"permissions": [
"group#chargeback_report_component",
],
"constraints": {
"merchant: {
"merchant_id": "REPLACE_ME"
}
}
}
]
}'
Actions permissions
Enable the user to have permissions to respond to chargebacks, as well as other actions such as refunding a payin associated to a chargeback. If the user should not have action permissions, then omit the respective groups.
Permission | Description |
---|---|
group#chargeback_report_component.update_chargeback | Respond to a chargeback or accept the loss when navigating to the Chargeback Details Component. |
group#chargeback_report_component.create_refund | Refund a payin associated to a chargeback when navigating to the Payin Details Component. |
{
"ttl": 86400,
"statements": [
{
"permissions": [
"group#chargeback_report_component",
+ "group#chargeback_report_component.update_chargeback"
+ "group#chargeback_report_component.create_refund"
],
"constraints": {
"merchant: {
"merchant_id": "REPLACE_ME"
}
}
}
]
}
JavaScript bundle
Include the merchant JavaScript bundle in your frontend to access the chargeback report component.
<script type="module" src="https://static.rainforestpay.com/sandbox.merchant.js"></script>
Chargeback report component
Add the Rainforest chargeback report component with custom configuration designed in the component studio.
<rainforest-chargeback-report
session-key="REPLACE_ME"
></rainforest-chargeback-report>
Migrating from older API versions
If you are integrated against a previous API version and your minimum API version is not 2024-10-16, then you'll need to set the api-version
prop to 2024-10-16
. See the API version upgrades guide for more information.
<rainforest-chargeback-report
session-key="REPLACE_ME"
api-version="2024-10-16"
></rainforest-chargeback-report>
Column configuration
The chargeback report will load with a set of default columns. Simply omit the columns
prop to use the following default columns.
[
{"name":"Created","type":"builtin","value":"created"},
{"name":"Status","type":"builtin","value":"status"},
{"name":"Amount","type":"builtin","value":"amount"},
{"name":"Customer","type":"builtin","value":"name"},
{"name":"Method","type":"builtin","value":"method"},
{"name":"Due Date","type":"builtin","value":"due_date"},
{"name":"ARN","type":"builtin","value":"acquirer_ref"},
{"name":"Merchant Name","type":"builtin","value":"merchant_name"}
]
Custom configuration
Columns can be customized to fit the needs of your platform. To override the default columns for the chargeback report, pass in the column specifications via a JSON payload in the columns
prop.
<rainforest-chargeback-report
columns='[{"name":"My Custom Column Name","type":"builtin","value":"id"}]'
></rainforest-chargeback-report>
A column specification needs a name
, type
, and value
.
name
- The display header name for the column.type
- Set tobuiltin
ormetadata
value
- The key corresponding to a value returned from the list payments endpoint.
Valid column values
Type | Value | Description |
---|---|---|
builtin | id | The unique chargeback identifier. Corresponds to the chargeback_id field. |
builtin | merchant_id | The unique merchant identifier. Corresponds to the merchant_id field. |
builtin | merchant_name | The name of the merchant. Corresponds to the merchant.name field. |
builtin | created | The datetime the chargeback was created at. Corresponds to the created_at field. |
builtin | amount | The amount of the chargeback. Corresponds to the amount field. |
builtin | name | The billing contact name for the chargeback. Corresponds to the billing_contact.name field. |
builtin | billing_contact_email | The billing contact email for the chargeack. Corresponds to the billing_contact.email field. |
builtin | status | The status of the chargeback. Corresponds to the status field. |
builtin | method | The payment method for the chargeback. Corresponds to the method_type field and the last 4 digits of the card or bank account. |
builtin | due_date | The due date for the chargeback. Corresponds to the due_date field. |
builtin | acquirer_ref | The Acquirer Reference Number (ARN) for the chargeback. Corresponds to the acquirer_ref field. |
metadata | JSONPath to metadata key | The metadata for the chargeback. Corresponds to the metadata field. |
Metadata column
A column can be configured to display a custom metadata value passed into the config requests for varying payment activities. The value
for type metadata
should be valid JSONPath to a corresponding metadata key.
For example, a payin created with the following metadata
{
"account": {
"id": "123",
"name": "Jane Doe",
"email": "[email protected]
}
}
could have the following column specification to display the metadata account id
{
"name": "Account ID",
"type": "metadata",
"value": "$.account.id"
}
Payin metadata is persisted to the associated chargebacks.
Templating columns
If you need to format the metadata for presentation to your users, you can specify a template pattern. In order to show the Account ID as above, but formatted as "Account #123". You can specify a template string, and the pattern {{value}}
will be replaced with the value of the field:
{
"name": "Account ID",
"type": "metadata",
"value": "$.account.id",
"template": "Account #{{value}}"
}
Data filters
The chargeback report can be pre-loaded with a defined set of filters, including sort by and sort order. Data filters are defined by a JSON payload of key-value pairs passed into the data-filters
prop.
A valid key
includes any of the query params from the list payments endpoint. To pass multiple values for a given key, the value can be defined as an array of values.
{
"merchant_id": "mid_123",
"status": ["INQUIRY_ACTION_REQUIRED", "DISPUTE_ACTION_REQUIRED"],
"sort_by": "created_at",
"sort_order": "desc"
}
Data filters will always be applied to the report and any additional filtering via the component will be in addition to the filters passed in.
Embed a merchant work queue
Merchants will need to know what chargebacks they need to work and respond to. Filtering the chargeback report to the statuses of Inquiry Action Required and Dispute Action Required will show all the chargebacks the merchant needs to action.
Tabs in the report
Rainforest provides tabs in the Chargeback Report Component to quickly view chargebacks grouped by statuses. The Action Required tab allows your merchants to see all chargebacks that they need to respond to.
To enable the tabs within the Chargeback Report, add the prop show-tabs
<rainforest-chargeback-report
+ show-tabs
></rainforest-chargeback-report>
Custom filtering
You can also build your own custom merchant work queue by embedding the report with a status filter defined in the data-filters
prop.
Action required
Pre-load the chargeback report with chargebacks the merchant needs to respond to:
<rainforest-chargeback-report
+ data-filters='{"status":["INQUIRY_ACTION_REQUIRED", "DISPUTE_ACTION_REQUIRED"], "merchant_id":"REPLACE_ME"}'
></rainforest-chargeback-report>
Simulate chargeback scenarios in sandbox
In production, some chargeback statuses can only be reached when the issuing bank decisions the chargeback or the customer initiates a phase of the chargeback.
In order to simulate these scenarios in sandbox, first simulate a chargeback against a payin to create a chargeback. A chargeback can be initiated into one of the following statuses:
- Inquiry Action Required
- Dispute Action Required
Once a chargeback is created, you can respond to the chargeback via the chargeback report components. This will move the chargeback to one of the following statuses depending on the previous status:
- Inquiry Action Required → Inquiry Processing
- Dispute Action Required → Chargeback Processing
Then, you can simulate the decisions made by the issuing bank or customer with the simulate chargeback status change endpoint. A chargeback can be simulated to one of the following statuses:
- Dispute Action Required
- Provisional Win
- Won
- Lost
See the chargeback status diagram for the various statuses a chargeback can transition into given the current chargeback status.
Updated 15 days ago