Chargeback Webhooks

April 30, 2026

Chargebacks

Kushki can send webhook events that notify your application when any of the following changes occur in the status of a chargeback:

Initialized chargeback (INITIALIZED): Kushki receives the chargeback notification and you must upload the supporting documentation. The event will include a deadLine (in Unix format) with the deadline to do so.
Chargeback under review (REVIEW): you have successfully submitted the supporting documents and the chargeback is being analyzed. Kushki has a maximum of 60 days to notify you of the resolution.
Approved chargeback (APPROVAL): the chargeback was resolved in your favor. You will not lose the value of the sale.
Declined chargeback (DECLINED): the chargeback was resolved against you. You will lose the value of the sale.
Expired chargeback (EXPIRED): you did not upload the supporting documentation within the 15-day deadline. You will lose the value of the sale.

Chargeback status update notification

Structure

The chargeback webhooks sent by Kushki will contain the headers listed here. These are the possible variables that are delivered in the webhook body when a chargeback changes status:

Método: POST

Body: Object

Variable	Type
`country`	`string`
`iceValue`	`number`
`approvalCode`	`string`
`metadata`	`object`
`metadata.key0`	`string`
`subtotalIva0`	`string`
`credentialMetadata`	`string`
`productDetails`	`object`
`product`	`object`
`product.quantity`	`integer`
`product.price`	`number`
`product.id`	`string`
`product.tittle`	`string`
`product.sku`	`string`
`deadLine`	`number (Unix Timestamp Format)`
`transaction_details`	`object`
`transaction_details.cardType`	`string`
`transaction_details.binCard`	`string`
`transaction_details.processorBankName`	`string`
`transaction_details.isDeferred`	`string`
`merchantName`	`string`
`responseCode`	`string`
`credentialAlias`	`string`
`merchantId`	`string`
`ivaValue`	`number`
`syncMode`	`string`
`id`	`string`
`transaction_reference`	`string`
`transactionReference`	`string`
`vault_token`	`string`
`created`	`number (Unix Timestamp Format)`
`ip`	`string`
`transactionId`	`string`
`saleTicketNumber`	`string`
`lastFourDigits`	`string`
`credentialId`	`string`
`saleApprovalCode`	`string`
`ticketNumber`	`string`
`processor_type`	`string`
`acquirer_bank`	`string`
`responseText`	`string`
`fullResponse`	`boolean`
`binCard`	`string`
`recap`	`string`
`requestAmount`	`number`
`token_type`	`number`
`maskedCardNumber`	`number`
`emails`	`array`
`security`	`object`
`security.whitelist`	`boolean`
`processorId`	`string`
`processorMerchantId`	`string`
`issuing_bank`	`string`
`foreign_card`	`boolean`
`processorName`	`string`
`processorBankName`	`string`
`user_agent`	`string`
`amount`	`object`
`amount.subtotalIva0`	`number`
`amount.subtotalIva`	`number`
`amount.iva`	`number`
`amount.ice`	`number`
`amount.currency`	`string`
`card_holder_name`	`string`
`transactionStatus`	`string` “INITIALIZED” “REVIEW” “APPROVAL” “DECLINED” “EXPIRED” `
`paymentBrand`	`string`
`subtotalIva`	`number`
`cardType`	`string`
`plcc`	`string`
`contact_details`	`object`
`contact_details.firstName`	`string`
`contact_details.lastName`	`string`
`contact_details.phoneNumber`	`string`
`contact_details.documentType`	`string`
`contact_details.documentNumber`	`string`
`contact_details.email`	`string`
`publicCredentialId`	`string`
`token`	`string`
`transactionType`	`string`
`orderDetails`	`object`
`shippingDetails`	`object`
`shippingDetails.country`	`string`
`shippingDetails.zipCode`	`string`
`shippingDetails.address`	`string`
`shippingDetails.phone`	`string`
`shippingDetails.city`	`string`
`shippingDetails.name`	`string`
`shippingDetails.region`	`string`
`billingDetails`	`object`
`billingDetails.country`	`string`
`billingDetails.zipCode`	`string`
`billingDetails.address`	`string`
`billingDetails.phone`	`string`
`billingDetails.city`	`string`
`billingDetails.name`	`string`
`billingDetails.region`	`string`
`siteDomain`	`string`
`approvedTransactionAmount`	`number`
`currencyCode`	`string`
`previousStatus`	`object`
`previousStatus.status`	`string` `"PENDING" "INITIALIZED" "REVIEW" "FAILED" "APPROVAL" "DECLINED" "EXPIRED"`
`previousStatus.updatedAt`	`number (Unix Timestamp Format)`
`external_reference_id`	`string`

Example

JSON

// Chargeback Initialized 
{
    "data": {
        "headers": {
            "Accept": "application/json, text/plain, */*",
            "Content-Type": "application/x-www-form-urlencoded",
            "X-Kushki-Id": 1625173711150,
            "X-Kushki-Key": "20000000106902204000",
            "X-Kushki-Signature": "e8caf6bcafff0ec4ff410eb6cda43891c616f90e5081fc6918d71b1098ac081f",
            "X-Kushki-SimpleSignature": "77396f3d87ae660f44513f989a1663cb1d61709d239f71a4600b3593a821fab8"
        },
        "url": "https://accendo.getsandbox.com/users",
        "body": {
            "country": "Ecuador",
            "iceValue": 0,
            "approvalCode": "000000",
            "metadata": {
                "contractID": "157AB"
            },
            "subtotalIva0": 56.5,
            "credentialMetadata": null,
            "productDetails": {
                "product": [
                    {
                        "quantity": 1,
                        "price": 6990000,
                        "id": "198952AB",
                        "title": "eBook Digital Services",
                        "sku": "10101042"
                    },
                    {
                        "quantity": 1,
                        "price": 9990000,
                        "id": "198953AB",
                        "title": "eBook Virtual Selling",
                        "sku": "004834GQ"
                    }
                ]
            },
            "deadLine": 1625519298000,
            "transaction_details": {
                "cardType": "Master Card",
                "binCard": "520081",
                "processorBankName": "0032~BANCO TEST",
                "isDeferred": "N"
            },
            "merchantName": "pruebaEcuador",
            "responseCode": "000",
            "credentialAlias": "pruebaEcuador",
            "merchantId": "20000000106902204000",
            "external_reference_id":"8373737336637383",
            "ivaValue": 0,
            "syncMode": "online",
            "id": "ce6b4ef5-693d-4e3f-97ba-da8a65465498",
            "transaction_reference": "5643f3b1-3c3e-4090-bb71-1ea997f09d79",
            "vault_token": "EQ*********=",
            "created": 1625173695218,
            "ip": "181.199.34.1",
            "transactionId": "1625173695217917",
            "saleTicketNumber": "776576109663279606",
            "lastFourDigits": "4242",
            "credentialId": "1f4c2a757e8b450b9ebf0550ef2d64ff",
            "saleApprovalCode": "000000",
            "ticketNumber": "1625173695217917",
            "processor_type": "gateway",
            "acquirer_bank": "Banco Adquiriente",
            "responseText": "Transacción aprobada",
            "fullResponse": true,
            "binCard": "520081",
            "recap": "612900",
            "requestAmount": 56.5,
            "token_type": "tr*********n",
            "maskedCardNumber": "520081XXXX4242",
            "emails": [
                "test@yourdomain.com"
            ],
            "security": {
                "whitelist": false
            },
            "processorId": "6000000000162379953762969965097",
            "processorMerchantId": "35677777",
            "issuing_bank": "BANCO TEST C.A.",
            "foreign_card": false,
            "processorName": "Credimatic Processor",
            "processorBankName": "0032~BANCO TEST",
            "user_agent": "PostmanRuntime/7.28.0",
            "amount": {
                "subtotalIva0": 56.5,
                "iva": 0,
                "subtotalIva": 0,
                "ice": 0,
                "currency": "USD"
            },
            "cardHolderName": "Your name",
            "transactionStatus": "INITIALIZED",
            "paymentBrand": "Master Card",
            "subtotalIva": 0,
            "cardType": "CREDIT",
            "plcc": false,
            "contact_details": {
                "firstName": "Diego",
                "lastName": "Cadena",
                "phoneNumber": "+593988734644",
                "documentType": "CC",
                "documentNumber": "1009283738",
                "email": "test@yourdomain.com"
            },
            "publicCredentialId": "a83320cb922548098d02793c827a004b",
            "token": "8503e83a182c4c84a9de1786891feacb",
            "transactionType": "CHARGEBACK",
            "orderDetails": {
                "shippingDetails": {
                    "country": "Ecuador",
                    "zipCode": "170402",
                    "address": "Eloy Alfaro 139 y Catalina Aldaz",
                    "phone": "+593988734644",
                    "city": "Quito",
                    "name": "Diego Cadena",
                    "region": "Pichincha"
                },
                "billingDetails": {
                    "country": "Ecuador",
                    "zipCode": "170402",
                    "address": "Eloy Alfaro 139 y Catalina Aldaz",
                    "phone": "+593988734644",
                    "city": "Quito",
                    "name": "Diego Cadena",
                    "region": "Pichincha"
                },
                "siteDomain": "tuebook.com"
            },
            "approvedTransactionAmount": 56.5,
            "currencyCode": "USD",
            "previousStatus": [
                {
                    "status": "INITIALIZED",
                    "updatedAt": 1625173695218
                }
            ]
        },
        "method": "post"
    }
}