1. Webhooks para devoluciones
Kushki Docs
Español
  • Español
  • English
  • Inicio
  • Inicio rápido
    • Últimas novedades
    • Preguntas frecuentes
    • Paso a producción
    • Política de cambios importantes del API
    • Datos de prueba
    • Códigos de error
  • Glosario de pagos
    • Glosario de pagos
  • Pagos únicos con tarjeta (Online)
    • Network Tokens
    • Marcas de tarjeta soportadas
    • Funcionalidades por modelo de negocio
    • Guía de integración Comisiones a terceros
    • ¿Cómo funcionan las Comisiones a terceros?
    • Pagos en un paso
      • Acepta un pago con tarjeta
      • Cargo directo (sin token)
      • ¿Cómo funcionan los pagos con tarjeta?
      • Acepta pagos únicos con OTP
      • Códigos de error autenticación OTP
      • Códigos de error pagos únicos con tarjeta
    • Pagos en dos pasos
      • Recibe pagos con autorización y captura
      • ¿Cómo funcionan los pagos únicos con autorización y captura?
    • Devoluciones
      • Devoluciones, anulaciones y reembolsos
    • Autenticación 3DS
      • Integración 3DS API + librería kushki.js
      • Introducción a 3DS
      • Integración 100% API de 3DS
      • Integración 3DS con librería kushki.js
      • Códigos de error autenticación 3DS
    • Pagos con Apple Pay
      • Configuración de Apple Pay
      • Pruebas en Sandbox Apple Pay
  • Pagos recurrentes con tarjeta (Online)
    • Autentica tus suscripciones con 3DS
    • Apple Pay en Suscripciones
    • Suscripciones externas a Kushki
    • Acepta pagos one click con 3DS
    • Funcionalidades por modelo de negocio
    • Códigos de error en cargos recurrentes
    • Pagos calendarizados
      • ¿Cómo funcionan los cargos recurrentes con tarjeta?
      • Maneja tus cargos calendarizados
      • Crea un cargo recurrente
    • Pagos OneClick
      • Genera pagos one click
      • Recibe pagos OneClick con autorización y captura
      • ¿Cómo funcionan los pagos OneClick con autorización y captura?
  • Pagos con tarjeta presente
    • Acepta pagos con tarjeta presente
    • Datos de prueba
    • Webhooks para tarjeta presente
    • Cloud Terminal API
      • Acepta pagos
      • Anula una solicitud de pago
      • Consulta el estado de una petición de cobro
      • ¿Cómo imprimir un ticket personalizado?
    • App-to-app
      • Acepta pagos
    • Transacciones
      • Anula un pago
      • Transacciones
    • Terminal SDK
      • Acepta pagos
    • Kushki One
      • Autenticación y Cifrado de Requests
      • Realiza cobros con Kushki One
      • Formato de montos en Kushki ONE
      • Impresión en terminal SmartPOS
      • Catálogo Unificado de Errores — Kushki ONE Connect
      • Servicios asíncronos y webhooks
    • Raw card-present API
      • Acepta pagos
      • Script de ejemplo para cifrar información
      • Intercambio de claves criptográficas
      • Preguntas frecuentes
      • Códigos de error para transacciones con tarjeta presente
    • Kushki One App de Pagos
      • Devoluciones y PreAuth & Capture
      • Procesa un cobro
      • Pago Dividido en la terminal
      • Consulta tus transacciones
      • Configuración del terminal
  • Pagos con transferencias
    • Bancos y detalles de operación para pagos con transferencia bancaria
    • Recibe transferencias bancarias
    • Consulta el estado de una transacción
  • Dispersión de dinero
    • Transferencia bancaria
      • Dispersa a cuentas bancarias
      • Códigos de error para dispersiones por transferencia
  • Plugins
    • Shopify
      • Operación del Plugin
    • Vtex
      • Guía de integración VTEX
  • Links de pago
    • Smartlinks
  • Formularios y botones de pago
    • Kajita
      • Kajitas de pago
      • ¿Cómo funciona?
    • Botón de pago
      • ¿Cómo funciona el botón de pago?
      • Genera un botón de pago
  • Administración de sucursales
    • ¿Cómo realizar el onboarding de subcomercios vía API?
  • Notificaciones
    • Buenas prácticas
    • Consulta tus webhooks
    • Webhooks para pagos únicos
      • Webhook para pagos únicos con tarjeta
      • Webhook para pagos únicos con transferencia bancaria
      • Webhook para pagos únicos con efectivo
    • Webhooks para dispersiones
      • Webhook para dispersión de dinero con transferencia
    • Webhooks para botón de pagos
      • Webhooks con Botón de pago
    • Webhooks para smartlinks
      • Webhooks con Smartlinks
    • Webhooks para pagos recurrentes
      • Webhook para pagos recurrentes con tarjeta
    • Webhooks para devoluciones
      • Webhook para devoluciones
      • Webhook para contracargos
HomeMexico 🇲🇽
Ecuador 🇪🇨Chile 🇨🇱Colombia 🇨🇴Peru 🇵🇪
HomeMexico 🇲🇽
Ecuador 🇪🇨Chile 🇨🇱Colombia 🇨🇴Peru 🇵🇪
Status
Soporte / Support
Español
  • Español
  • English
  1. Webhooks para devoluciones

Webhook para contracargos

Contracargos
Kushki puede enviar eventos vía webhook que notifican a tu aplicación cuando ocurra alguno de los siguientes cambios en el estado de un contracargo:
Contracargo inicializado (INITIALIZED): Kushki recibe la notificación del contracargo y debes cargar la documentación de soporte. El evento incluirá un deadLine (en formato Unix) con la fecha límite para hacerlo.
Contracargo en revisión (REVIEW): has enviado correctamente los documentos de soporte y el contracargo está siendo analizado. Kushki tiene un plazo máximo de 60 días para notificarte la resolución.
Contracargo aprobado (APPROVAL): el contracargo fue resuelto a tu favor. No perderás el valor de la venta.
Contracargo declinado (DECLINED): el contracargo fue resuelto en tu contra. Perderás el valor de la venta.
Contracargo expirado (EXPIRED): no cargaste la documentación de soporte dentro del plazo de 15 días. Perderás el valor de la venta.
También puedes consultar el estado de las devoluciones desde tu consola

Notificación de actualización de estado de contracargo#

Estructura#

Los webhooks de contracargos enviados por Kushki contendrán los encabezados (headers) aquí listados.

Estas son las posibles variables que se entregan en el cuerpo del webhook cuando un contracargo cambia de estado:
Método: POST
Body: Object
VariableTipo
countrystring
iceValuenumber
approvalCodestring
metadataobject
metadata.key0string
subtotalIva0string
credentialMetadatastring
productDetailsobject
productobject
product.quantityinteger
product.pricenumber
product.idstring
product.tittlestring
product.skustring
deadLinenumber (Unix Timestamp Format)
transaction_detailsobject
transaction_details.cardTypestring
transaction_details.binCardstring
transaction_details.processorBankNamestring
transaction_details.isDeferredstring
merchantNamestring
responseCodestring
credentialAliasstring
merchantIdstring
ivaValuenumber
syncModestring
idstring
transaction_referencestring
transactionReferencestring
vault_tokenstring
creatednumber (Unix Timestamp Format)
ipstring
transactionIdstring
saleTicketNumberstring
lastFourDigitsstring
credentialIdstring
saleApprovalCodestring
ticketNumberstring
processor_typestring
acquirer_bankstring
responseTextstring
fullResponseboolean
binCardstring
recapstring
requestAmountnumber
token_typenumber
maskedCardNumbernumber
emailsarray
securityobject
security.whitelistboolean
processorIdstring
processorMerchantIdstring
issuing_bankstring
foreign_cardboolean
processorNamestring
processorBankNamestring
user_agentstring
amountobject
amount.subtotalIva0number
amount.subtotalIvanumber
amount.ivanumber
amount.icenumber
amount.currencystring
card_holder_namestring
transactionStatusstring "INITIALIZED" "REVIEW" "APPROVAL" "DECLINED" "EXPIRED" `
paymentBrandstring
subtotalIvanumber
cardTypestring
plccstring
contact_detailsobject
contact_details.firstNamestring
contact_details.lastNamestring
contact_details.phoneNumberstring
contact_details.documentTypestring
contact_details.documentNumberstring
contact_details.emailstring
publicCredentialIdstring
tokenstring
transactionTypestring
orderDetailsobject
shippingDetailsobject
shippingDetails.countrystring
shippingDetails.zipCodestring
shippingDetails.addressstring
shippingDetails.phonestring
shippingDetails.citystring
shippingDetails.namestring
shippingDetails.regionstring
billingDetailsobject
billingDetails.countrystring
billingDetails.zipCodestring
billingDetails.addressstring
billingDetails.phonestring
billingDetails.citystring
billingDetails.namestring
billingDetails.regionstring
siteDomainstring
approvedTransactionAmountnumber
currencyCodestring
previousStatusobject
previousStatus.statusstring "PENDING" "INITIALIZED" "REVIEW" "FAILED" "APPROVAL" "DECLINED" "EXPIRED"
previousStatus.updatedAtnumber (Unix Timestamp Format)
external_reference_idstring

Ejemplo#

JSON
// Contracargo inicializado
{
    "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",
            "ivaValue": 0,
            "syncMode": "online",
            "id": "ce6b4ef5-693d-4e3f-97ba-da8a65465498",
            "transaction_reference": "5643f3b1-3c3e-4090-bb71-1ea997f09d79",
            "transactionReference": "ce6b4ef5-693d-4e3f-97ba-da8a65465498",
            "vault_token": "EQ*********=",
            "created": 1625173695218,
            "ip": "181.199.34.1",
            "transactionId": "1625173695217917",
            "external_reference_id": "8373737336637383",
            "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"
    }
}
Modificado en 2026-09-21 19:55:36
Anterior
Webhook para devoluciones
Built with