Webhooks para tarjeta presente
Recibe notificaciones de los eventos ocurridos en tu comercio a través de webhooks en tu sistema.
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:
¿Cuáles son las buenas prácticas a tener en cuenta al consumir un Webhook?
¿Cómo consultar tus Webhooks a través de la consola o vía API?
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
Variable | Type |
---|---|
country | string |
franchise | string |
available | boolean |
channel | string |
public_credential_id | string |
client_transaction_id | string |
mcc | string |
card_country | string |
processor_name | string |
transaction_reference | string |
payment_method | string |
card_details | object |
card_details.prosa_info | object |
card_details.reading_type | string |
card_details.card_sequential | string |
card_details.tlv | string |
transaction_id | string |
created | integer |
merchant_name | string |
transaction_type | string |
processor | object |
processor.code | string |
processor.message | string |
reference_number | string |
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 |
deferred | object |
deferred.months | string |
response_code | string |
transaction_status | string |
social_reason | string |
payment_brand | string |
acquirer_bank | string |
request_amount | number |
merchant_id | string |
merchant_category | string |
acq_transaction_type | string |
security | object |
security.ip | string |
security.user_agent | string |
masked_credit_card | string |
authorization_code | string |
issuing_bank | string |
processor_id | string |
foreign_card | boolean |
pos_details | object |
pos_details.model | string |
pos_details.location | object |
pos_details.location.latitude | number |
pos_details.location.longitude | number |
pos_details.version | string |
pos_details.brand | string |
pos_details.terminal_id | string |
last_four_digits | string |
approval_code | string |
amount | object |
amount.extra_taxes | object |
amount.currency | string |
amount.subtotal_iva0 | number |
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 amount | 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 |
ticket_number | string |
card_country_code | string |
credential_alias | string |
bin_card | string |
credential_id | string |
cvm_type | string |
approved_transaction_amount | number |
transaction_reference | string |
Ejemplos
- JSON
{"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
Variable | Type |
---|---|
country | string |
franchise | string |
available | boolean |
channel | string |
public_credential_id | string |
client_transaction_id | string |
mcc | string |
card_country | string |
processor_name | string |
transaction_reference | string |
payment_method | string |
card_details | object |
card_details.prosa_info | object |
card_details.reading_type | string |
card_details.card_sequential | string |
card_details.tlv | string |
transaction_id | string |
created | integer |
merchant_name | string |
transaction_type | string |
processor | object |
processor.code | string |
processor.message | string |
reference_number | string |
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 |
deferred | object |
deferred.months | string |
response_code | string |
transaction_status | string |
social_reason | string |
payment_brand | string |
acquirer_bank | string |
request_amount | number |
merchant_id | string |
merchant_category | string |
acq_transaction_type | string |
security | object |
security.ip | string |
security.user_agent | string |
masked_credit_card | string |
authorization_code | string |
issuing_bank | string |
processor_id | string |
foreign_card | boolean |
pos_details | object |
pos_details.model | string |
pos_details.location | object |
pos_details.location.latitude | number |
pos_details.location.longitude | number |
pos_details.version | string |
pos_details.brand | string |
pos_details.terminal_id | string |
last_four_digits | string |
approval_code | string |
amount | object |
amount.extra_taxes | object |
amount.currency | string |
amount.subtotal_iva0 | number |
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 amount | 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 |
ticket_number | string |
card_country_code | string |
credential_alias | string |
bin_card | string |
credential_id | string |
cvm_type | string |
approved_transaction_amount | number |
transaction_reference | string |
Ejemplos
- JSON
{"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"}