Webhooks

Webhooks allow you to subscribe to events that may occur, such as a transaction being approved or declined. When an event is triggered, we notify you through an endpoint that you have previously configured, sending a POST request with a JSON object containing all the necessary information about the event.

Using webhooks, your application can listen for important events and trigger actions, such as updating the database when a payment is successfully processed within your system.

INFO

Webhooks are asynchronous. Notifications are usually sent immediately, but occasional delays can occur. Design your integration to handle delayed or out-of-order delivery.

Endpoint requirements

Before configuring an endpoint to receive notifications, it must meet the following requirements:

Accept HTTP POST requests

Have a valid SSL certificate (HTTPS) and public access

Respond with HTTP 200 (OK) within 2 seconds

Accept payloads in JSON format

Have a URL no longer than 300 characters

Event types

Event	Description
Approved transactions	Fired when a card payment is approved.
Rejected transactions	Fired when a card payment is declined.
Refunds	Fired when a refund is approved, rejected or left pending.
Transfer funds to your bank account	SPEI settlement notification for funds transferred to your bank account.

Depending on the type of event that triggers a notification, you receive an object with a certain structure in the payload.

To ensure that the requests you receive on your endpoint come from us, use the X-BP-Signature and X-BP-SignatureKey headers to authenticate the incoming request. See Security for details.

Register your endpoint

Navigate to Configuración > Integraciones.

Enter your endpoint URL in the Webhook General section.

Select the type of events you want to subscribe to.

Click Guardar.

Note

The endpoint must respond with an HTTP Status Code 200 for it to be saved successfully. Changes may take a few minutes to take effect.

Security

A digital signature is provided with every POST notification. Signature values are accessible through the request headers:

Header	Description
`X-BP-Signature`	Base64-encoded value of the signature for the delivered payload.
`X-BP-SignatureKey`	Key index of the private key used to sign the message.

To get a hold of the public key for signature verification, append the key index to the following URL, using the .pem or .der extension depending on the preferred format for your application:

https://keys.billpocket.com/webhook/

Example — for key index k1:

PEM: https://keys.billpocket.com/webhook/k1.pem

DER: https://keys.billpocket.com/webhook/k1.der

INFO

We encourage you to cache or otherwise store the public key contents on your side to speed up the signature verification process on successive notifications. Keys won't change over time, but the key index may be updated to use a new pair of keys.

Code examples

Below are code examples on how to receive event notifications through webhooks.

Java

PHP

Node.js

Assuming you're using Spring Boot, get the signature and signature key values to perform verification on the received payload:

The previous code has the following dependencies:

<dependency>
  <groupId>commons-io</groupId>
  <artifactId>commons-io</artifactId>
  <version>2.6</version>
</dependency>

<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcprov-jdk15on</artifactId>
  <version>1.54</version>
</dependency>

Approved transactions

Configure webhook

Set your webhook URL in the Webhook General section and select the Transacciones Aprobadas option under the Ventas tab. Click Guardar to save your changes.

Note

Changes may take a few minutes to take effect. The webhook URL must be no longer than 300 characters.

Payload fields

Below are all the properties that can be contained in the payload of an approved transaction event.

Property	Type	Description
`result`	String	Transaction result. Possible values: `aprobada` for approved transactions.
`amount`	String	Transaction amount.
`tip`	String	If the transaction includes a tip, it is returned.
`payments`	Integer	If the transaction has been deferred, the number of deferred installments. For example, `3`.
`authorizationTime`	String	Authorization time. RFC 3339 date format.
`reference`	String	Transaction description.
`transactionid`	String	Transaction ID generated by Kushki.
`authorization`	String	Transaction authorization string.
`creditcard`	String	Last 4 digits of the card's Primary Account Number.
`cardtype`	String	Card issuer. Possible values: `VISA`, `MASTERCARD`, `CARNET`, `AMERICAN EXPRESS`.
`arqc`	String	EMV only. Authorization Request Cryptogram (ARQC) of the transaction.
`userID`	Integer	ID of the user who made the transaction.
`aid`	String	EMV only. Chip's Application ID.
`applabel`	String	EMV only. Chip's Application Label.
`url`	String	Unique identifier to access a transaction ticket.
`email`	String	Email to which the transaction ticket is sent.
`phone`	String	Phone number to which the transaction ticket is sent.
`cardBrand`	String	Card Issuer Network.
`cardIssuer`	String	Card Issuer Bank.
`cardCountry`	String	Card Country Code (ISO 3166-1 alpha-2).
`cardClass`	String	`DEBIT` or `CREDIT` card.
`launchTime`	String	Time the transaction was sent.
`maskedPAN`	String	Masked card number.
`uniqueReference`	String	Unique identifier per transaction generated on the client side to avoid duplicates. For example, a UUID.

Example

{
    "cardBrand": "MASTERCARD",
    "cardIssuer": "SANTANDER",
    "cardCountry": "MX",
    "cardClass": "CREDIT",
    "launchTime": "2024-05-29T11:01:27.360-0600",
    "userID": 61000,
    "authorizationTime": "2024-05-29T11:01:27.360-0600",
    "result": "aprobada",
    "amount": "100.00",
    "payments": 0,
    "transactionid": "128010",
    "authorization": "BP3500",
    "creditcard": "0009",
    "cardtype": "MASTERCARD",
    "arqc": "A38051D19B2548E3",
    "aid": "A0000000041010",
    "applabel": "Mastercard",
    "url": "face3142cb4d32a545f42d278b8cf4ce5ea3d0b1",
    "maskedPAN": "500000******0009",
    "uniqueReference": "d6732f94-6cf2-4dfb-aed7-11b64b739407"
}

Rejected transactions

Configure webhook

Set your webhook URL in the Webhook General section and select the Transacciones Rechazadas option under the Ventas tab. Click Guardar to save your changes.

Note

Changes may take a few minutes to take effect.

Payload fields

Below are all the properties that can be contained in the event payload of a rejected transaction.

Property	Type	Description
`result`	String	Transaction result. Possible values: `rechazadaProsa` for rejected transactions.
`amount`	String	Transaction amount.
`tip`	String	If the transaction includes a tip, it is returned.
`payments`	Integer	If the transaction has been deferred, the number of deferred installments. For example, `3`.
`authorizationTime`	String	Authorization time. RFC 3339 date format.
`reference`	String	Transaction description.
`transactionid`	String	Transaction ID generated by Kushki.
`creditcard`	String	Last 4 digits of the card's Primary Account Number.
`cardtype`	String	Card issuer. Possible values: `VISA`, `MASTERCARD`, `CARNET`, `AMERICAN EXPRESS`.
`arqc`	String	EMV only. Authorization Request Cryptogram (ARQC) of the transaction.
`userID`	Integer	ID of the user who made the transaction.
`aid`	String	EMV only. Chip's Application ID.
`applabel`	String	EMV only. Chip's Application Label.
`cardBrand`	String	Card Issuer Network.
`cardIssuer`	String	Card Issuer Bank.
`cardCountry`	String	Card Country Code (ISO 3166-1 alpha-2).
`cardClass`	String	`DEBIT` or `CREDIT` card.
`launchTime`	String	Time the transaction was sent.
`maskedPAN`	String	Masked card number.
`uniqueReference`	String	Unique identifier per transaction generated on the client side to avoid duplicates. For example, a UUID.

Note

Unlike approved transactions, rejections do not return authorization, url, email or phone.

Example

{
    "cardBrand": "MASTERCARD",
    "cardIssuer": "SANTANDER",
    "cardCountry": "MX",
    "cardClass": "CREDIT",
    "launchTime": "2024-05-29T10:46:52.221-0600",
    "userID": 61000,
    "authorizationTime": "2024-05-29T10:46:52.221-0600",
    "result": "rechazadaProsa",
    "amount": "99.00",
    "payments": 0,
    "transactionid": "128011",
    "creditcard": "0009",
    "cardtype": "MASTERCARD",
    "arqc": "6FEC34124C9AAEEB",
    "aid": "A0000000041010",
    "applabel": "Mastercard",
    "maskedPAN": "500000******0009",
    "uniqueReference": "d6732f94-6cf2-4dfb-aed7-11b64b739407"
}

Refunds

Configure webhook

Set your webhook URL in the Webhook General section and select the Transacciones Aprobadas and/or Transacciones Rechazadas option in the Devoluciones tab. Click Guardar to save your changes.

Note

Changes may take a few minutes to take effect.

Payload fields

Below are all the properties that can be contained in the payload of an approved or rejected refund event.

Property	Type	Description
`result`	String	Transaction result. Possible values: `aprobada` for approved refunds; `rechazadaRiesgo`, `rechazadaProsa` or `rechazada` for rejected refunds; `pendiente` for pending refunds.
`amount`	String	Refund amount.
`payments`	Integer	If the transaction has been deferred, the number of deferred installments. For example, `3`.
`authorizationTime`	String	Authorization time. RFC 3339 date format.
`transactionid`	String	Transaction ID generated by Kushki.
`authorization`	String	Transaction authorization string. Approved refunds only.
`creditcard`	String	Last 4 digits of the card's Primary Account Number.
`cardtype`	String	Card issuer. Possible values: `VISA`, `MASTERCARD`, `CARNET`, `AMERICAN EXPRESS`.
`userID`	Integer	ID of the user who made the transaction.
`url`	String	Unique identifier to access a transaction ticket. Approved refunds only.
`cardBrand`	String	Card Issuer Network.
`cardCountry`	String	Card Country Code (ISO 3166-1 alpha-2).
`cardClass`	String	`DEBIT` or `CREDIT` card.
`launchTime`	String	Time the request was sent.
`maskedPAN`	String	Masked card number.
`uniqueReference`	String	Unique identifier per transaction generated on the client side to avoid duplicates. For example, a UUID.
`transactionType`	String	Transaction type. Possible values: `devolucion` for refunds.
`transactionRefundedId`	String	Original refunded transaction ID.

Approved refund example

{
    "cardBrand": "VISA",
    "cardCountry": "US",
    "cardClass": "CREDIT",
    "uniqueReference": "d6732f94-6cf2-4dfb-aed7-11b64b739407",
    "launchTime": "2024-08-16T10:02:37.965-0600",
    "userID": 61000,
    "authorizationTime": "2024-08-16T10:02:37.965-0600",
    "result": "aprobada",
    "amount": "1018.0",
    "payments": 0,
    "transactionid": "128013",
    "authorization": "BP4160",
    "creditcard": "0002",
    "cardtype": "VISA",
    "url": "19c6f19bc1a7a00a1d76021aa5eaef2627aba950",
    "maskedPAN": "400000******0002",
    "transactionType": "devolucion",
    "transactionRefundedId": "128012"
}

Rejected refund example

{
    "cardBrand": "VISA",
    "cardCountry": "US",
    "cardClass": "CREDIT",
    "launchTime": "2024-08-15T16:22:52.461-0600",
    "userID": 61000,
    "authorizationTime": "2024-08-15T16:22:52.461-0600",
    "result": "rechazadaProsa",
    "amount": "1003.0",
    "payments": 0,
    "transactionid": "128015",
    "creditcard": "0002",
    "cardtype": "VISA",
    "maskedPAN": "400000******0002",
    "transactionType": "devolucion",
    "transactionRefundedId": "128014"
}

Got a suggestion on this documentation? Contact us.

Endpoint requirements#

Event types#

Register your endpoint#

Security#

Code examples#

Approved transactions#

Configure webhook#

Payload fields#

Example#

Rejected transactions#

Configure webhook#

Payload fields#

Example#

Refunds#

Configure webhook#

Payload fields#

Approved refund example#

Rejected refund example#

Endpoint requirements

Event types

Register your endpoint

Security

Code examples

Approved transactions

Configure webhook

Payload fields

Example

Rejected transactions

Configure webhook

Payload fields

Example

Refunds

Configure webhook

Payload fields

Approved refund example

Rejected refund example