Webhook events

Webhooks are an important part of your payment integration. They allow Palremit notify you about events that happen on your account, such as a successful payment or a failed transaction.

Webhook authentication

We've implemented measures to enhance the security of webhook communications, ensuring that you can reliably verify the origin of a webhook event to confirm it originated from us rather than from a potentially malicious source.

Below are the steps you need to follow to verify that a webhook event came from Palremit.

Step 1: Retrieve your API secret key from your dashboard. The key is represented by either "live_secret_key" or "test_secret_key" within the brackets, depending on the environment. Generate a SHA-256 hash using this key.

Step 2: When you receive a webhook event from Palremit, fetch the X-Webhook-Signature header. Then, create a signature on your end by hashing the webhook payload with your secret key using the SHA-256 algorithm.

Note: Remember to hash your secret key using the SHA-256 hashing algorithm before generating the signature.

Step 3: Compare the signature you generated on your end with the signature retrieved from the webhook headers. If the signatures match, the webhook is from us; otherwise, ignore it.

In Node.js, you can accomplish this using the crypto module.

To Generate SHA256:

js
export function generateSHA256(secret: string): string {
  const hash = crypto.createHash('sha256');
  hash.update(secret);
  return hash.digest('hex');
}

To Generate the Signature:

js
const crypto = require('crypto');

function generateSignature(payload, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(JSON.stringify(payload));
  return hmac.digest('hex');
}

To Compare the Signature:

js
function verifySignature(payload, receivedSignature, secret_hash) {
  const expectedSignature = generateSignature(payload, secret_hash);
  return crypto.timingSafeEqual(Buffer.from(receivedSignature), Buffer.from(expectedSignature));
}

All webhook events

These are the list of webhook events triggered when you communicate with our APIs.

cardholder_verification.successful

This webhook event is sent when a user has passed the ID verification process.

{
    "event": "cardholder_verification.successful",
    "data" : {
        "cardholder_id": "859505050505",
        "cardholder_email": "jeremy@palremit.com",
        "is_active": true, 
        "livemode": false, 
        "issuing_app_id": "9ujinoncpsni3943198393939930ke"
    }
}

cardholder_verification.failed

This webhook event is sent when a user has failed the ID verification process

{
    "event": "cardholder_verification.failed",
    "data" : {
        "cardholder_id": "859505050505",
        "cardholder_email": "jeremy@palremit.com",
        "is_active": true, 
        "livemode": false, 
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "error_description": "the user passed an invalid ID number"
    }
}

card_creation_event.successful

We send this webhook event when a card is successfully created

{
    "event": "card_creation_event.successful",
    "data" : {
        "card_id": "123505050674",
        "cardholder_id": "123505050674",
        "cardholder_email": "jeremy@palremit.com",
        "currency": "USD",
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "livemode": True
    }
}

card_creation_event.failed

This webhook event is sent when we can't complete your request to create a card.

{
    "event": "card_creation_event.failed",
    "data" : {
        "card_id": "123505050674",
        "cardholder_id": "123505050674",
        "cardholder_email": "jeremy@palremit.com",
        "currency": "USD",
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "livemode": True,
        "reason": "The user failed our second stage KYC verification for fraud detection, please contact admin."
    }
}

card_credit_event.successful

We send this webhook event when a successful credit transaction happens on a card.

{
    "event": "card_credit_event.successful",
    "data" : {
        "card_id": "123505050674",
        "cardholder_id": "123505050674",
        "cardholder_email": "jeremy@palremit.com",
        "amount": "100",
        "currency": "USD",
        "transaction_reference":"123505050674",
        "livemode": false, 
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "card_transaction_type": "CREDIT",
        "transaction_date": "2022-09-28 23:10:45",
        "transaction_timestamp": "1664406645"
    }
}

card_credit_event.failed

We send this webhook event when a card funding transaction fails on a card.

{
    "event": "card_credit_event.failed",
    "data" : {
        "card_id": "123505050674",
        "cardholder_id": "123505050674",
        "cardholder_email": "jeremy@palremit.com",
        "amount": "100",
        "currency": "USD",
        "transaction_reference":"859505050505",
        "livemode": false, 
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "card_transaction_type": "CREDIT",
        "transaction_date": "2022-09-28 23:10:45",
        "transaction_timestamp": "1664406645"
    }
}

card_debit_event.successful

You get this webhook event when a debit transaction happens on a card.

{
    "event": "card_debit_event.successful",
    "data" : {
        "card_id": "123505050674",
        "cardholder_id": "123505050674",
        "cardholder_email": "jeremy@palremit.com",
        "amount": "100",
        "description": "Amazon US",
        "currency": "USD",
        "transaction_reference":"456505050505",
        "livemode": false, 
        "issuing_app_id": "9ujinoncpsni6783198393939930ke",
        "card_transaction_type": "DEBIT",
        "merchant_category_code": "12345 can be None",
        "transaction_date": "2022-09-28 23:10:45",
        "transaction_timestamp": "1664406645"
    }
}

card_debit_event.declined

We send this webhook event whenever there's a declined transaction on the user's card.

{
   
   'event': 'card_debit_event.declined', 
   'data': {
       'card_id': '9aaCfssfee443rffd1cb5e', 
       'cardholder_id': 'fbgg8eedfssfee123rffd1cb9b',
       "cardholder_email": "jeremy@palremit.com",
       'currency': 'USD', 
       'amount': '224',
       'description': 'ALIEXPRESS', 
       'transaction_date': '2021-11-15 17:13:19', 
       'transaction_timestamp': '1636996399',
       'transaction_reference': '123505050595',
       'livemode': True, 
       'issuing_app_id': 'b4524f3c-3408-5686-7806-b20da7f4d6b8', 
       'decline_reason': 'Insufficient balance for transaction amount',
       'transaction_date': '2022-09-28 23:10:45',
       'transaction_timestamp': '1664406645'

    }

}

card_unload_event.successful

You get this webhook event when an unload transaction is successful on a USD card.

{
    "event": "card_unload_event.successful",
    "data" : {
        "card_id": "859505050505",
        "cardholder_id": "859505050505",
        "cardholder_email": "jeremy@palremit.com",
        "amount": "100",
        "description": "Visa Virtual dollar card unloading",
        "currency": "USD",
        "transaction_reference":"859505050505",
        "livemode": false, 
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "card_transaction_type": "DEBIT",
        "transaction_date": "2022-09-28 23:10:45",
        "transaction_timestamp": "1664406645"
    }
}

card_unload_event.failed

You get this webhook event when an unload transaction on a USD card fails.

{
    "event": "card_unload_event.failed",
    "data" : {
        "card_id": "859505050505",
        "cardholder_id": "859505050505",
        "cardholder_email": "jeremy@palremit.com",
        "amount": "100",
        "description": "Visa Virtual dollar card unloading",
        "currency": "USD",
        "transaction_reference":"859505050505",
        "livemode": false, 
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "card_transaction_type": "DEBIT",
        "transaction_date": "2022-09-28 23:10:45",
        "transaction_timestamp": "1664406645"
    }
}

card_reversal_event.successful

This webhook event is triggered whenever a user's USD card gets a reversal from a merchant that they previously got debited from.

{
  "event": "card_reversal_event.successful",
  "data": {
    "card_id": "a303fb8b7a0e476fbc910671ca952b74",
    "cardholder_id": "9b78a44ccdf848fd860f75fd5c117d9d",
    "cardholder_email": "jeremy@palremit.com",
    "amount": "100",
    "currency": "USD",
    "transaction_reference": "22597F3D-A7A5-4C9B-B9DF-B7D918EE8241_REVERSAL",
    "transaction_date": "2022-09-28 23:10:45",
    "transaction_timestamp": "1664406645",
    "livemode": true,
    "issuing_app_id": "c6424f3c-1708-4386-9406-b20da7f4d6b9",
    "card_transaction_type": "CREDIT"
  }
}

PreviousIntroductionNextAvailable Currencies

Last updated