Card chargeback

Fires when the payment provider reports a chargeback on an already processed order: the cardholder disputed the charge or their bank reversed it.

This event arrives about a charge you already treated as good. If you marked the debt as paid, you have to reverse that state in your system here.


`type`	`CARD_PAYMENT_CHARGEBACK`
`status`	Not applicable: this event carries no `status`
Idempotency key	`operationId`

The payload

Field	Type	Present	Description
`type`	String	Always	Always `"CARD_PAYMENT_CHARGEBACK"`.
`operationId`	String	Always	Identifier of the affected order.
`chargebackReason`	String \| null	Variable	Chargeback reason, from the closed catalog below. `null` when the provider reports no reason.
`chargebackDate`	String	Always	Chargeback date, in ISO 8601.
`amount`	Number	Always	Chargeback amount.
`currency`	String	Always	Chargeback currency, for example `"MXN"`.
`companyCode`	String \| null	Always	Company code. The key is always there; the value can be `null`.
`companyName`	String \| null	Always	Company name. Same rule as `companyCode`.
`hash`	String \| null	Always	Verification hash. `null` if you have no public key configured.

This payload carries no status, because a chargeback does not describe the state of a payment but a later fact about an already processed charge. It carries no bank either: that belongs to the bank debit events.

Chargeback reasons

chargebackReason is a closed catalog, unlike the bank debit chargeback, where it is free text. You can branch your logic on these values with confidence. The possible values are FRAUD, DUPLICATE, NOT_AS_DESCRIBED, NOT_RECEIVED and UNRECOGNIZED. The reason is reported by the payment provider.

The reason always arrives uppercase, in its canonical form, no matter how the provider wrote it. A reason outside the catalog is rejected in validation and the notification is not delivered, so you will never receive an unexpected value in this field. What you can receive is null.

Examples

{
  "type": "CARD_PAYMENT_CHARGEBACK",
  "operationId": "ORD-88888",
  "chargebackReason": "FRAUD",
  "chargebackDate": "2026-07-09T14:30:00Z",
  "amount": 25000,
  "currency": "MXN",
  "companyCode": "MX-S-12345",
  "companyName": "ACME",
  "hash": "encrypted-base64-string"
}

{
  "type": "CARD_PAYMENT_CHARGEBACK",
  "operationId": "ORD-88888",
  "chargebackReason": null,
  "chargebackDate": "2026-07-09T14:30:00Z",
  "amount": 25000,
  "currency": "MXN",
  "companyCode": "MX-S-12345",
  "companyName": "ACME",
  "hash": null
}

Common fields, hash and idempotency

What every webhook in this family shares.

Get started

What's new

Concepts

Resources

Payment portal

Webhooks

Card chargeback

The payload

Chargeback reasons

Examples

Common fields, hash and idempotency

​The payload

​Chargeback reasons

​Examples

Common fields, hash and idempotency

The payload

Chargeback reasons

Examples