Webhook para dispersión con tarjeta

03 julio 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 envía un pago con tarjeta correctamente (approvedTransaction)
Cuando falla el envío de un pago con tarjeta (declinedTransaction)

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
details.amount.currency	String
details.amount.totalAmount	Number
details.approvalCode	String \| Null (Solo en aprobación)
details.approvedTransactionAmount	Number \| Null (Solo en aprobación)
details.binInfo.bank	String
details.binInfo.bin	String
details.binInfo.brand	String
details.binInfo.brandProductCode	String \| Null
details.binInfo.country	String
details.binInfo.type	String
details.binInfo.prepaid	Boolean
details.created	Number (Timestamp en milisegundos)
details.merchantId	String
details.merchantName	String
details.paymentBrand	String
details.responseCode	String
details.responseText	String
details.transactionId	String
details.transactionReference	String
details.transactionStatus	String (‘APPROVAL’ o ‘DECLINED’)
details.transactionType	String (‘PAYOUT’)
ticketNumber	String \| Null (Solo en aprobación)
transactionReference	String
code	String \| Null (Solo en declinación)
processorCode	String \| Null (Solo en declinación)
processorMessage	String \| Null (Solo en declinación)
message	String \| Null (Solo en declinación)

Ejemplos

JSON
JSON

// Transacción aprobada
{
    "details": {
        "amount": {
            "currency": "PEN",
            "totalAmount": 30
        },
        "approvalCode": "NANANA",
        "approvedTransactionAmount": 30,
        "binInfo": {
            "bank": "CITIBANK (SOUTH DAKOTA), N.A.",
            "bin": "41049201",
            "brand": "VISA",
            "brandProductCode": "",
            "country": "USA",
            "type": "credit",
            "prepaid": false
        },
        "created": 1738087581164,
        "merchantId": "20000000100400157000",
        "merchantName": "ORIZABA PAYOUTS CARD BRANCH",
        "paymentBrand": "VISA",
        "responseCode": "00",
        "responseText": "Approved and completed successfully",
        "transactionId": "951738087581164005",
        "transactionReference": "c9e6c7d4-e8c2-4457-b6a6-bb6d8ac8fad1",
        "transactionStatus": "APPROVAL",
        "transactionType": "PAYOUT"
    },
    "ticketNumber": "951738087581164005",
    "transactionReference": "c9e6c7d4-e8c2-4457-b6a6-bb6d8ac8fad1"
}

// Transacción rechazada
{
    "code": "E557",
    "details": {
        "amount": {
            "currency": "PEN",
            "totalAmount": 30
        },
        "binInfo": {
            "bank": "bank",
            "bin": "495703",
            "brand": "VISA",
            "brandProductCode": "",
            "country": "USA",
            "type": "credit",
            "prepaid": false
        },
        "created": 1738085144614,
        "merchantId": "20000000100400157000",
        "merchantName": "ORIZABA PAYOUTS CARD BRANCH",
        "paymentBrand": "VISA",
        "processorCode": "557",
        "processorMessage": "El emisor no puede autorizar esta transacción",
        "responseCode": "57",
        "responseText": "Transaction not permitted to cardholder",
        "transactionId": "951738085144614309",
        "transactionReference": "9a4e8794-c30e-4ed7-bd45-53943fb01550",
        "transactionStatus": "DECLINED",
        "transactionType": "PAYOUT"
    },
    "message": "El emisor no puede autorizar esta transacción"
}