Webhooks — Pagos con tarjeta - Kushki Developer Portal

Kushki envía una notificación de webhook a tu endpoint cuando ocurre cualquiera de estos eventos presenciales:

Se aprueba o se rechaza una transacción con tarjeta de crédito o débito

Se crea una autorización (pre-auth)

Se procesa una captura

Se procesa una anulación

Se procesa un reverso

Se realiza una consulta de saldo

Estructura de la solicitud

Las notificaciones de webhook usan POST con las cabeceras de autenticación.

Método: POST
Cuerpo: objeto JSON

Campo	Tipo	Descripción
`country`	string	País de la transacción: `"Mexico"`
`franchise`	string	Red de la tarjeta: `VISA`, `MASTERCARD`, `PROSA`
`metadata`	object	Metadata personalizada asociada a la transacción
`metadata.key0`	string	Campo de metadata personalizada
`metadata.key1`	string	Campo de metadata personalizada
`metadata.key2`	string	Campo de metadata personalizada
`available`	boolean	Indica si la transacción está disponible
`channel`	string	Canal de la transacción: `"POS"`
`public_credential_id`	string	Credencial pública utilizada
`client_transaction_id`	string	UUID que envía el comercio
`mcc`	string	Código de categoría del comercio
`card_country`	string	Código ISO del país emisor de la tarjeta
`processor_name`	string	Nombre del procesador de la tarjeta
`transaction_reference`	string	Referencia de la transacción en Kushki
`payment_method`	string	`"card"`
`card_details`	object	Detalles de la lectura de la tarjeta
`card_details.prosa_info`	object	Información de la tarjeta específica de PROSA (México)
`card_details.reading_type`	string	`ICC`, `MCR` o `NFC`
`card_details.card_sequential`	string	Número de secuencia de la tarjeta
`card_details.tlv`	string	Datos TLV crudos del chip
`transaction_id`	string	ID interno de la transacción en Kushki
`created`	integer	Timestamp de creación de la transacción (Unix ms)
`merchant_name`	string	Nombre visible del comercio
`transaction_type`	string	`SALE`, `PREAUTH`, `CAPTURE`, `VOID`, `REFUND`
`processor`	object	Respuesta 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 del adquirente
`tax_id`	string	Identificador fiscal del comercio
`sync_mode`	string	`"online"`
`additional_info`	object	Campos adicionales de ISO 8583
`additional_info.f7`	string	Campo ISO 7
`additional_info.f63`	string	Campo ISO 63
`additional_info.f11`	string	Campo ISO 11
`additional_info.f37`	string	Campo ISO 37
`additional_info.f32`	string	Campo ISO 32
`additional_info.f62s2`	string	Campo ISO 62, subcampo 2
`subtotal_iva0`	number	Subtotal de la transacción (exento de IVA)
`deferred`	object	Detalles del diferido MSI
`deferred.months`	string	Número de meses de MSI
`response_code`	string	Código de respuesta ISO
`transaction_status`	string	`APPROVAL` o `DECLINED`
`social_reason`	string	Razón social del comercio
`payment_brand`	string	Red de la tarjeta: `VISA`, `MASTERCARD`
`acquirer_bank`	string	Nombre del banco adquirente
`request_amount`	number	Monto solicitado de la transacción
`merchant_id`	string	ID del comercio en Kushki
`merchant_category`	string	Categoría del comercio
`acq_transaction_type`	string	Tipo de transacción del adquirente
`security`	object	Metadata de seguridad
`security.ip`	string	Dirección IP del cliente
`security.user_agent`	string	User agent del cliente
`masked_credit_card`	string	Número de tarjeta enmascarado (por ejemplo, `545195XXXXXX5480`)
`authorization_code`	string	Código de autorización del banco
`issuing_bank`	string	Nombre del banco emisor de la tarjeta
`processor_id`	string	Identificador del procesador
`foreign_card`	boolean	`true` si la tarjeta se emitió fuera de México
`pos_details`	object	Detalles de la terminal POS
`pos_details.brand`	string	Marca de la terminal (por ejemplo, `"SUNMI"`)
`pos_details.model`	string	Modelo de la terminal (por ejemplo, `"P2-EU"`)
`pos_details.version`	string	Versión del software de la terminal
`pos_details.terminal_id`	string	Identificador de la terminal
`pos_details.location`	object	Coordenadas GPS de la terminal
`pos_details.location.latitude`	number	Latitud
`pos_details.location.longitude`	number	Longitud
`last_four_digits`	string	Últimos 4 dígitos de la tarjeta
`approval_code`	string	Código de aprobación del banco
`amount`	object	Desglose completo del monto
`amount.currency`	string	`"MXN"`
`amount.subtotal_iva0`	number	Subtotal exento de IVA
`amount.extra_taxes`	object	Impuestos adicionales
`rules_response`	object	Configuración del comercio en el motor de reglas de Kushki
`rules_response.country`	string	`"MEX"`
`rules_response.city`	string	Ciudad del comercio
`rules_response.province`	string	Estado del comercio
`rules_response.address`	string	Dirección del comercio
`rules_response.zip_code`	string	Código postal del comercio
`rules_response.currency`	string	`"MXN"`
`rules_response.merchant_name`	string	Nombre del comercio
`rules_response.mcc`	string	MCC
`rules_response.authorizer`	object	Configuración del adquirente o procesador
`acq_transaction_scope`	string	`"local"` o `"international"`
`contact_details`	object	Datos de contacto del cliente
`contact_details.document_type`	string	Código del tipo de documento
`contact_details.document_number`	string	Número de documento
`acq_transaction_mode`	string	`"Authorization"`
`card_type`	string	`credit`, `debit` o `prepaid`
`ticket_number`	string	Número de ticket de Kushki
`card_country_code`	string	`"MEX"`
`credential_alias`	string	Nombre visible de la credencial
`bin_card`	string	Primeros 6 dígitos de la tarjeta
`credential_id`	string	Identificador de la credencial
`cvm_type`	string	Método de verificación del tarjetahabiente
`approved_transaction_amount`	number	Monto aprobado
`transactionReference`	string	Duplicado de `transaction_reference`

Ejemplos

Cargo

Autorización (preAuth)

Captura

{
  "country": "Mexico",
  "franchise": "MASTERCARD",
  "metadata": {
    "transaccionCodigo": "1245",
    "type": "test",
    "transaccionId": "1234"
  },
  "available": true,
  "channel": "POS",
  "public_credential_id": "146cbf33c7fd45c4111cbf9d3f04478d",
  "client_transaction_id": "ae6dd41a-9173-4ec7-8734-3178454ef341",
  "mcc": "1234",
  "card_country": "MEX",
  "processor_name": "MASTERCARD",
  "transaction_reference": "718fa526-6f41-405f-a1f5-a71db52dfdd2",
  "payment_method": "card",
  "card_details": {
    "prosa_info": {},
    "reading_type": "MCR"
  },
  "transaction_id": "111663595155516279",
  "created": 1663895155240,
  "merchant_name": "Mi Comercio México",
  "transaction_type": "SALE",
  "processor": {
    "code": "000",
    "message": "Transacción Aprobada."
  },
  "reference_number": "226520101801",
  "tax_id": "MCC800101HNG",
  "sync_mode": "online",
  "additional_info": {
    "f7": "0922200555",
    "f63": "MDS8TNCN9",
    "f11": "101883",
    "f37": "226520101883"
  },
  "subtotal_iva0": 500,
  "deferred": {
    "months": "1"
  },
  "response_code": "00",
  "transaction_status": "APPROVAL",
  "social_reason": "MI COMERCIO MÉXICO",
  "payment_brand": "MASTERCARD",
  "acquirer_bank": "Kushki",
  "request_amount": 500,
  "merchant_id": "20000000103802320000",
  "approved_transaction_amount": 500,
  "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": "BANORTE",
  "processor_id": "1652365464",
  "foreign_card": false,
  "pos_details": {
    "model": "P2-EU",
    "location": {
      "latitude": 19.4326,
      "longitude": -99.1332
    },
    "brand": "SUNMI",
    "version": "Kushki SunmiV1.1.28",
    "terminal_id": "PB04209860189"
  },
  "last_four_digits": "5480",
  "approval_code": "533804",
  "amount": {
    "extra_taxes": {},
    "currency": "MXN",
    "subtotal_iva0": 500
  },
  "rules_response": {
    "country": "MEX",
    "address": "Av. Insurgentes Sur 1234",
    "business_category": "0",
    "commercial_executive": "user@example.com",
    "authorizer": {
      "authorizer_name": "MASTERCARD",
      "soft_descriptor": "KSK*MI COMERCIO",
      "authorizer_bank_id": "",
      "authorizer_type": "",
      "commerce_code": "353453",
      "retailer_id": "",
      "authorizer_acquirer_bin": "545195",
      "category_model": "0",
      "terminal_id": "1652365464",
      "authorizer_alias": "MASTERCARD"
    },
    "city": "Ciudad de México",
    "province": "CDMX",
    "contact_person": "Juan García",
    "merchant_name": "Mi Comercio México",
    "telephone": "+525512345678",
    "mcc": "5411",
    "tax_id": "MCC800101HNG",
    "zip_code": "06600",
    "total_amount": "500.000000",
    "business_line": "37006",
    "currency": "MXN",
    "id": "1652365464",
    "acquirer_type": "kushki"
  },
  "acq_transaction_scope": "local",
  "contact_details": {
    "document_number": "GACJ800101HDFRRN09",
    "document_type": "CURP"
  },
  "acq_transaction_mode": "Authorization",
  "card_type": "credit",
  "ticket_number": "319228478889680318",
  "card_country_code": "MEX",
  "credential_alias": "Mi Comercio México",
  "bin_card": "545195",
  "credential_id": "245c10532cd844e28e4ec9a83159d89b",
  "transactionReference": "718fa526-6f41-405f-a1f5-a71db52dfdd2"
}

¿Tienes una sugerencia sobre esta documentación? Contáctanos.

Webhooks — Pagos con tarjeta

Estructura de la solicitud#

Ejemplos#

Estructura de la solicitud

Ejemplos