Webhooks — Reembolsos - Kushki Developer Portal

Kushki envía una notificación de webhook a tu endpoint cuando ocurre el siguiente evento de reembolso:

Se aprueba un reembolso

INFO

También puedes revisar el estado de los reembolsos desde tu Console.

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`
`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	`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	`"Refund"`
`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, `476134XXXXXX0043`)
`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.tax_id`	string	Identificador fiscal del comercio
`rules_response.tcc`	string	Código de capacidad de la terminal
`rules_response.business_registration_id`	string	ID de registro del negocio
`rules_response.business_line`	string	Código de la línea de negocio
`rules_response.business_category`	string	Categoría del negocio
`rules_response.commercial_executive`	string	Ejecutivo comercial asignado
`rules_response.contact_person`	string	Nombre de la persona de contacto
`rules_response.telephone`	string	Teléfono del comercio
`rules_response.total_amount`	string	Monto total de la transacción
`rules_response.id`	string	ID de la configuración del comercio
`rules_response.acquirer_type`	string	`"kushki"`
`rules_response.authorizer`	object	Configuración del adquirente o procesador
`rules_response.authorizer.authorizer_name`	string	Nombre del procesador
`rules_response.authorizer.soft_descriptor`	string	Soft descriptor en el estado de cuenta del tarjetahabiente
`rules_response.authorizer.authorizer_bank_id`	string	ID del banco del autorizador
`rules_response.authorizer.authorizer_type`	string	Tipo de autorizador
`rules_response.authorizer.commerce_code`	string	Código de comercio
`rules_response.authorizer.retailer_id`	string	ID del minorista
`rules_response.authorizer.authorizer_acquirer_bin`	string	BIN del adquirente
`rules_response.authorizer.category_model`	string	Modelo de categoría
`rules_response.authorizer.terminal_id`	string	ID de la terminal en el autorizador
`rules_response.authorizer.authorizer_alias`	string	Alias del autorizador
`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`

Ejemplo

{
  "country": "Mexico",
  "franchise": "VISA",
  "available": true,
  "channel": "POS",
  "public_credential_id": "146cbf33c7fd45c4111cbf9d3f04478d",
  "client_transaction_id": "6681eadc-6d8d-44ba-8ca0-18e061c1172a",
  "mcc": "5411",
  "card_country": "MEX",
  "processor_name": "VISA",
  "transaction_reference": "daa8583d-f18c-419a-840e-be5c95011eb6",
  "payment_method": "card",
  "card_details": {
    "card_sequential": "11",
    "prosa_info": {},
    "reading_type": "ICC",
    "tlv": "9F2701809F1A0206049A032208309F02060000000120005F2A0206044F07A00000000310109F0607A00000000310109F26085DE291D252397F709F100706010A03A020009F37044A05C99750095649534120544553549F6E009F5B009F3602008C9F330360F8C89F03009C010082021C008407A00000000310105F34011195058080048000"
  },
  "transaction_id": "111663896831621702",
  "created": 1663896831738,
  "merchant_name": "Mi Comercio México",
  "transaction_type": "REFUND",
  "processor": {
    "code": "000",
    "message": "Transacción Aprobada."
  },
  "reference_number": "226520105211",
  "tax_id": "MCC800101HNG",
  "sync_mode": "online",
  "additional_info": {
    "f7": "0922203351",
    "f32": "408210",
    "f11": "100611",
    "f62s2": "40000000000000000302145412649612",
    "f37": "226520100611"
  },
  "subtotal_iva0": 500,
  "deferred": {
    "months": "1"
  },
  "response_code": "00",
  "transaction_status": "APPROVAL",
  "social_reason": "MI COMERCIO MÉXICO",
  "payment_brand": "VISA",
  "acquirer_bank": "Kushki",
  "request_amount": 500,
  "merchant_id": "20000000103802320000",
  "approved_transaction_amount": 500,
  "merchant_category": "Medium",
  "acq_transaction_type": "Refund",
  "security": {
    "ip": "187.212.254.148",
    "user_agent": "PostmanRuntime/7.29.2"
  },
  "masked_credit_card": "476134XXXXXX0043",
  "authorization_code": "120606",
  "issuing_bank": "BANORTE",
  "processor_id": "1652365464",
  "cvm_type": "pin",
  "foreign_card": false,
  "pos_details": {
    "location": {
      "latitude": 19.4326,
      "longitude": -99.1332
    },
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.28",
    "brand": "SUNMI",
    "terminal_id": "PB04209860189"
  },
  "last_four_digits": "0043",
  "approval_code": "120606",
  "amount": {
    "extra_taxes": {},
    "currency": "MXN",
    "subtotal_iva0": 500
  },
  "rules_response": {
    "country": "MEX",
    "commercial_executive": "user@example.com",
    "business_category": "0",
    "address": "Av. Insurgentes Sur 1234",
    "contact_person": "Juan García",
    "authorizer": {
      "authorizer_name": "VISA",
      "soft_descriptor": "KSK*MI COMERCIO",
      "authorizer_bank_id": "",
      "authorizer_type": "",
      "commerce_code": "353453",
      "authorizer_acquirer_bin": "476134",
      "retailer_id": "",
      "category_model": "0",
      "terminal_id": "1652365464",
      "authorizer_alias": "VISA"
    },
    "city": "Ciudad de México",
    "province": "CDMX",
    "merchant_name": "Mi Comercio México",
    "telephone": "+525512345678",
    "mcc": "5411",
    "zip_code": "06600",
    "tax_id": "MCC800101HNG",
    "tcc": "H",
    "business_registration_id": "000000000001",
    "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": "319228478889680321",
  "card_country_code": "MEX",
  "credential_alias": "Mi Comercio México",
  "bin_card": "476134",
  "credential_id": "245c10532cd844e28e4ec9a83159d89b",
  "transactionReference": "daa8583d-f18c-419a-840e-be5c95011eb6"
}

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

Webhooks — Reembolsos

Estructura de la solicitud#

Ejemplo#

Estructura de la solicitud

Ejemplo