Webhooks for card present

October 29, 2024

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

Webhooks allow you to subscribe to events that may occur, such as a transaction being approved or declined. When an event is triggered, we will notify you through an endpoint that you have previously configured, sending a POST request with a JSON object containing all the necessary information about the event. Available events vary by integration type.

Cloud Terminal API and Raw Card-Present API

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

Discover the list of events available through Cloud terminal API and [Raw Card-Present API](/card- present-payments/raw-card-present-api/raw-card-present-api):

Approved transactions
Rejected transactions
Authorizations
Capture of funds
Voids/refunds
Reversals
Balance inquiry

Below is the list of properties available in the webhook. Please note that some properties may not be available at the time of notification depending on the transaction settings and payment method.

Property	Type	Description
country	String	Merchant country.
franchise	String	Processed card franchise.
available	boolean
channel	String	Channel through which the sale was made.
public_credential_id	String	Merchant public key.
client_transaction_id	String	Id generated by the merchant.
mcc	String	Merchant category code.
card_country	String	Country of processed card.
processor_name	String	Processor name.
transaction_reference	String	Unique reference per transaction generated by Kushki.
payment_method	String	Payment method.
card_details	Object	Object with additional information about the processed card.
card_details.prosa_info	String
card_details.reading_type	String	Card reading type.
card_details.card_sequential	String
card_details.tlv	String
transaction_id	String	Unique ID per transaction generated by Kushki.
created	Integer	Transaction date.
merchant_name	String	Merchant name.
transaction_type	String	Operation type.
processor	Object	Object with additional processor information.
processor.code	String	Processor response code.
processor.message	String	Processor response message.
reference_number	String	Transaction reference number.
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	Tax-free transaction amount.
deferred	Object
deferred.months	String	Number of installments (if the transaction was deferred).
response_code	String	Response code.
transaction_status	String	Transaction status.
social_reason	String	Social reason.
payment_brand	String	Card brand.
acquirer_bank	String
request_amount	String	Requested amount.
merchant_id	String	Merchant id.
merchant_category	String	Merchant category.
acq_transaction_type	String
security	Object
security.ip	String
security.user_agent	String
masked_credit_card	String	Masked card number.
authorization_code	String	Authorization code.
issuing_bank	String	Card issuing bank.
processor_id	String	Processor ID.
foreign_card	Boolean
pos_details	Object
pos_details.model	String	Terminal model.
pos_details.location	Object
pos_details.location.latitude	Number
pos_details.location.longitude	Number
pos_details.version	String	Terminal version.
pos_details.brand	String	Terminal brand.
pos_details.terminal_id	String	Terminal id.
last_four_digits	String	Las four digits of the card.
approval_code	String	Approval code.
amount	Object
amount.extra_taxes	Object
amount.currency	String	Transaction currency.
amount.subtotal_iva0	Number	Tax-free transaction amount.
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	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	Card type.
ticket_number	String	Ticker number.
card_country_code	String	Country code of the processed card.
credential_alias	String
bin_card	String	Card bin.
credential_id	String
cvm_type	String
approved_transaction_amount	Number	Authorized amount.
transaction_reference	String	Unique reference per transaction generated by Kushki.

Examples of webhooks for an approved transaction.

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

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

Examples of webhooks for a refund.

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