Webhooks

Webhooks notify your application when events occur — a transaction is approved or declined, a refund is processed, or a SPEI fund transfer completes. Billpocket sends a POST request to your configured endpoint with a JSON payload containing the full event details.

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

Your webhook endpoint must:

Accept HTTP POST requests

Have a valid SSL certificate (HTTPS)

Respond with HTTP 200 within 2 seconds

Accept JSON payloads

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 or rejected
Transfer funds to your bank account	Daily SPEI settlement notification sent at 01:00 AM CDMX (UTC-6)

Register your endpoint

Navigate to Configuración > Integraciones.

Enter your endpoint URL in the Webhook General section.

Select the event types you want to subscribe to.

Click Guardar.

INFO

The endpoint must respond with HTTP 200 on registration to be saved successfully. Changes may take a few minutes to take effect.

Security — signature verification

Every webhook POST includes two headers to verify the request origin:

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

Retrieve the matching public key by appending the key index to:

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

Cache the public key on your side to speed up verification. Keys don't change over time, but the key index may be updated to use a new pair.

Verification examples

Java

PHP

Node.js

Approved transactions

Configure

In the dashboard: Configuración > Integraciones → set your webhook URL in Webhook General and enable Transacciones Aprobadas.

Payload fields

Field	Type	Description
`result`	string	`"aprobada"`
`amount`	string	Transaction amount
`tip`	string	Tip amount (if applicable)
`payments`	integer	Number of MSI installments (`0` = one-time)
`authorizationTime`	string	Authorization timestamp (RFC 3339)
`reference`	string	Transaction description
`transactionid`	string	Kushki-generated transaction ID
`authorization`	string	Authorization string
`creditcard`	string	Last 4 digits of the PAN
`cardtype`	string	`VISA`, `MASTERCARD`, `CARNET`, `AMERICAN EXPRESS`
`arqc`	string	EMV Authorization Request Cryptogram
`userID`	integer	ID of the user who made the transaction
`aid`	string	EMV Chip Application ID
`applabel`	string	EMV Chip Application Label
`url`	string	Unique identifier to access the transaction ticket
`email`	string	Email the ticket was sent to
`phone`	string	Phone the ticket was sent to
`cardBrand`	string	Card network
`cardIssuer`	string	Issuing bank
`cardCountry`	string	Card country code (ISO 3166-1 alpha-2)
`cardClass`	string	`DEBIT` or `CREDIT`
`launchTime`	string	Timestamp the transaction was sent
`maskedPAN`	string	Masked card number
`uniqueReference`	string	Client-generated unique identifier (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

In the dashboard: Configuración > Integraciones → enable Transacciones Rechazadas in the Webhook General section.

Payload fields

Same fields as approved transactions, with result: "rechazadaProsa". Fields authorization, url, email, and phone are not returned on rejections.

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

In the dashboard: Configuración > Integraciones → enable Transacciones Aprobadas and/or Transacciones Rechazadas under the Devoluciones tab.

Payload fields

Field	Type	Description
`result`	string	`"aprobada"`, `"rechazadaRiesgo"`, `"rechazadaProsa"`, `"rechazada"`, or `"pendiente"`
`transactionType`	string	`"devolución"`
`transactionRefundedId`	string	Original transaction ID that was refunded
`amount`	string	Refund amount
`transactionid`	string	Refund transaction ID
`authorization`	string	Authorization string (approved only)
`creditcard`	string	Last 4 digits of the PAN
`cardtype`	string	Card network
`cardBrand`	string	Card Issuer Network
`cardCountry`	string	Card country code (ISO 3166-1 alpha-2)
`cardClass`	string	`DEBIT` or `CREDIT`
`userID`	integer	User ID
`url`	string	Transaction ticket identifier (approved only)
`maskedPAN`	string	Masked card number
`uniqueReference`	string	Client-generated unique identifier

Examples

Approved refund:

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

Got a suggestion on this documentation? Contact us.

Endpoint requirements#

Event types#

Register your endpoint#

Security — signature verification#

Verification examples#

Approved transactions#

Configure#

Payload fields#

Example#

Rejected transactions#

Configure#

Payload fields#

Example#

Refunds#

Configure#

Payload fields#

Examples#

Endpoint requirements

Event types

Register your endpoint

Security — signature verification

Verification examples

Approved transactions

Configure

Payload fields

Example

Rejected transactions

Configure

Payload fields

Example

Refunds

Configure

Payload fields

Examples