Webhooks with Smartlinks

August 03, 2023

When making payments through a Smartlink you will be notified of the following events for card payments.

Transaction approved
Declined transaction

Structure

The webhooks sent by Kushki will contain the headers listed here.

Card Payments

The following is a description of the possible variables delivered in the body of the webhook for credit card payments:

Method: POST

Body: Object

Variable	Type
`publicMerchantId`	`string`
`amount`	`object`
`amount.subtotalIva0`	`integer`
`amount.iva`	`integer`
`amount.subtotalIva`	`integer`
`amount.currency`	`string`
`metadata`	`object`
`metadata.total`	`string`
`metadata.nombreApellido`	`string`
`metadata.cedula`	`string`
`metadata.direccion`	`string`
`metadata.productos`	`string`
`metadata.email`	`string`
`created`	`integer (Unix Timestamp Format)`
`syncMetadata`	`string`
`smartLink`	`string`
`id`	`string`
`status`	`string`
`paymentMethod`	`string`
`ticketNumber`	`string`
`approvalCode`	`string`
`approvedTransactionAmount`	`number`
`bank`	`string`
`binCard`	`string`
`cardCountry`	`string`
`cardHolderName`	`string`
`lastFourDigits`	`string`
`paymentBrand`	`string`
`paymentConfigType`	`fixed` `open`
`processorBankName`	`string`
`requestAmount`	`number`
`responseCode`	`string`
`responseText`	`string`
`transactionType`	`string`
`type`	`string`
`transactionReference`	`string`

Examples

JSON
JSON

// Approved Transaction
{
 "id": "d5d2da2b-9213-4193-b72e-89508deec554",
 "amount": {
  "currency": "USD",
  "iva": 27.6,
  "subtotalIva": 230,
  "subtotalIva0": 0
 },
 "approvalCode": "000000",
 "approvedTransactionAmount": 257.6,
 "bank": "BANK NAME",
 "binCard": "424242",
 "cardCountry": "Ecuador",
 "cardHolderName": "Jhon Doe",
 "contactDetails": {},
 "created": 1689093048576,
 "lastFourDigits": "4242",
 "merchantId": "20000000108216107000",
 "metadata": {},
 "paymentBrand": "Visa",
 "paymentConfigType": "fixed", 
 "paymentMethod": "creditCard",
 "processorBankName": "0032~BANCO INTERNACIONAL",
 "publicMerchantId": "2ce2008060b146ed964692cc1fad8957",
 "requestAmount": 257.6,
 "responseCode": "000",
 "responseText": "Transacción aprobada",
 "smartLink": "0saIIYkDB",
 "status": "approvedTransaction",
 "syncMetadata": "false",
 "ticketNumber": "634537651430879765",
 "token": "d4c0ae7db80d4520b99eaa1e7a600c97",
 "transactionReference": "6487061f-8b90-47e2-a728-6b229300e73b",
 "type": "credit"
}

// Declined Transaction
{
  "amount": {
    "subtotalIva0": 49000,
    "iva": 0,
    "subtotalIva": 0,
    "currency": "COP"
  },
  "metadata": {
    "email": "test@kushki.com"
  },
  "code": "017",
  "transactionReference": null,
  "created": 1602089066473,
  "smartLink": "QG02kRklU",
  "message": "Transacción declinada.",
  "contactDetails": {
    "email": "test@kushki.com"
  },
  "token": "f71431f596834c8b8fe5a51b40db2138",
  "publicMerchantId": "20000000XXXXXX2000",
  "merchantId": "20000000XXXXXX2000",
  "paymentMethod": "creditCard",
  "syncMetadata": "true",
  "id": "9dfa0186-95e3-48cf-868e-47ce591d242c",
  "status": "declinedTransaction"
}

Wire Transfer Payments

These are the possible variables that are submitted in the webhook body for wire transfer payments:

Method: POST

Body: Object

Header	Header
`publicMerchantId`	`string`
`amount`	`object`
`amount.properties`	`integer`
`amount.iva`	`integer`
`amount.subtotalIva`	`integer`
`amount.currency`	`string`
`metadata`	`object`
`metadata.total`	`string`
`metadata.nombreApellido`	`string`
`metadata.cedula`	`string`
`metadata.direccion`	`string`
`metadata.productos`	`string`
`metadata.email`	`string`
`created`	`integer (Unix Timestamp Format)`
`syncMetadata`	`string`
`smartLink`	`string`
`id`	`string`
`status`	`string`
`paymentMethod`	`string`
`redirectUrl`	`string`
`description`	`string`
`bankName`	`string`
`bankId`	`string`
`trazabilityCode`	`string`
`email`	`string`

Examples

JSON
JSON

// Approved Transaction
{
  "ticketNumber": "1602089881960155",
  "amount": {
    "subtotalIva0": 49000,
    "iva": 0,
    "subtotalIva": 0,
    "currency": "COP"
  },
  "metadata": {
    "email": null
  },
  "redirectUrl": "https://api-uat.kushkipagos.com/transfer/v1/agent?token=4e85ec6daee54468919654c796e7bf74&mid=20000000XXXXXXX2000",
  "transactionReference": "0d3905a2-f30c-4d22-8106-d291f3afbbab",
  "created": 1602089886565,
  "bankName": "Kushki bank Colombia",
  "smartLink": "QG02kRklU",
  "contactDetails": {
    "email": "test@kushki.com"
  },
  "token": "4e85ec6daee54468919654c796e7bf74",
  "publicMerchantId": "20000000XXXXXXX2000",
  "bankId": "0001",
  "merchantId": "20000000XXXXXXX2000",
  "paymentMethod": "transfer",
  "syncMetadata": "false",
  "id": "b33ad9c2-9587-483d-9200-2f3ac7b3f883",
  "trazabilityCode": "823086197",
  "status": "approvedTransaction"
}

// Declined Transaction
{
  "amount": {
    "subtotalIva0": 15,
    "iva": 0,
    "subtotalIva": 0,
    "currency": "COP"
  },
  "metadata": {
    "email": null
  },
  "redirectUrl": "https://api-uat.kushkipagos.com/transfer/v1/agent?token=ee3feadd97a542149d2809eec9e55522&mid=20000000XXXXXXX2000",
  "transactionReference": "e19ee166-0306-487f-9810-ad79f444c315",
  "created": 1602090023831,
  "bankName": "Kushki bank Colombia",
  "smartLink": "QG02kRklU",
  "contactDetails": {
    "email": "test@kushki.com"
  },
  "token": "ee3feadd97a542149d2809eec9e55522",
  "publicMerchantId": "20000000XXXXXXX2000",
  "bankId": "0001",
  "merchantId": "20000000XXXXXXX2000",
  "paymentMethod": "transfer",
  "syncMetadata": "false",
  "id": "53657c39-ad54-442a-b86d-53476691bb7c",
  "trazabilityCode": "101210819",
  "status": "declinedTransaction"
}

Subscriptions

These are the possible variables that are submitted in the webhook body for subscription payments:

Method: POST

Body: Object

Header	Header
`publicMerchantId`	`string`
`amount`	`object`
`amount.subtotalIva0`	`integer`
`amount.iva`	`integer`
`amount.subtotalIva`	`integer`
`amount.currency`	`string`
`metadata`	`object`
`metadata.total`	`string`
`metadata.nombreApellido`	`string`
`metadata.cedula`	`string`
`metadata.direccion`	`string`
`metadata.productos`	`string`
`metadata.email`	`string`
`created`	`(Unix Timestamp Format)`
`syncMetadata`	`string`
`smartLink`	`string`
`id`	`string`
`status`	`string`
`paymentMethod`	`string`
`subscriptionDetails`	`object`
`subscriptionDetails.amount`	`object`
`subscriptionDetails.amount.subtotalIva0`	`integer`
`subscriptionDetails.amount.subtotalIva`	`integer`
`subscriptionDetails.amount.iva`	`integer`
`subscriptionDetails.amount.currency`	`string`
`subscriptionDetails.endDate`	`string "yyyy-mm-dd"`
`subscriptionDetails.terms`	`string`
`subscriptionDetails.periodicity`	`string`
`subscriptionDetails.planName`	`string`
`subscriptionDetails.startDate`	`string "yyyy-mm-dd"`
`subscriptionId`	`string`
`contactDetails`	`object`
`contactDetails.firstName`	`string`
`contactDetails.lastName`	`string`
`contactDetails.email`	`string`

Example

// Approved Transaction
{
  "amount": {
    "subtotalIva0": 49000,
    "iva": 0,
    "subtotalIva": 0,
    "currency": "COP"
  },
  "metadata": {
    "email": "test@kushki.com"
  },
  "created": 1602090156792,
  "smartLink": "QG02kRklU",
  "contactDetails": {
    "firstName": null,
    "lastName": null,
    "email": "test@kushki.com"
  },
  "token": "00efa6b6484c412b84271d59c2dacd8e",
  "publicMerchantId": "2200000000XXXXXXX200",
  "subscriptionDetails": {
    "amount": {
      "subtotalIva0": 15,
      "iva": 0,
      "subtotalIva": 0,
      "currency": "COP"
    },
    "terms": "<p>Acepto!</p>",
    "periodicity": "monthly",
    "planName": "Subscription-SmartLink",
    "startDate": "2020-10-07"
  },
  "merchantId": "2200000000XXXXXXX200",
  "paymentMethod": "subscription",
  "syncMetadata": "false",
  "id": "ba6f7ad1-0623-417a-93fc-74b2d4b98efc",
  "subscriptionId": "1602090156474000",
  "status": "approvedTransaction"
}