Webhooks para tarjeta presente

Te contamos sobre las notificaciones que recibirá tu comercio a través de Webhooks cada vez que se realicen transacciones con el servicio de tarjeta presente de Kushki.

Una vez ocurra algún evento en la cuenta de tu comercio, recibirás una notificación a través de un Webhook; este consiste en una petición HTTP; usualmente a través del método POST. El cuerpo de este objeto describe el evento originado en tu cuenta.

Si cuentas con la funcionalidad de Webhooks para tarjeta presente en tu comercio, recibirás notificaciones en los siguientes escenarios:

  • Al actualizar la membresía de un cliente en tu base de datos cuando un pago es exitoso.
  • Al registrar un asiento contable (también conocida como entrada de contabilidad) una vez realices una transacción.

Para conocer los pasos que debes seguir para consumir y configurar un Webhook en tu cuenta, por favor revisa las siguientes guías:

Webhook para pagos con tarjeta presente

Kushki enviará un evento de Webhook a tu comercio, notificando a tu aplicación cuando ocurre uno de los siguientes eventos:

  • Cuando una transacción con tarjeta de crédito o débito es aprobada o rechazada.
  • Cuando se realiza una autorización.
  • Cuando se hace una captura de fondos.
  • Cuando se realiza una cancelación.
  • Cuando se realiza una reversión.
  • Cuando se realiza una consulta de saldo.

Estructura

Los Webhooks enviados por Kushki contendrán los encabezados (headers) aquí listados. Las siguientes son las posibles variables que se entregan en el Webhook:

Método: POST

Body: Object

VariableType
countrystring
franchisestring
availableboolean
channelstring
public_credential_idstring
client_transaction_idstring
mccstring
card_countrystring
processor_namestring
transaction_referencestring
payment_methodstring
card_detailsobject
card_details.prosa_infoobject
card_details.reading_typestring
card_details.card_sequentialstring
card_details.tlvstring
transaction_idstring
createdinteger
merchant_namestring
transaction_typestring
processorobject
processor.codestring
processor.messagestring
reference_numberstring
tax_idstring
sync_modestring
additional_infoobject
additional_info.f7string
additional_info.f63string
additional_info.f11string
additional_info.f37string
additional_info.f32string
additional_info.f62s2string
subtotal_iva0number
deferredobject
deferred.monthsstring
response_codestring
transaction_statusstring
social_reasonstring
payment_brandstring
acquirer_bankstring
request_amountnumber
merchant_idstring
merchant_categorystring
acq_transaction_typestring
securityobject
security.ipstring
security.user_agentstring
masked_credit_cardstring
authorization_codestring
issuing_bankstring
processor_idstring
foreign_cardboolean
pos_detailsobject
pos_details.modelstring
pos_details.locationobject
pos_details.location.latitudenumber
pos_details.location.longitudenumber
pos_details.versionstring
pos_details.brandstring
pos_details.terminal_idstring
last_four_digitsstring
approval_codestring
amountobject
amount.extra_taxesobject
amount.currencystring
amount.subtotal_iva0number
rules_responseobject
rules_response.countrystring
rules_response.commercial_executivestring
rules_response.business_categorystring
rules_response.addressstring
rules_response.citystring
rules_response.authorizerobject
rules_response.authorizer.authorizer_namestring
rules_response.authorizer.soft_descriptorstring
rules_response.authorizer.authorizer_bank_idstring
rules_response.authorizer.commerce_codestring
rules_response.authorizer.authorizer_typestring
rules_response.authorizer.retailer_idstring
rules_response.authorizer.authorizer_acquirer_binstring
rules_response.authorizer.category_modelstring
rules_response.authorizer.urlstring
rules_response.authorizer.authorizer_aliasstring
rules_response.authorizer.terminal_idstring
rules_response.contact_personstring
rules_response.merchant_namestring
rules_response.telephonestring
rules_response.mccstring
rules_response.urlstring
rules_response.zip_codestring
rules_response.tax_idstring
rules_response.provincestring
rules_response.business_registration_idstring
rules_response.tccstring
rules_response.total amountstring
rules_response.business_linestring
rules_response.currencystring
rules_response.idstring
rules_response.acquirer_typestring
acq_transaction_scopestring
contact_detailsobject
contact_details.document_numberstring
contact_details.document_typestring
acq_transaction_modestring
card_typestring
ticket_numberstring
card_country_codestring
credential_aliasstring
bin_cardstring
credential_idstring
cvm_typestring
approved_transaction_amountnumber
transaction_referencestring

Ejemplos

{
"country": "Mexico",
"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": {
"prosa_info": {},
"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": "MXN",
"subtotal_iva0": 101.99
},
"rules_response": {
"country": "MEX",
"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": "http://internal-k8s-acquirer-acquirer-83c4eec5cf-1220747559.us-east-1.elb.amazonaws.com/mc/"
},
"city": "Monterrey",
"contact_person": "John Doe",
"merchant_name": "Tu libreria",
"telephone": "8100000001",
"mcc": "1234",
"tax_id": "asdf12345678",
"url": "http://internal-k8s-acquirer-acquirer-83c4eec5cf-1220747559.us-east-1.elb.amazonaws.com/mc/",
"zip_code": "64000",
"province": "NUEVO LEON",
"tcc": "H",
"total_amount": "101.990000",
"business_registration_id": "000000000001",
"business_line": "37006",
"currency": "MXN",
"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": "MEX",
"credential_alias": "Tu libreria",
"bin_card": "545195",
"credential_id": "245c10532cd844e28e4ec9a83159d89b",
"transactionReference": "718fa526-6f41-405f-a1f5-a71db52dfdd2"
}
{
"country": "Mexico",
"franchise": "MASTERCARD",
"available": true,
"channel": "POS",
"public_credential_id": "146cbf33c7fd45c4111cbf9d3f04478d",
"client_transaction_id": "6610eadc-6c1d-44aa-8ca0-18e061c1472a",
"mcc": "1234",
"card_country": "CHL",
"processor_name": "MASTERCARD",
"transaction_reference": "a1c8ccb4-0bbc-4661-8b22-7355bd1a2701",
"payment_method": "card",
"card_details": {
"prosa_info": {},
"reading_type": "MCR"
},
"transaction_id": "151663895657169613",
"created": 1663895657169,
"merchant_name": "Tu libreria",
"transaction_type": "PREAUTH",
"processor": {
"code": "000",
"message": "Transacción Aprobada."
},
"reference_number": "226520101814",
"tax_id": "7283839425223",
"sync_mode": "online",
"additional_info": {
"f7": "0922201417",
"f63": "MDS8TNCN9",
"f11": "101884",
"f37": "226520101884"
},
"subtotal_iva0": 601,
"deferred": {
"months": "1"
},
"response_code": "00",
"transaction_status": "APPROVAL",
"social_reason": "TU LIBRERIA",
"payment_brand": "MASTERCARD",
"acquirer_bank": "Kushki",
"request_amount": 601,
"merchant_id": "20000000505013348000",
"approved_transaction_amount": 601,
"merchant_category": "Medium",
"acq_transaction_type": "preAuth",
"security": {
"ip": "187.212.254.148",
"user_agent": "PostmanRuntime/7.29.2"
},
"masked_credit_card": "222300XXXXXX0018",
"authorization_code": "918762",
"issuing_bank": "BankACQ",
"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": "PB04016R20519"
},
"last_four_digits": "0018",
"approval_code": "918762",
"amount": {
"extra_taxes": {},
"currency": "MXN",
"subtotal_iva0": 601
},
"rules_response": {
"country": "MEX",
"address": "Centro 123",
"business_category": "0",
"commercial_executive": "user@example.com",
"city": "Monterrey",
"authorizer": {
"authorizer_name": "MASTERCARD",
"soft_descriptor": "KSK*TEST",
"authorizer_bank_id": "",
"authorizer_type": "",
"commerce_code": "353453",
"retailer_id": "",
"authorizer_acquirer_bin": "24477",
"category_model": "0",
"url": "http://internal-k8s-acquirer-acquirer-83c4eec5cf-1220747559.us-east-1.elb.amazonaws.com/mc/",
"terminal_id": "1632369464",
"authorizer_alias": "MASTERCARD"
},
"contact_person": "John Doe",
"merchant_name": "Tu libreria",
"telephone": "8100000001",
"mcc": "1234",
"zip_code": "64000",
"tax_id": "asdf12345678",
"url": "http://internal-k8s-acquirer-acquirer-83c4eec5cf-1220747559.us-east-1.elb.amazonaws.com/mc/",
"province": "NUEVO LEON",
"tcc": "H",
"total_amount": "601.000000",
"business_registration_id": "000000000001",
"business_line": "37006",
"currency": "MXN",
"id": "1652365464",
"acquirer_type": "kushki"
},
"acq_transaction_scope": "international",
"contact_details": {
"document_type": "-1"
},
"acq_transaction_mode": "Authorization",
"card_type": "credit",
"ticket_number": "111663895707169666",
"card_country_code": "MEX",
"credential_alias": "Tu libreria",
"bin_card": "222300",
"credential_id": "245c10532cd544e28e4eb9a70659d89b",
"transactionReference": "a1c8ccb4-0bbc-4661-8b22-7355bd1a2701"
}
{
"country": "Mexico",
"franchise": "MASTERCARD",
"available": true,
"channel": "POS",
"public_credential_id": "146caf33c7fd45c4941cbf9d3f04478d",
"client_transaction_id": "ae6dd91a-9173-4ec7-8934-3178454ef341",
"mcc": "1234",
"card_country": "CHL",
"processor_name": "MASTERCARD",
"transaction_reference": "777fea10-24f2-4bb9-8d0c-8ae717fce2e8",
"payment_method": "card",
"card_details": {
"prosa_info": {},
"reading_type": "MCR"
},
"transaction_id": "111663895948960466",
"created": 1663895948960,
"merchant_name": "Tu libreria",
"transaction_type": "CAPTURE",
"processor": {
"code": "000",
"message": "Transacción Aprobada."
},
"reference_number": "226601101885",
"tax_id": "7283839421223",
"sync_mode": "online",
"additional_info": {
"f7": "0923011908",
"f63": "MDS8TNCN9",
"f11": "101885",
"f37": "226601101885"
},
"subtotal_iva0": 2000,
"deferred": {
"months": "1"
},
"response_code": "00",
"transaction_status": "APPROVAL",
"social_reason": "TU LIBRERIA",
"payment_brand": "MASTERCARD",
"acquirer_bank": "Kushki",
"request_amount": 2000,
"merchant_id": "20000000105053348000",
"approved_transaction_amount": 2000,
"merchant_category": "Medium",
"acq_transaction_type": "capture",
"security": {
"ip": "187.252.251.248",
"user_agent": "PostmanRuntime/7.29.2"
},
"masked_credit_card": "222300XXXXXX0018",
"authorization_code": "423101",
"issuing_bank": "BankACQ",
"processor_id": "1652365464",
"foreign_card": true,
"pos_details": {
"model": "P2-EU",
"location": {
"latitude": -0.1848534,
"longitude": -78.4769761
},
"version": "Kushki SunmiV1.1.13",
"brand": "SUNMI",
"terminal_id": "PB04209860189"
},
"last_four_digits": "0018",
"approval_code": "423101",
"amount": {
"extra_taxes": {},
"currency": "COP",
"subtotal_iva0": 2000
},
"rules_response": {
"country": "MEX",
"commercial_executive": "marco@kushkipagos.com",
"address": "Direccion prueba",
"business_category": "0",
"city": "Guanajuato",
"authorizer": {
"authorizer_name": "MASTERCARD",
"soft_descriptor": "KSK*TEST",
"authorizer_bank_id": "",
"authorizer_type": "",
"commerce_code": "353453",
"authorizer_acquirer_bin": "24477",
"retailer_id": "",
"category_model": "0",
"authorizer_alias": "MASTERCARD",
"url": "http://internal-k8s-acquirer-acquirer-83c4eec5cf-1220747559.us-east-1.elb.amazonaws.com/mc/",
"terminal_id": "1652365464"
},
"contact_person": "Person Contact 1",
"merchant_name": "Tu libreria",
"telephone": "0987654321",
"mcc": "1234",
"tax_id": "asdf12345678",
"zip_code": "12345",
"url": "http://internal-k8s-acquirer-acquirer-83c4eec5cf-1220747559.us-east-1.elb.amazonaws.com/mc/",
"province": "AGUASCALIENTES",
"total_amount": "2000.000000",
"tcc": "H",
"business_registration_id": "000000000001",
"business_line": "37006",
"currency": "MXN",
"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": "111663895948960466",
"card_country_code": "MEX",
"credential_alias": "Tu libreria",
"bin_card": "222300",
"credential_id": "245c10532cd844e28e4ec9a70659d89b",
"transactionReference": "777fea10-24f2-4bb9-8d0c-8ae717fce2e8"
}

Webhook para reembolsos con tarjeta presente

Kushki puede notificarte eventos al Webhook que configuraste, notificando a tu aplicación cuando un reembolso es aprobado.

Estructura

Los webhooks enviados por Kushki contendrán los encabezados que se enumeran aquí.

Estas son las posibles variables que se envían en el cuerpo del Webhook:

Método: POST

Body: Object

VariableType
countrystring
franchisestring
availableboolean
channelstring
public_credential_idstring
client_transaction_idstring
mccstring
card_countrystring
processor_namestring
transaction_referencestring
payment_methodstring
card_detailsobject
card_details.prosa_infoobject
card_details.reading_typestring
card_details.card_sequentialstring
card_details.tlvstring
transaction_idstring
createdinteger
merchant_namestring
transaction_typestring
processorobject
processor.codestring
processor.messagestring
reference_numberstring
tax_idstring
sync_modestring
additional_infoobject
additional_info.f7string
additional_info.f63string
additional_info.f11string
additional_info.f37string
additional_info.f32string
additional_info.f62s2string
subtotal_iva0number
deferredobject
deferred.monthsstring
response_codestring
transaction_statusstring
social_reasonstring
payment_brandstring
acquirer_bankstring
request_amountnumber
merchant_idstring
merchant_categorystring
acq_transaction_typestring
securityobject
security.ipstring
security.user_agentstring
masked_credit_cardstring
authorization_codestring
issuing_bankstring
processor_idstring
foreign_cardboolean
pos_detailsobject
pos_details.modelstring
pos_details.locationobject
pos_details.location.latitudenumber
pos_details.location.longitudenumber
pos_details.versionstring
pos_details.brandstring
pos_details.terminal_idstring
last_four_digitsstring
approval_codestring
amountobject
amount.extra_taxesobject
amount.currencystring
amount.subtotal_iva0number
rules_responseobject
rules_response.countrystring
rules_response.commercial_executivestring
rules_response.business_categorystring
rules_response.addressstring
rules_response.citystring
rules_response.authorizerobject
rules_response.authorizer.authorizer_namestring
rules_response.authorizer.soft_descriptorstring
rules_response.authorizer.authorizer_bank_idstring
rules_response.authorizer.commerce_codestring
rules_response.authorizer.authorizer_typestring
rules_response.authorizer.retailer_idstring
rules_response.authorizer.authorizer_acquirer_binstring
rules_response.authorizer.category_modelstring
rules_response.authorizer.urlstring
rules_response.authorizer.authorizer_aliasstring
rules_response.authorizer.terminal_idstring
rules_response.contact_personstring
rules_response.merchant_namestring
rules_response.telephonestring
rules_response.mccstring
rules_response.urlstring
rules_response.zip_codestring
rules_response.tax_idstring
rules_response.provincestring
rules_response.business_registration_idstring
rules_response.tccstring
rules_response.total amountstring
rules_response.business_linestring
rules_response.currencystring
rules_response.idstring
rules_response.acquirer_typestring
acq_transaction_scopestring
contact_detailsobject
contact_details.document_numberstring
contact_details.document_typestring
acq_transaction_modestring
card_typestring
ticket_numberstring
card_country_codestring
credential_aliasstring
bin_cardstring
credential_idstring
cvm_typestring
approved_transaction_amountnumber
transaction_referencestring

Ejemplos

{
"country": "Mexico",
"franchise": "VISA",
"available": true,
"channel": "POS",
"public_credential_id": "146cbf33c7fd45c0271cbf9d31d4478d",
"client_transaction_id": "6681eadc-6d8d-44ba-8ca0-18e061c1172a",
"mcc": "1234",
"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": "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": "MXN",
"subtotal_iva0": 60
},
"rules_response": {
"country": "MEX",
"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": "http://internal-k8s-acquirer-acquirer-83c4eec5cf-1220747559.us-east-1.elb.amazonaws.com/visa/"
},
"city": "Monterrey",
"merchant_name": "Tu libreria",
"telephone": "8100000001",
"mcc": "1234",
"url": "http://internal-k8s-acquirer-acquirer-83c4eec5cf-1220747559.us-east-1.elb.amazonaws.com/visa/",
"zip_code": "64000",
"tax_id": "asdf12345678",
"province": "NUEVO LEON",
"total_amount": "60.000000",
"business_registration_id": "000000000001",
"tcc": "H",
"business_line": "37006",
"currency": "MXN",
"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": "MEX",
"credential_alias": "Tu libreria",
"bin_card": "476134",
"credential_id": "245c10502cd844ebae4ec9a70610d89b",
"transactionReference": "daa8583d-f18c-419a-840e-be5c95011eb6"
}