Webhooks

PayItFast sends real-time JSON notifications about key events to your registered endpoint. Webhooks allow you to react immediately to user status changes, payment settlements, failures, and more without polling the API.

Webhook Payload Structure

Every webhook delivers a JSON body with the following structure.

{
  "eventId": "EV-231107XXXXX4387",
  "entityId": "OR-240726094358",
  "entityType": "order",
  "orgId": "OG-231207102120",
  "status": "fund_settled",
  "user": {
    "userId": "UX-240625104122",
    "firstName": "string",
    "lastName": "string",
    "country": "string",
    "createdAt": "ISO-8601"
  },
  "order": {
    "orderId": "string",
    "type": "string",
    "fiatTicker": "string",
    "cryptoTicker": "string",
    "fiatAmount": 0,
    "cryptoAmount": 0,
    "walletAddress": "string",
    "paymentType": "string",
    "createdAt": "ISO-8601",
    "customerOrderId": "string",
    "failureCode": "string",
    "failureMessage": "string"
  },
  "partnerContext": {},
  "createdAt": "ISO-8601"
}

User Events

These webhooks fire when a user's account or KYC status changes.

Collections Events

Webhooks for fiat payin (collection) orders.

Payout Events

Webhooks for fiat payout orders.

Gaming Events

Webhooks for fiat payin with wallet (iGaming) orders.

Onramp Events

Webhooks for fiat-to-crypto (onramp) orders.

Offramp Events

Webhooks for crypto-to-fiat (offramp) orders.

Signature Verification

All webhooks are signed with HMAC-SHA256 using a dedicated secret key. You should always verify the signature to ensure the webhook was sent by PayItFast and has not been tampered with.

Verification Steps

1. Generate an HMAC-SHA256 hash using your secret key and the raw request body.
2. Compare the generated hash with the value in the X-PayItFast-Hmac-Hash header.
3. If they match, the webhook is valid. If they do not match, the payload may have been tampered with — discard it.

Node.js Example

const crypto = require('crypto');

const hash = crypto
  .createHmac('sha256', secretKey)
  .update(JSON.stringify(requestBody))
  .digest('hex');

const isValid = hash === request.headers['x-payitfast-hmac-hash'];

Python Example

import hmac, hashlib

hash = hmac.new(
    secret_key.encode(),
    request_body.encode(),
    hashlib.sha256
).hexdigest()

is_valid = hash == request.headers['X-PayItFast-Hmac-Hash']

Retry Mechanics

PayItFast automatically retries failed webhook deliveries to ensure you receive every notification.