Webhooks for card present

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, App to app and Terminal SDK

Discover the list of events available through integrations Cloud terminal API, [App to app](/mx/en/card-present- payments/app-to-app/app-to-app-overview) and Terminal SDK:

Approved transactions

Rejected transactions

Voids/refunds

Approved transactions

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
result	String	Transaction result. Possible values: `aprobada` for approved transactions.
amount	String	Transaction amount.
tip	String	If the transaction includes a tip, it will be returned.
payments	Integer	If the transaction has been deferred, the number of deferred installments will be returned.
authorizationTime	String	Authorization time. RFC 3339 date format.
reference	String	Transaction description.
transactionid	String	Transaction ID generated by Kushki.
authorization	String	Transaction authorization string.
creditcard	String	Last 4 digits of the card's Primary Account Number (PAN).
cardtype	String	Card issuer. Possible values: `VISA`, `MASTERCARD`, `CARNET`, `AMERICAN EXPRESS`.
arqc	String	EMV only. Authorization Request Cryptogram (ARQC) of the transaction.
userID	Integer	ID of the user who made the transaction.
aid	String	EMV only. Chip's Application ID.
applabel	String	EMV only. Chip's Application Label.
url	String	Unique identifier to access a transaction ticket.
email	String	Email to which the transaction ticket is sent.
phone	String	Phone number to which the transaction ticket is sent.
cardBrand	String	Card Issuer Network.
cardIssuer	String	Card Issuer Bank.
cardCountry	String	Card Country Code (ISO 3166-1 alpha-2).
cardClass	String	`DEBIT` or `CREDIT` card.
launchTime	String	Time the transaction was sent.
maskedPAN	String	Masked card number.
uniqueReference	String	Unique identifier per transaction generated on the client side to avoid duplicates. For example, UUID.

Example.

{
    "cardBrand": "MASTERCARD",
    "cardIssuer": "SANTANDER",
    "cardCountry": "MX",
    "cardClass": "CREDIT",
    "launchTime": "2024-05-29T11:01:27.360-0600",
    "userID": 61000,
    "authorizationTime": "2024-05-29T11:01:27.360-0600",
    "result": "aprobada",
    "amount": "100.00",
    "payments": 0,
    "transactionid": "128010",
    "authorization": "BP3500",
    "creditcard": "0009",
    "cardtype": "MASTERCARD",
    "arqc": "A38051D19B2548E3",
    "aid": "A0000000041010",
    "applabel": "Mastercard",
    "url": "face3142cb4d32a545f42d278b8cf4ce5ea3d0b1",
    "maskedPAN": "500000******0009",
    "uniqueReference": "d6732f94-6cf2-4dfb-aed7-11b64b739407"
}

Rejected transactions

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
result	String	Transaction result. Possible values: `rechazadaProsa` for rejected transactions.
amount	String	Transaction amount.
tip	String	If the transaction includes a tip, it will be returned.
payments	Integer	If the transaction includes a tip, it will be returned.
authorizationTime	String	Authorization time. RFC 3339 date format.
reference	String	Transaction description.
transactionid	String	Transaction ID generated by Kushki.
creditcard	String	Last 4 digits of the card's Primary Account Number (PAN).
cardtype	String	Card issuer. Possible values:`VISA`, `MASTERCARD`, `CARNET`, `AMERICAN EXPRESS`.
arqc	String	EMV only. Authorization Request Cryptogram (ARQC) of the transaction.
userID	Integer	ID of the user who made the transaction.
aid	String	EMV only. Chip's Application ID.
applabel	String	EMV only. Chip's Application Label.
cardBrand	String	Card Issuer Network.
cardIssuer	String	Card Issuer Bank.
cardCountry	String	Card Country Code (ISO 3166-1 alpha-2).
cardClass	String	`DEBIT` or `CREDIT` card.
launchTime	String	Time the transaction was sent.
maskedPAN	String	Masked card number.
uniqueReference	String	Unique identifier per transaction generated on the client side to avoid duplicates. For example, UUID.

Example.

{
    "cardBrand": "MASTERCARD",
    "cardIssuer": "SANTANDER",
    "cardCountry": "MX",
    "cardClass": "CREDIT",
    "launchTime": "2024-05-29T10:46:52.221-0600",
    "userID": 61000,
    "authorizationTime": "2024-05-29T10:46:52.221-0600",
    "result": "rechazadaProsa",
    "amount": "99.00",
    "payments": 0,
    "transactionid": "128011",
    "creditcard": "0009",
    "cardtype": "MASTERCARD",
    "arqc": "6FEC34124C9AAEEB",
    "aid": "A0000000041010",
    "applabel": "Mastercard",
    "maskedPAN": "500000******0009",
    "uniqueReference": "d6732f94-6cf2-4dfb-aed7-11b64b739407"
}

Voids/refunds

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
result	String	Transaction result. Possible values: `aprobada` for approved voids/refunds `rechazadaRiesgo`, `rechazadaProsa` o `rechazada` for rejected refunds. `pendiente` for pending refunds.
amount	String	Refund amount.
payments	Integer	If the transaction has been deferred, the number of deferred installments will be returned.
authorizationTime	String	Authorization time. RFC 3339 date format.
transactionid	String	Transaction ID generated by Kushki.
authorization	String	Transaction authorization string.
creditcard	String	Last 4 digits of the card's Primary Account Number (PAN).
cardtype	String	Card issuer. Possible values: `VISA`, `MASTERCARD`, `CARNET`, `AMERICAN EXPRESS`.
userID	Integer	ID of the user who made the transaction.
url	String	Unique identifier to access a transaction ticket.
cardBrand	String	Card Issuer Network.
cardCountry	String	Card Country Code (ISO 3166-1 alpha-2).
cardClass	String	`DEBIT` or `CREDIT` card.
launchTime	String	Time the request was sent.
maskedPAN	String	Masked card number.
uniqueReference	String	Unique identifier per transaction generated on the client side to avoid duplicates. For example, UUID.
transactionType	String	Transaction type. Possible values: `devolución` for voids/refunds.
transactionRefundedId	String	Original refunded transaction ID

Example.

{
    "cardBrand": "VISA",
    "cardCountry": "US",
    "cardClass": "CREDIT",
    "uniqueReference": "d6732f94-6cf2-4dfb-aed7-11b64b739407",
    "launchTime": "2024-08-16T10:02:37.965-0600",
    "userID": 61000,
    "authorizationTime": "2024-08-16T10:02:37.965-0600",
    "result": "aprobada",
    "amount": "1018.0",
    "payments": 0,
    "transactionid": "128013",
    "authorization": "BP4160",
    "creditcard": "0002",
    "cardtype": "VISA",
    "url": "19c6f19bc1a7a00a1d76021aa5eaef2627aba950",
    "maskedPAN": "400000******0002",
    "transactionType": "devolucion",
    "transactionRefundedId": "128012"
}

Raw Card-Present API

Webhooks Retry Policy

At Kushki we make sure that you receive a Webhook callback correctly. For this reason, the Webhooks retry policy process is performed as shown below:

First immediate retry: this happens via instant messaging (known as Notify Now).

The system awaits a 200/201 status code.

If we receive a different status, 3 retries are made in the next hour and then 4 retries are performed in the next 2 hours.
Considering that our logic of retries to send notifications works with a maximum of 7 retries within 3 hours once Notify Now fails.

After the 7 retries are completed, if you do not receive a successful response, the Webhook is marked as failed and we stop retrying.
If at the end of this submission cycle we have not received a successful status and you want to receive the webhook, please contact our Support Team.

How do retries work over the elapsed time?

If Notify Now fails, you must wait 20 minutes for the first retry to be sent and the same period of time to complete the hour, as shown below:

First retry: it is sent after 20 minutes.

Second retry: it is sent after 40 minutes.

Third retry: it is sent after 60 minutes (1 hour).
After 60 minutes (1 hour) and if the third retry fails, you must wait 30 minutes for the fourth retry to be sent until the next 2 hours are completed as described below:

Fourth retry: it is sent after 30 minutes.

Fifth retry: it is sent after 60 minutes.

Sixth retry: it is sent after 90 minutes.

Seventh retry: it is sent after 120 minutes.

Note

Keep in mind that these times are estimates and may be subject to variations.

The Webhooks sent by Kushki will contain the headers listed here

Discover the list of events available through Raw Card-Present API integrations:

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	`VISA`, `MASTERCARD`, `PROSA` (PROSA only in Mexico).
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	`VISA`, `MASTERCARD`
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.
pos_details.user	String	Device operator username. Only returned if sent in the request.
pos_details.friendly_name	String	Friendly display name of the terminal. Only returned if sent in the request.
pos_details.serial	String	Device serial number. Only returned if sent in the request.
pos_details.type	String	Physical device type. Possible values: `COUNTERTOP`, `MPOS`, `SMARTPOS`, `SELF_SERVICE`, `OTHER`. Only returned if sent in the request.
pos_details.connectivity	String	Network connectivity type. Possible values: `GPRS`, `WIFI`, `ETHERNET`, `DIAL_UP`, `OTHER`. Only returned if sent in the request.
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	`credit`, `debit`, `prepaid`
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

{
    "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": ""
        },
        "city": "Monterrey",
        "contact_person": "John Doe",
        "merchant_name": "Tu libreria",
        "telephone": "8100000001",
        "mcc": "1234",
        "tax_id": "asdf12345678",
        "url": "",
        "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"
}

Examples of webhooks for a refund.

You can also check the status of refunds from your Console.

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

Webhooks for card present

Cloud Terminal API, App to app and Terminal SDK#

Approved transactions#

Rejected transactions#

Voids/refunds#

Raw Card-Present API#

Webhooks Retry Policy#

How do retries work over the elapsed time?#

Cloud Terminal API, App to app and Terminal SDK

Approved transactions

Rejected transactions

Voids/refunds

Raw Card-Present API

Webhooks Retry Policy

How do retries work over the elapsed time?