Webhooks can be configured to receive updates on every status change that occurs through the lifecycle of a chargeback.

Chargeback events

📘

Available on API version 2024-10-16

If you are integrated against a previous API version and your minimum API version is not 2024-10-16, then you'll need to upgrade your API version to 2024-10-16 to access the Chargeback webhooks in Production. See the API version upgrades guide for more information.

Events

It's recommended that your platform listen to the following Rainforest webhooks to notify your platform, the merchant, and the end user on key events for chargebacks. We'll break down each webhook event and if the following notifications should be sent:

• Internal Notification - notify your platform support team so they can assist your merchants
• Merchant Notification - notify your merchants via an email or alert within your platform
• End User (Payor) Notification - notify the end user (payor) of the result of the payin

Payload

The webhook payload consists of:

• data - represents all chargeback fields returned by the get chargeback endpoint
• event_type - chargeback events denoted by the format of chargeback.{chargeback_status}

{
    "data": {
        "chargeback_id": "chb_2sOgSgPTWQ8tuxhSn0DeIdLDUjm",
        "payin_id": "pyi_2sOgTXis06bBZ1rvxyqcoBWo1nq",
        // ...
        "status": "INQUIRY_ACTION_REQUIRED",
        // ...
    },
    "event_type": "chargeback.inquiry_action_required"
}

Inquiry action required

Event: chargeback.inquiry_action_required

Triggered when a chargeback is in the inquiry phase and the merchant can respond by providing evidence that the payment was valid.

External notification example

The following example is an external notification to be sent your merchant:

[System Alert - Action Required] The PlatformPay team is reaching out to inform you that an Inquiry Chargeback has been initiated against the following payment. Do not worry, this is simply a customer requesting more information about the payment and no funds have been debited from your account at this time.

You will need to upload additional documentation for this payment that will allow the cardholder to confirm this payment was initiated by them. Typically, a copy of a signed receipt and/or a copy of the invoice will satisfy the cardholder’s request. You can upload these documents using the link below.

Please be advised that responses for chargeback inquiries are time sensitive. Failure to upload this supporting documentation in a timely manner will dramatically decrease your chances at winning any future chargebacks that could arise from this inquiry.

Chargeback ID: #123456789 {insert chargeback ID}

Amount: $100 {insert chargeback amount}

Payment for Invoice: #1234 {insert invoice ID}

Reason Code: Services Not Rendered {insert chargeback reason description}

Due Date: xx/xx/xxxx {insert chargeback due date}

Upload documentation here: {insert link to Chargeback Management Component}

Inquiry processing

Event: chargeback.inquiry_processing

Triggered when a merchant responds to the inquiry and the cardholder's bank is now decisioning the inquiry.

Dispute action required

Event: chargeback.dispute_action_required

Triggered when a chargeback is in the dispute phase and the merchant can respond by providing evidence that the payment was valid.

External notification example

The following example is an external notification to be sent your merchant:

[System Alert] The PlatformPay team is reaching out to inform you that a chargeback has been initiated against the following payment. While this means the funds have been temporarily provided back to the cardholder and you can contest the dispute in an attempt to have the funds returned to your account.

To respond to the dispute, you will need to log in to your PlatformPay chargeback management tool and upload evidence explaining why this is a valid payment. If the card issuer finds your evidence satisfactory, they will return the funds to you. We encourage you to review the reason code below when uploading evidence. The evidence required to reverse the chargeback in your favor will depend on the specific reason code for the chargeback.

Responding to a chargeback is time sensitive and failure to upload your evidence by the due date listed below will result in the funds being permanently returned to the cardholder.

Chargeback ID: #123456789 {insert chargeback ID}

Amount: $100 {insert chargeback amount}

Payment for Invoice: #1234 {insert invoice ID}

Reason Code: Services Not Rendered {insert chargeback reason description}

Due Date: xx/xx/xxxx {insert chargeback due date}

Upload documentation here: {insert link to Chargeback Management Component}

Chargeback processing

Event: chargeback.chargeback_processing

Triggered when a merchant responds to the dispute and the cardholder's bank is now decisioning the chargeback.

Note: if the chargeback moved from Created to Chargeback Processing, then Rainforest responded to the chargeback on the merchant's behalf. This can occur when the chargeback did not include the necessary information for the merchant to dispute.

Provisional win

Event: chargeback.privisional_win

Triggered when a merchant provisionally wins the chargeback, meaning the chargeback can still be lost while the cardholder's bank finalizes their decision. Funds will be returned to the merchant. But if the chargeback's win is reversed and the chargeback moves from Provision Win to Lost, the funds will be pulled back from the merchant.

Lost

Event: chargeback.lost

Triggered when a chargeback is ruled in favor of the cardholder and the merchant loses the chargeback. This is final and the merchant cannot overturn this decision.

Won

Event: chargeback.won

Triggered when a chargeback is ruled in favor of the merchant and the merchant wins the chargeback. This is final and the cardholder cannot overturn this decision.