Webhooks — Refunds - Kushki Developer Portal

Kushki sends a webhook notification to your endpoint when the following refund event occurs:

A refund is approved

INFO

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

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`
`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	`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	`"Refund"`
`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., `476134XXXXXX0043`)
`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.tax_id`	string	Merchant tax ID
`rules_response.tcc`	string	Terminal capability code
`rules_response.business_registration_id`	string	Business registration ID
`rules_response.business_line`	string	Business line code
`rules_response.business_category`	string	Business category
`rules_response.commercial_executive`	string	Commercial executive assigned
`rules_response.contact_person`	string	Contact person name
`rules_response.telephone`	string	Merchant phone number
`rules_response.total_amount`	string	Total transaction amount
`rules_response.id`	string	Merchant configuration ID
`rules_response.acquirer_type`	string	`"kushki"`
`rules_response.authorizer`	object	Acquirer/processor configuration
`rules_response.authorizer.authorizer_name`	string	Processor name
`rules_response.authorizer.soft_descriptor`	string	Soft descriptor on cardholder statement
`rules_response.authorizer.authorizer_bank_id`	string	Authorizer bank ID
`rules_response.authorizer.authorizer_type`	string	Authorizer type
`rules_response.authorizer.commerce_code`	string	Commerce code
`rules_response.authorizer.retailer_id`	string	Retailer ID
`rules_response.authorizer.authorizer_acquirer_bin`	string	BIN of the acquirer
`rules_response.authorizer.category_model`	string	Category model
`rules_response.authorizer.terminal_id`	string	Terminal ID in the authorizer
`rules_response.authorizer.authorizer_alias`	string	Authorizer alias
`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`

Example

{
  "country": "Mexico",
  "franchise": "VISA",
  "available": true,
  "channel": "POS",
  "public_credential_id": "146cbf33c7fd45c4111cbf9d3f04478d",
  "client_transaction_id": "6681eadc-6d8d-44ba-8ca0-18e061c1172a",
  "mcc": "5411",
  "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": "Mi Comercio México",
  "transaction_type": "REFUND",
  "processor": {
    "code": "000",
    "message": "Transacción Aprobada."
  },
  "reference_number": "226520105211",
  "tax_id": "MCC800101HNG",
  "sync_mode": "online",
  "additional_info": {
    "f7": "0922203351",
    "f32": "408210",
    "f11": "100611",
    "f62s2": "40000000000000000302145412649612",
    "f37": "226520100611"
  },
  "subtotal_iva0": 500,
  "deferred": {
    "months": "1"
  },
  "response_code": "00",
  "transaction_status": "APPROVAL",
  "social_reason": "MI COMERCIO MÉXICO",
  "payment_brand": "VISA",
  "acquirer_bank": "Kushki",
  "request_amount": 500,
  "merchant_id": "20000000103802320000",
  "approved_transaction_amount": 500,
  "merchant_category": "Medium",
  "acq_transaction_type": "Refund",
  "security": {
    "ip": "187.212.254.148",
    "user_agent": "PostmanRuntime/7.29.2"
  },
  "masked_credit_card": "476134XXXXXX0043",
  "authorization_code": "120606",
  "issuing_bank": "BANORTE",
  "processor_id": "1652365464",
  "cvm_type": "pin",
  "foreign_card": false,
  "pos_details": {
    "location": {
      "latitude": 19.4326,
      "longitude": -99.1332
    },
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.28",
    "brand": "SUNMI",
    "terminal_id": "PB04209860189"
  },
  "last_four_digits": "0043",
  "approval_code": "120606",
  "amount": {
    "extra_taxes": {},
    "currency": "MXN",
    "subtotal_iva0": 500
  },
  "rules_response": {
    "country": "MEX",
    "commercial_executive": "user@example.com",
    "business_category": "0",
    "address": "Av. Insurgentes Sur 1234",
    "contact_person": "Juan García",
    "authorizer": {
      "authorizer_name": "VISA",
      "soft_descriptor": "KSK*MI COMERCIO",
      "authorizer_bank_id": "",
      "authorizer_type": "",
      "commerce_code": "353453",
      "authorizer_acquirer_bin": "476134",
      "retailer_id": "",
      "category_model": "0",
      "terminal_id": "1652365464",
      "authorizer_alias": "VISA"
    },
    "city": "Ciudad de México",
    "province": "CDMX",
    "merchant_name": "Mi Comercio México",
    "telephone": "+525512345678",
    "mcc": "5411",
    "zip_code": "06600",
    "tax_id": "MCC800101HNG",
    "tcc": "H",
    "business_registration_id": "000000000001",
    "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": "319228478889680321",
  "card_country_code": "MEX",
  "credential_alias": "Mi Comercio México",
  "bin_card": "476134",
  "credential_id": "245c10532cd844e28e4ec9a83159d89b",
  "transactionReference": "daa8583d-f18c-419a-840e-be5c95011eb6"
}

Got a suggestion on this documentation? Contact us.

Webhooks — Refunds

Request structure#

Example#

Request structure

Example