Webhooks — Card Payments - Kushki Developer Portal

Kushki sends a webhook notification to your endpoint when any of the following Card Present events occur:

A credit or debit card transaction is approved or declined

An authorization (pre-auth) is created

A capture is processed

A void (cancellation) is processed

A reversal is processed

A balance inquiry is made

Request structure

Webhook notifications use POST with the authentication headers.

Method: POST
Body: JSON object

Field	Type	Description
`country`	string	Country of the transaction — `"Mexico"`
`franchise`	string	Card network — `VISA`, `MASTERCARD`, `PROSA`
`metadata`	object	Custom metadata attached to the transaction
`metadata.key0`	string	Custom metadata field
`metadata.key1`	string	Custom metadata field
`metadata.key2`	string	Custom metadata field
`available`	boolean	Whether the transaction is available
`channel`	string	Transaction channel — `"POS"`
`public_credential_id`	string	Public credential used
`client_transaction_id`	string	UUID provided by the merchant
`mcc`	string	Merchant category code
`card_country`	string	ISO country code of the card-issuing country
`processor_name`	string	Name of the card processor
`transaction_reference`	string	Kushki transaction reference
`payment_method`	string	`"card"`
`card_details`	object	Card reading details
`card_details.prosa_info`	object	PROSA-specific card info (Mexico)
`card_details.reading_type`	string	`ICC`, `MCR`, or `NFC`
`card_details.card_sequential`	string	Card sequence number
`card_details.tlv`	string	Raw TLV data from the chip
`transaction_id`	string	Internal Kushki transaction ID
`created`	integer	Transaction creation timestamp (Unix ms)
`merchant_name`	string	Merchant display name
`transaction_type`	string	`SALE`, `PREAUTH`, `CAPTURE`, `VOID`, `REFUND`
`processor`	object	Processor response
`processor.code`	string	Processor response code
`processor.message`	string	Processor response message
`reference_number`	string	Acquirer reference number
`tax_id`	string	Merchant tax ID
`sync_mode`	string	`"online"`
`additional_info`	object	Additional ISO 8583 fields
`additional_info.f7`	string	ISO field 7
`additional_info.f63`	string	ISO field 63
`additional_info.f11`	string	ISO field 11
`additional_info.f37`	string	ISO field 37
`additional_info.f32`	string	ISO field 32
`additional_info.f62s2`	string	ISO field 62 sub-field 2
`subtotal_iva0`	number	Transaction subtotal (tax-exempt)
`deferred`	object	MSI installment details
`deferred.months`	string	Number of MSI months
`response_code`	string	ISO response code
`transaction_status`	string	`APPROVAL` or `DECLINED`
`social_reason`	string	Merchant legal name
`payment_brand`	string	Card network — `VISA`, `MASTERCARD`
`acquirer_bank`	string	Acquiring bank name
`request_amount`	number	Requested transaction amount
`merchant_id`	string	Kushki merchant ID
`merchant_category`	string	Merchant category
`acq_transaction_type`	string	Acquirer transaction type
`security`	object	Security metadata
`security.ip`	string	Client IP address
`security.user_agent`	string	Client user agent
`masked_credit_card`	string	Masked card number (e.g., `545195XXXXXX5480`)
`authorization_code`	string	Bank authorization code
`issuing_bank`	string	Name of the card-issuing bank
`processor_id`	string	Processor identifier
`foreign_card`	boolean	`true` if the card was issued outside Mexico
`pos_details`	object	POS terminal details
`pos_details.brand`	string	Terminal brand (e.g., `"SUNMI"`)
`pos_details.model`	string	Terminal model (e.g., `"P2-EU"`)
`pos_details.version`	string	Terminal software version
`pos_details.terminal_id`	string	Terminal identifier
`pos_details.location`	object	GPS coordinates of the terminal
`pos_details.location.latitude`	number	Latitude
`pos_details.location.longitude`	number	Longitude
`last_four_digits`	string	Last 4 digits of the card
`approval_code`	string	Bank approval code
`amount`	object	Full amount breakdown
`amount.currency`	string	`"MXN"`
`amount.subtotal_iva0`	number	Tax-exempt subtotal
`amount.extra_taxes`	object	Additional taxes
`rules_response`	object	Merchant configuration from Kushki rules engine
`rules_response.country`	string	`"MEX"`
`rules_response.city`	string	Merchant city
`rules_response.province`	string	Merchant state
`rules_response.address`	string	Merchant address
`rules_response.zip_code`	string	Merchant zip code
`rules_response.currency`	string	`"MXN"`
`rules_response.merchant_name`	string	Merchant name
`rules_response.mcc`	string	MCC
`rules_response.authorizer`	object	Acquirer/processor configuration
`acq_transaction_scope`	string	`"local"` or `"international"`
`contact_details`	object	Customer contact data
`contact_details.document_type`	string	Document type code
`contact_details.document_number`	string	Document number
`acq_transaction_mode`	string	`"Authorization"`
`card_type`	string	`credit`, `debit`, or `prepaid`
`ticket_number`	string	Kushki ticket number
`card_country_code`	string	`"MEX"`
`credential_alias`	string	Credential display name
`bin_card`	string	First 6 digits of the card
`credential_id`	string	Credential identifier
`cvm_type`	string	Cardholder verification method
`approved_transaction_amount`	number	Approved amount
`transactionReference`	string	Duplicate of `transaction_reference`

Examples

Charge

Authorization (preAuth)

Capture

{
  "country": "Mexico",
  "franchise": "MASTERCARD",
  "metadata": {
    "transaccionCodigo": "1245",
    "type": "test",
    "transaccionId": "1234"
  },
  "available": true,
  "channel": "POS",
  "public_credential_id": "146cbf33c7fd45c4111cbf9d3f04478d",
  "client_transaction_id": "ae6dd41a-9173-4ec7-8734-3178454ef341",
  "mcc": "1234",
  "card_country": "MEX",
  "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": "Mi Comercio México",
  "transaction_type": "SALE",
  "processor": {
    "code": "000",
    "message": "Transacción Aprobada."
  },
  "reference_number": "226520101801",
  "tax_id": "MCC800101HNG",
  "sync_mode": "online",
  "additional_info": {
    "f7": "0922200555",
    "f63": "MDS8TNCN9",
    "f11": "101883",
    "f37": "226520101883"
  },
  "subtotal_iva0": 500,
  "deferred": {
    "months": "1"
  },
  "response_code": "00",
  "transaction_status": "APPROVAL",
  "social_reason": "MI COMERCIO MÉXICO",
  "payment_brand": "MASTERCARD",
  "acquirer_bank": "Kushki",
  "request_amount": 500,
  "merchant_id": "20000000103802320000",
  "approved_transaction_amount": 500,
  "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": "BANORTE",
  "processor_id": "1652365464",
  "foreign_card": false,
  "pos_details": {
    "model": "P2-EU",
    "location": {
      "latitude": 19.4326,
      "longitude": -99.1332
    },
    "brand": "SUNMI",
    "version": "Kushki SunmiV1.1.28",
    "terminal_id": "PB04209860189"
  },
  "last_four_digits": "5480",
  "approval_code": "533804",
  "amount": {
    "extra_taxes": {},
    "currency": "MXN",
    "subtotal_iva0": 500
  },
  "rules_response": {
    "country": "MEX",
    "address": "Av. Insurgentes Sur 1234",
    "business_category": "0",
    "commercial_executive": "user@example.com",
    "authorizer": {
      "authorizer_name": "MASTERCARD",
      "soft_descriptor": "KSK*MI COMERCIO",
      "authorizer_bank_id": "",
      "authorizer_type": "",
      "commerce_code": "353453",
      "retailer_id": "",
      "authorizer_acquirer_bin": "545195",
      "category_model": "0",
      "terminal_id": "1652365464",
      "authorizer_alias": "MASTERCARD"
    },
    "city": "Ciudad de México",
    "province": "CDMX",
    "contact_person": "Juan García",
    "merchant_name": "Mi Comercio México",
    "telephone": "+525512345678",
    "mcc": "5411",
    "tax_id": "MCC800101HNG",
    "zip_code": "06600",
    "total_amount": "500.000000",
    "business_line": "37006",
    "currency": "MXN",
    "id": "1652365464",
    "acquirer_type": "kushki"
  },
  "acq_transaction_scope": "local",
  "contact_details": {
    "document_number": "GACJ800101HDFRRN09",
    "document_type": "CURP"
  },
  "acq_transaction_mode": "Authorization",
  "card_type": "credit",
  "ticket_number": "319228478889680318",
  "card_country_code": "MEX",
  "credential_alias": "Mi Comercio México",
  "bin_card": "545195",
  "credential_id": "245c10532cd844e28e4ec9a83159d89b",
  "transactionReference": "718fa526-6f41-405f-a1f5-a71db52dfdd2"
}

Got a suggestion on this documentation? Contact us.

Webhooks — Card Payments

Request structure#

Examples#

Request structure

Examples