Webhook para pagos recurrentes con tarjeta

30 diciembre 2024

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
`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`

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

// 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
  }
}