Webhooks para tarjeta presente

Recibe notificaciones de los eventos ocurridos en tu comercio a través de webhooks en tu sistema.

Los webhooks permiten suscribirte a eventos que puedan ocurrir, como por ejemplo, una transacción es aprobada o rechazada. Cuando un evento ocurra, te notificaremos a través de un endpoint que hayas configurado previamente, enviando una solicitud POST con un objeto JSON que contendrá toda la información necesaria sobre el evento.

Raw Card-Present API

Política de reintentos de Webhooks

En Kushki nos aseguramos que recibas correctamente una devolución de llamada de Webhook. Por esta razón, el proceso de la política de reintentos de Webhooks se realiza de la siguiente manera:

Primer intento inmediato: este pasa a través de mensajería instantánea (conocida como Notify Now).

El sistema espera un código de estado o status code de 200/201.

Si recibimos un estado diferente, se realizan 3 reintentos en la siguiente hora y después se hacen 4 reintentos en las siguientes 2 horas.

Lo anterior, teniendo en cuenta que nuestra lógica de reintentos de envío de notificaciones funciona con un máximo de 7 reintentos en un transcurso de 3 horas una vez falla el Notify Now.

Una vez finalizados los 7 reintentos, si no recibes una respuesta exitosa, el Webhook se marca como fallido y dejamos de reintentar.

Si al finalizar este ciclo de envíos no hemos recibido un estado exitoso y deseas recibir el webhook, por favor comunícate con nuestro Equipo de soporte.

¿Cómo funcionan los reintentos a través del tiempo transcurrido?

Si falla el Notify Now, debes esperar 20 minutos a que se envíe el primer reintento y de la misma manera el mismo periodo de tiempo hasta completar la hora, tal y como se muestra a continuación:

Primer reintento: se envía al minuto 20.

Segundo reintento: se envía al minuto 40.

Tercer reintento: se envía al minuto 60 (1 hora).

Transcurridos los 60 minutos (1 hora) y si el tercer reintento falla, debes esperar 30 minutos a que se envíe el cuarto reintento hasta completar las 2 horas siguientes de la siguiente forma:

Cuarto reintento: se envía al minuto 30.

Quinto reintento: se envía al minuto 60.

Sexto reintento: se envía al minuto 90.

Séptimo reintento: se envía al minuto 120.

Nota

Ten en cuenta que estos tiempos son aproximados y podrían estar sujetos a variaciones.

Seguridad de los webhooks

Los webhooks de la Raw Card-Present API incluyen estas cabeceras para que verifiques que provienen de Kushki:

Cabecera	Descripción
`X-Kushki-Key`	ID de tu comercio.
`X-Kushki-Id`	Fecha de la petición en formato timestamp Unix.
`X-Kushki-Signature`	Hex digest de la firma HMAC SHA256 del body de la petición, un punto (`.`) y el valor de `X-Kushki-Id`, usando tu Webhook signature como clave.
`X-Kushki-SimpleSignature`	Hex digest de la firma HMAC SHA256 solo del valor de `X-Kushki-Id`, usando tu Webhook signature como clave.

Puedes verificar cualquiera de las dos firmas. X-Kushki-Signature incluye el body, por lo que además comprueba que el contenido no se alteró en el camino. X-Kushki-SimpleSignature solo usa el timestamp: confirma el origen, pero no valida el body.

Dónde obtener tu Webhook signature: en la Kushki Console, en Desarrolladores > Webhooks. Aparece en la parte superior de la página, aunque todavía no hayas creado ningún webhook.

IPs de origen: Kushki envía los webhooks desde estas IPs estáticas; puedes usarlas como capa adicional de validación.

Entorno	IP
UAT	`54.208.105.247`
Producción	`34.230.185.20`

Para ver los pasos de verificación y los ejemplos de código, consulta Webhooks — Introducción.

Descubre la lista de los eventos disponibles a través de la integración Raw Card-Present API

Transacciones aprobadas

Transacciones rechazadas

Autorizaciones

Captura de fondos

Anulaciones

Reversos

Consulta de saldo

A continuación, la lista de propiedades disponibles en el webhook. Ten en cuenta que algunas de las propiedades podrían no estar disponibles al momento de la notificación de acuerdo a la configuración de la operación y al método de pago.

Propiedad	Tipo	Descripción
country	String	País del comercio.
franchise	String	`VISA`, `MASTERCARD`.
available	boolean
channel	String	Canal por donde se realizó la venta.
public_credential_id	String	Llave pública del comercio.
client_transaction_id	String	Id generado por el comercio.
mcc	String	Código de categoría de comerciante (Merchant category code).
card_country	String	País de la tarjeta procesada.
processor_name	String	Nombre del procesador.
transaction_reference	String	Referencia única por transacción generada por Kushki.
payment_method	String	Método de pago.
card_details	Object	Objeto con información adicional de la tarjeta procesada.
card_details.reading_type	String	Tipo de lectura de la tarjeta procesada.
card_details.card_sequential	String
card_details.tlv	String
transaction_id	String	Id único por transacción generado por Kushki.
created	Integer	Fecha de creación de la transacción.
merchant_name	String	Nombre del comercio.
transaction_type	String	Tipo de operación.
processor	Object	Objeto con información adicional del procesador.
processor.code	String	Código de respuesta del procesador.
processor.message	String	Mensaje de respuesta del procesador.
reference_number	String	Número de referencia de la transacción.
tax_id	String
sync_mode	String
additional_info	Object
additional_info.f7	String
additional_info.f63	String
additional_info.f11	String
additional_info.f37	String
additional_info.f32	String
additional_info.f62s2	String
subtotal_iva0	Number	Monto sin impuestos de la transacción.
deferred	Object
deferred.months	String	Número de cuotas (si la transacción se difirió).
response_code	String	Código de respuesta.
transaction_status	String	Estado de la transacción.
social_reason	String	Razón social del comercio.
payment_brand	String	`VISA`, `MASTERCARD`
acquirer_bank	String
request_amount	String	Monto solicitado.
merchant_id	String	Id del comercio.
merchant_category	String	Categoría del comercio.
acq_transaction_type	String
security	Object
security.ip	String
security.user_agent	String
masked_credit_card	String	Número de tarjeta enmascarado.
authorization_code	String	Código de autorización.
issuing_bank	String	Banco emisor de la tarjeta.
processor_id	String	Id del procesador.
foreign_card	Boolean
pos_details	Object
pos_details.model	String	Modelo del terminal.
pos_details.location	Object
pos_details.location.latitude	Number
pos_details.location.longitude	Number
pos_details.version	String	Versión del terminal.
pos_details.brand	String	Marca del terminal.
pos_details.terminal_id	String	ID del terminal.
pos_details.user	String	Usuario operador del dispositivo. Solo se devuelve si se envía en el request.
pos_details.friendly_name	String	Nombre amigable del terminal. Solo se devuelve si se envía en el request.
pos_details.serial	String	Número de serie del dispositivo. Solo se devuelve si se envía en el request.
pos_details.type	String	Tipo físico del dispositivo. Valores posibles: `COUNTERTOP`, `MPOS`, `SMARTPOS`, `SELF_SERVICE`, `OTHER`. Solo se devuelve si se envía en el request.
pos_details.connectivity	String	Tipo de conectividad de red. Valores posibles: `GPRS`, `WIFI`, `ETHERNET`, `DIAL_UP`, `OTHER`. Solo se devuelve si se envía en el request.
last_four_digits	String	Últimos 4 dígitos de la tarjeta.
approval_code	String	Código de aprobación.
amount	Object
amount.extra_taxes	Object
amount.currency	String	Moneda de la transacción.
amount.subtotal_iva0	Number	Monto sin impuestos de la transacción.
rules_response	Object
rules_response.country	String
rules_response.commercial_executive	String
rules_response.business_category	String
rules_response.address	String
rules_response.city	String
rules_response.authorizer	Object
rules_response.authorizer.authorizer_name	String
rules_response.authorizer.soft_descriptor	String
rules_response.authorizer.authorizer_bank_id	String
rules_response.authorizer.commerce_code	String
rules_response.authorizer.authorizer_type	String
rules_response.authorizer.retailer_id	String
rules_response.authorizer.authorizer_acquirer_bin	String
rules_response.authorizer.category_model	String
rules_response.authorizer.url	String
rules_response.authorizer.authorizer_alias	String
rules_response.authorizer.terminal_id	String
rules_response.contact_person	String
rules_response.merchant_name	String
rules_response.telephone	String
rules_response.mcc	String
rules_response.url	String
rules_response.zip_code	String
rules_response.tax_id	String
rules_response.province	String
rules_response.business_registration_id	String
rules_response.tcc	String
rules_response.total	String
rules_response.business_line	String
rules_response.currency	String
rules_response.id	String
rules_response.acquirer_type	String
acq_transaction_scope	String
contact_details	Object
contact_details.document_number	String
contact_details.document_type	String
acq_transaction_mode	String
card_type	String	`credit`, `debit`, `prepaid`
ticket_number	String	Número de ticket.
card_country_code	String	Código de país de la tarjetas procesada.
credential_alias	String
bin_card	String	Bin de la tarjeta procesada.
credential_id	String
cvm_type	String
approved_transaction_amount	Number	Monto autorizado.
transaction_reference	String	Referencia única por transacción generada por Kushki.

Ejemplos de webhooks para una transacción aprobada.

JSON

{
    "country": "Chile",
    "franchise": "MASTERCARD",
    "available": true,
    "channel": "POS",
    "public_credential_id": "146cbf33c7fd45c4111cbf9d3f04478d",
    "client_transaction_id": "ae6dd41a-9173-4ec7-8734-3178454ef341",
    "mcc": "1234",
    "card_country": "CHL",
    "processor_name": "MASTERCARD",
    "transaction_reference": "718fa526-6f41-405f-a1f5-a71db52dfdd2",
    "payment_method": "card",
    "card_details": {
        "reading_type": "MCR"
    },
    "transaction_id": "111663595155516279",
    "created": 1663895155240,
    "merchant_name": "Tu libreria",
    "transaction_type": "SALE",
    "processor": {
        "code": "000",
        "message": "Transacción Aprobada."
    },
    "reference_number": "226520101801",
    "tax_id": "7283839521223",
    "sync_mode": "online",
    "additional_info": {
        "f7": "0922200555",
        "f63": "MDS8TNCN9",
        "f11": "101883",
        "f37": "226520101883"
    },
    "subtotal_iva0": 101.99,
    "deferred": {
        "months": "1"
    },
    "response_code": "00",
    "transaction_status": "APPROVAL",
    "social_reason": "TU LIBRERIA",
    "payment_brand": "MASTERCARD",
    "acquirer_bank": "Kushki",
    "request_amount": 101.99,
    "merchant_id": "20000000305053342000",
    "approved_transaction_amount": 101.99,
    "merchant_category": "Medium",
    "acq_transaction_type": "charge",
    "security": {
        "ip": "187.212.254.148",
        "user_agent": "PostmanRuntime/7.29.2"
    },
    "masked_credit_card": "545195XXXXXX5480",
    "authorization_code": "533804",
    "issuing_bank": "BankACQ",
    "processor_id": "1652365464",
    "foreign_card": true,
    "pos_details": {
        "model": "P2-EU",
        "location": {
            "latitude": -0.1848534,
            "longitude": -78.4769761
        },
        "brand": "SUNMI",
        "version": "Kushki SunmiV1.1.13",
        "terminal_id": "PB04209860004"
    },
    "last_four_digits": "5480",
    "approval_code": "533804",
    "amount": {
        "extra_taxes": {},
        "currency": "CLP",
        "subtotal_iva0": 101.99
    },
    "rules_response": {
        "country": "CHL",
        "address": "Centro 123",
        "business_category": "0",
        "commercial_executive": "user@example.com",
        "authorizer": {
            "authorizer_name": "MASTERCARD",
            "soft_descriptor": "KSK*TEST",
            "authorizer_bank_id": "",
            "authorizer_type": "",
            "commerce_code": "353453",
            "retailer_id": "",
            "authorizer_acquirer_bin": "545195",
            "category_model": "0",
            "terminal_id": "1652365413",
            "authorizer_alias": "MASTERCARD",
            "url": ""
        },
        "city": "Monterrey",
        "contact_person": "John Doe",
        "merchant_name": "Tu libreria",
        "telephone": "8100000001",
        "mcc": "1234",
        "tax_id": "asdf12345678",
        "url": "",
        "zip_code": "64000",
        "province": "NUEVO LEON",
        "tcc": "H",
        "total_amount": "101.990000",
        "business_registration_id": "000000000001",
        "business_line": "37006",
        "currency": "CLP",
        "id": "1652365464",
        "acquirer_type": "kushki"
    },
    "acq_transaction_scope": "international",
    "contact_details": {
        "document_number": "123666",
        "document_type": "0"
    },
    "acq_transaction_mode": "Authorization",
    "card_type": "credit",
    "ticket_number": "111663890155240264",
    "card_country_code": "CHL",
    "credential_alias": "Tu libreria",
    "bin_card": "545195",
    "credential_id": "245c10532cd844e28e4ec9a83159d89b",
    "transactionReference": "718fa526-6f41-405f-a1f5-a71db52dfdd2"
}

Ejemplos de webhooks para un reembolso.

También puedes consultar el estado de las devoluciones desde tu Consola.

JSON

{
    "country": "Chile",
    "franchise": "VISA",
    "available": true,
    "channel": "POS",
    "public_credential_id": "146cbf33c7fd45c0271cbf9d31d4478d",
    "client_transaction_id": "6681eadc-6d8d-44ba-8ca0-18e061c1172a",
    "mcc": "1234",
    "card_country": "CHL",
    "processor_name": "VISA",
    "transaction_reference": "daa8583d-f18c-419a-840e-be5c95011eb6",
    "payment_method": "card",
    "card_details": {
        "card_sequential": "11",
        "reading_type": "ICC",
        "tlv": "9F2701809F1A0206049A032208309F02060000000120005F2A0206044F07A00000000310109F0607A00000000310109F26085DE291D252397F709F100706010A03A020009F37044A05C99750095649534120544553549F6E009F5B009F3602008C9F330360F8C89F03009C010082021C008407A00000000310105F34011195058080048000"
    },
    "transaction_id": "111663896831621702",
    "created": 1663896831738,
    "merchant_name": "Tu libreria",
    "transaction_type": "REFUND",
    "processor": {
        "code": "000",
        "message": "Transacción Aprobada."
    },
    "reference_number": "226520105211",
    "tax_id": "7283839421223",
    "sync_mode": "online",
    "additional_info": {
        "f7": "0922203351",
        "f32": "408210",
        "f11": "100611",
        "f62s2": "40000000000000000302145412649612",
        "f37": "226520100611"
    },
    "subtotal_iva0": 60,
    "deferred": {
        "months": "1"
    },
    "response_code": "00",
    "transaction_status": "APPROVAL",
    "social_reason": "TU LIBRERIA",
    "payment_brand": "VISA",
    "acquirer_bank": "Kushki",
    "request_amount": 60,
    "merchant_id": "20000000105850418000",
    "approved_transaction_amount": 0.6,
    "merchant_category": "Medium",
    "acq_transaction_type": "Refund",
    "security": {},
    "masked_credit_card": "476134XXXXXX0043",
    "authorization_code": "120606",
    "issuing_bank": "VISA",
    "processor_id": "1652365464",
    "cvm_type": "none",
    "foreign_card": true,
    "pos_details": {
        "location": {
            "latitude": -0.22480833333333333,
            "longitude": -78.487955
        },
        "model": "P2-EU",
        "version": "Kushki SunmiV1.1.26",
        "brand": "SUNMI",
        "terminal_id": "PB04216R24337"
    },
    "last_four_digits": "0043",
    "approval_code": "120606",
    "amount": {
        "extra_taxes": {},
        "currency": "CLP",
        "subtotal_iva0": 60
    },
    "rules_response": {
        "country": "CHL",
        "commercial_executive": "user@example.com",
        "business_category": "0",
        "address": "Centro 123",
        "contact_person": "Jhon Doe",
        "authorizer": {
            "authorizer_name": "VISA",
            "soft_descriptor": "KSK*TEST",
            "authorizer_bank_id": "",
            "authorizer_type": "",
            "commerce_code": "353453",
            "authorizer_acquirer_bin": "408210",
            "retailer_id": "",
            "category_model": "0",
            "terminal_id": "1652365464",
            "authorizer_alias": "VISA",
            "url": ""
        },
        "city": "Monterrey",
        "merchant_name": "Tu libreria",
        "telephone": "8100000001",
        "mcc": "1234",
        "url": "",
        "zip_code": "64000",
        "tax_id": "asdf12345678",
        "province": "NUEVO LEON",
        "total_amount": "60.000000",
        "business_registration_id": "000000000001",
        "tcc": "H",
        "business_line": "37006",
        "currency": "CLP",
        "id": "1652365464",
        "acquirer_type": "kushki"
    },
    "acq_transaction_scope": "international",
    "contact_details": {
        "document_type": "-1"
    },
    "acq_transaction_mode": "Authorization",
    "card_type": "credit",
    "ticket_number": "111663896831738702",
    "card_country_code": "CHL",
    "credential_alias": "Tu libreria",
    "bin_card": "476134",
    "credential_id": "245c10502cd844ebae4ec9a70610d89b",
    "transactionReference": "daa8583d-f18c-419a-840e-be5c95011eb6"
}

Webhooks para tarjeta presente

Raw Card-Present API#

Política de reintentos de Webhooks#

¿Cómo funcionan los reintentos a través del tiempo transcurrido?#

Seguridad de los webhooks#

Raw Card-Present API

Política de reintentos de Webhooks

¿Cómo funcionan los reintentos a través del tiempo transcurrido?

Seguridad de los webhooks