Webhooks for card present

Receive notifications of events that occur in your merchant through webhooks in your system.

Once an event occurs in your merchant account, you will receive a notification through a Webhook; this consists of an HTTP request, usually through the POST method. The body of this object describes the event originating in your account.

If you have the Webhooks functionality for card-present transactions enabled in your merchant account, you will receive notifications in the following scenarios:

  • When updating a customer’s membership in your database upon successful payment.
  • When registering an accounting entry (also known as a ledger entry) once a transaction is completed.

To learn the steps you need to follow to consume and set up a Webhook in your account, please review the following guides::

Webhook for card-present payments

Kushki will send a webhook event to your merchant, notifying your application when one of the following events occurs:

When a credit or debit card transaction is approved or rejected. When an authorization is performed. When funds are captured. When a cancellation is made. When a reversal is made. When a balance inquiry is made.

Structure

The Webhooks sent by Kushki will contain the headers listed here. The following are the possible variables delivered in the Webhook:

Method: 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

  • JSON
  • JSON
  • 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"
}
//Authorization
{
"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"
}
//Capture
{
"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 for refunds with card-present payments

Kushki can notify you of events via the Webhook you’ve set up, informing your application when a refund is approved.

Structure

The Webhooks sent by Kushki will contain the headers listed here. These are the possible variables sent in the body of the Webhook:

Method: 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

Examples

  • 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"
}