Webhook para pagos recurrentes con tarjeta

12 marzo 2025

Kushki puede enviar eventos vía webhook que notifican a tu aplicación en el momento en que uno de los siguientes eventos ocurra:

Cuando se crea una suscripción (subscriptionApproved)
Cuando un cobro de una suscripción es exitoso (succesfullCharge)
Cuando un cobro de una suscripción bajo demanda es declinado (declinedCharge)
Cuando un intento de cobro de la suscripción calendarizada falló (failedRetry)
Cuando todos los intentos de cobro de la suscripción calendarizada fallan (lastRetry)
Cuando se elimina una suscripción (subscriptionDelete)

Estructura

Los webhooks enviados por Kushki contendrán los encabezados (headers) aquí listados.
Estas son las posibles variables que se entregan en el webhook:

Método: POST

Body: Object

Variable	Tipo	Descripción
`name`	`"succesfullCharge" "failedRetry" "lastRetry" "declinedCharge" "subscriptionDelete"` `"subscriptionApproved"`
`event`	`Object`
`event.id`	`string`
`event.metadata`	`Object`
`event.metadata.key0`	`string`
`event.metadata.key1`	`string`
`event.metadata.key2`	`string`
`event.subscriptionId`	`number`
`event.cardHolderName`	`string`
`event.amount`	`Object`
`event.amount.subtotalIva`	`number`
`event.amount.subtotalIva0`	`number`
`event.amount.iva`	`number`
`event.amount.ice`	`number`
`event.amount.currency`	`string`
`event.amount.extraTaxes`	`Object`
`event.amount.extraTaxes.agenciaDeViaje`	`number`
`event.amount.extraTaxes.iac`	`number`
`event.amount.extraTaxes.propina`	`number`
`event.amount.extraTaxes.tasaAeroportuaria`	`number`
`event.periodicity`	`string`
`event.contactDetails`	`Object`
`event.contactDetails.firstName`	`string`
`event.contactDetails.lastName`	`string`
`event.contactDetails.email`	`string`
`event.token`	`string`
`event.merchantId`	`string`
`event.startDate`	`number (Unix Timestamp Format)`
`event.endDate`	`number (Unix Timestamp Format)`
`event.created`	`number (Unix Timestamp Format)`
`event.planName`	`string`
`event.binInfo`	`Object`
`event.binInfo.bank`	`string`
`event.binInfo.type`	`string`
`event.binInfo.processor`	`string`
`event.binInfo.brand`	`string`
`event.dayOfMonth`	`number`
`event.month`	`string`
`event.dayOfWeek`	`string`
`event.retry.type`	`Object`
`event.retry.attempts`	`number`
`event.retry.max`	`number`
`event.retry.firstAttemptDate`	`number`
`event.retry.periodicity`	`number`
`event.retry.daysLeft`	`array`
`event.retry.daysLeft.items`	`integer`
`event.retryCount`	`number`
`event.expirationTime`	`number`
`event.active`	`boolean`
`event.lastFourDigits`	`string`
`event.adjustment`	`object`
`event.adjustment.amount`	`object`
`event.adjustment.amount.subtotalIva`	`number`
`event.adjustment.amount.subtotalIva0`	`number`
`event.adjustment.amount.iva`	`number`
`event.adjustment.amount.ice`	`number`
`event.adjustment.amount.currency`	`string`
`event.adjustment.amount.extraTaxes`	`object`
`event.adjustment.amount.extraTaxes.agenciaDeViaje`	`number`
`event.adjustment.amount.extraTaxes.iac`	`number`
`event.adjustment.amount.extraTaxes.propina`	`number`
`event.adjustment.amount.extraTaxes.tasaAeroportuaria`	`number`
`event.adjustment.periods`	`number`
`event.retryConfiguration`	`object`
`event.retryConfiguration.retryType`	`string`
`event.retryConfiguration.value`	`array`
`event.retryConfiguration.value.items`	`integer`
`event.nextAttemptDay`	`number`
`event.lastRetryDate`	`number`
`event.url`	`string`
`event.approvalCode`	`string`
`event.ticketNumber`	`string`
`event.lastChargeDate`	`number`
`responseCode`	`string`	Código de respuesta. Solo para declinaciones.
`responseText`	`string`	Texto de la respuesta. Solo para declinaciones.
`processor.code`	`string`	Código del procesador. Solo para declinaciones.
`processor.message`	`string`	Mensaje del procesador. Solo para declinaciones.
`messageFields.f38`	`string`	Campo específico de declinaciones por emisor o marca.
`messageFields.f48`	`object`	Códigos de respuesta. Solo para Mastercard.
`messageFields.f48.s22`	`string`	Corresponde al código citMit enviado en la solicitud. Solo para Mastercard.
`messageFields.f48.s84`	`string`	Código MAC (Merchant Advice Code) de Mastercard para transacciones declinadas.
`messageFields.f39`	`string`	Campo específico de declinaciones por emisor o marca.

Ejemplos

JSON
JSON
JSON
JSON
JSON

// Transacción aprobada
{
  "name": "succesfullCharge",
  "event": {
    "userAgent": "Go-http-client/1.1",
    "metadata": {
      "plan": {
        "fitness": {
          "pool": "include",
          "rumba": "include",
          "cardio": "include"
        }
      }
    },
    "subscriptionId": "1602024113521000",
    "created": 1602024113,
    "ip": "35.193.164.95",
    "lastChargeDate": 1602024176,
    "contactDetails": {
      "firstName": "Diego",
      "lastName": "Cadena",
      "phoneNumber": "+593988734644",
      "documentType": "CC",
      "documentNumber": "1009283738",
      "email": "test@test.com"
    },
    "periodicity": "monthly",
    "lastFourDigits": "4242",
    "active": true,
    "dayOfMonth": 6,
    "token": "da44953475f74c02abca31c5371e1792",
    "binInfo": {
      "bank": null,
      "brand": "VISA",
      "processor": "NA",
      "bin": "424242",
      "info": {
        "country": {
          "emoji": "🇺🇸",
          "latitude": 38,
          "alpha2": "US",
          "name": "United States of America",
          "numeric": "840",
          "currency": "USD",
          "longitude": -97
        },
        "number": {},
        "bank": {},
        "scheme": "visa",
        "type": "credit"
      }
    },
    "cardHolderName": "Pruebas",
    "maskedCardNumber": "424242XXXXXX4242",
    "month": "*",
    "planName": "Premium",
    "dayOfWeek": "?",
    "startDate": 1601942400,
    "amount": {
      "currency": "USD",
      "ice": 0,
      "subtotalIva0": 0,
      "iva": 0.14,
      "subtotalIva": 1
    },
    "id": "160202411352100020000000XXXXXXXX2000",
    "plccMetadataId": "187169a42eed456a9964dab5e7ec9468",
    "merchantId": "20000000XXXXXXXX2000",
    "transactionReference": "9eb4ec3d-5e83-4450-8d90-5047121bddbf",
    "approvalCode": "000000",
    "binCard": "424242",
    "issuingBank": null,
    "ticketNumber": "646245907500066871"
  }
}

// Transacción rechazada
{
  "name": "declinedCharge",
  "event": {
    "userAgent": "Go-http-client/1.1",
    "metadata": {
      "plan": {
        "fitness": {
          "pool": "include",
          "rumba": "include",
          "cardio": "include"
        }
      }
    },
    "subscriptionId": "1602024884332000",
    "created": 1602024884,
    "ip": "35.193.164.95",
    "contactDetails": {
      "firstName": "Diego",
      "lastName": "Cadena",
      "phoneNumber": "+593988734644",
      "documentType": "CC",
      "documentNumber": "1009283738",
      "email": "test@test.com"
    },
    "periodicity": "monthly",
    "lastFourDigits": "7015",
    "active": true,
    "dayOfMonth": 6,
    "token": "1637f3a2be6849cbbf2095693f7367c1",
    "binInfo": {
      "bank": "BANCO DE LA PRODUCCION S.A. (PRODUBANCO)",
      "brand": "VISA",
      "processor": "NA",
      "bin": "434900",
      "info": {
        "country": {
          "emoji": "🇪🇨",
          "latitude": -2,
          "alpha2": "EC",
          "name": "Ecuador",
          "numeric": "218",
          "currency": "USD",
          "longitude": -77.5
        },
        "number": {
          "length": 16,
          "luhn": true
        },
        "bank": {
          "name": "BANCO DE LA PRODUCCION,S.A. (PRODUBANCO)"
        },
        "scheme": "visa",
        "prepaid": false,
        "type": "CREDIT",
        "brand": "Traditional"
      }
    },
    "cardHolderName": "Pruebas",
    "maskedCardNumber": "434900XXXXXX7015",
    "planName": "Premium",
    "month": "*",
    "dayOfWeek": "?",
    "startDate": 1601942400,
    "amount": {
      "currency": "USD",
      "ice": 0,
      "subtotalIva0": 0,
      "iva": 0.14,
      "subtotalIva": 1
    },
    "plccMetadataId": "baae19a29bc64382b1cbdfd374cfaba6",
    "id": "160202488433200020000000XXXXXXXX2000",
    "merchantId": "20000000XXXXXXXX2000",
    "transactionReference": "4eeec12b-6554-469e-87b8-a432ab9c3106",
    "messageFields": {
      "f39": "83",
      "f48": {
        "s22": {
          "se5": "C101"
        },
        "s84": "14"
      },
      "restricted": false
    }
  }
}

// Intento de cobro fallido
{
  "name": "failedRetry",
  "event": {
    "userAgent": "Go-http-client/1.1",
    "metadata": {
      "plan": {
        "fitness": {
          "pool": "include",
          "rumba": "include",
          "cardio": "include"
        }
      }
    },
    "subscriptionId": "1602024884332000",
    "created": 1602024884,
    "ip": "35.193.164.95",
    "contactDetails": {
      "firstName": "Diego",
      "lastName": "Cadena",
      "phoneNumber": "+593988734644",
      "documentType": "CC",
      "documentNumber": "1009283738",
      "email": "test@test.com"
    },
    "periodicity": "monthly",
    "lastFourDigits": "7015",
    "active": true,
    "dayOfMonth": 6,
    "token": "1637f3a2be6849cbbf2095693f7367c1",
    "binInfo": {
      "bank": "BANCO DE LA PRODUCCION S.A. (PRODUBANCO)",
      "brand": "VISA",
      "processor": "NA",
      "bin": "434900",
      "info": {
        "country": {
          "emoji": "🇪🇨",
          "latitude": -2,
          "alpha2": "EC",
          "name": "Ecuador",
          "numeric": "218",
          "currency": "USD",
          "longitude": -77.5
        },
        "number": {
          "length": 16,
          "luhn": true
        },
        "bank": {
          "name": "BANCO DE LA PRODUCCION,S.A. (PRODUBANCO)"
        },
        "scheme": "visa",
        "prepaid": false,
        "type": "CREDIT",
        "brand": "Traditional"
      }
    },
    "cardHolderName": "Pruebas",
    "maskedCardNumber": "434900XXXXXX7015",
    "planName": "Premium",
    "month": "*",
    "dayOfWeek": "?",
    "startDate": 1601942400,
    "amount": {
      "currency": "USD",
      "ice": 0,
      "subtotalIva0": 0,
      "iva": 0.14,
      "subtotalIva": 1
    },
    "plccMetadataId": "baae19a29bc64382b1cbdfd374cfaba6",
    "id": "160202411352100020000000XXXXXXXX2000m",
    "merchantId": "20000000XXXXXXXX2000",
    "transactionReference": "9b85ba91-1a97-4964-bf6a-472a9b0cb813"
  }
}

// Suscripción borrada
{
  "name": "subscriptionDelete",
  "event": {
    "amount": {
      "subtotalIva0": 0,
      "iva": 0.14,
      "subtotalIva": 1,
      "currency": "USD",
      "ice": 0
    },
    "metadata": {
      "plan": {
        "fitness": {
          "rumba": "include",
          "pool": "include",
          "cardio": "include"
        }
      }
    },
    "cardHolderName": "Pruebas",
    "deleteAt": 1602024462,
    "created": 1602024113,
    "plccMetadataId": "187169a42eed456a9964dab5e7ec9468",
    "ip": "35.193.164.95",
    "active": false,
    "planName": "Premium",
    "userAgent": "Go-http-client/1.1",
    "contactDetails": {
      "firstName": "Diego",
      "lastName": "Cadena",
      "phoneNumber": "+593988734644",
      "documentType": "CC",
      "documentNumber": "1009283738",
      "email": "test@test.com"
    },
    "lastChargeDate": 1602024176,
    "maskedCardNumber": "424242XXXXXX4242",
    "token": "da44953475f74c02abca31c5371e1792",
    "dayOfWeek": "?",
    "month": "*",
    "binInfo": {
      "bank": null,
      "bin": "424242",
      "brand": "VISA",
      "processor": "NA",
      "info": {
        "country": {
          "emoji": "🇺🇸",
          "latitude": 38,
          "alpha2": "US",
          "name": "United States of America",
          "numeric": "840",
          "currency": "USD",
          "longitude": -97
        },
        "number": {},
        "bank": {},
        "scheme": "visa",
        "type": "credit"
      }
    },
    "dayOfMonth": 6,
    "lastFourDigits": "4242",
    "merchantId": "20000000XXXXXXXX2000",
    "periodicity": "monthly",
    "id": "160202411352100020000000XXXXXXXX2000m",
    "subscriptionId": "1602024113521000",
    "startDate": 1601942400
  }
}

// Suscripción creada exitosamente
{
  "name": "subscriptionApproved",
  "event": {
    "amount": {
      "subtotalIva0": 0,
      "iva": 0.14,
      "subtotalIva": 1,
      "currency": "USD",
      "ice": 0
    },
    "metadata": {
      "plan": {
        "fitness": {
          "rumba": "include",
          "pool": "include",
          "cardio": "include"
        }
      }
    },
    "cardHolderName": "Pruebas",
    "created": 1602024113,
    "plccMetadataId": "187169a42eed456a9964dab5e7ec9468",
    "ip": "35.193.164.95",
    "active": true,
    "planName": "Premium",
    "userAgent": "Go-http-client/1.1",
    "contactDetails": {
      "firstName": "Diego",
      "lastName": "Cadena",
      "phoneNumber": "+593988734644",
      "documentType": "CC",
      "documentNumber": "1009283738",
      "email": "test@test.com"
    },
    "maskedCardNumber": "424242XXXXXX4242",
    "token": "da44953475f74c02abca31c5371e1792",
    "dayOfWeek": "?",
    "month": "*",
    "binInfo": {
      "bank": null,
      "bin": "424242",
      "brand": "VISA",
      "processor": "NA",
      "info": {
        "country": {
          "emoji": "🇺🇸",
          "latitude": 38,
          "alpha2": "US",
          "name": "United States of America",
          "numeric": "840",
          "currency": "USD",
          "longitude": -97
        },
        "number": {},
        "bank": {},
        "scheme": "visa",
        "type": "credit"
      }
    },
    "dayOfMonth": 6,
    "lastFourDigits": "4242",
    "merchantId": "20000000XXXXXXXX2000",
    "merchantCountry": "Mexico",
    "periodicity": "monthly",
    "provider":"kushki",
    "id": "160202411352100020000000XXXXXXXX2000m",
    "subscriptionId": "1602024113521000",
    "startDate": 1601942400
  }
}