Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dollarpe.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks allow you to receive real-time notifications about various events that occur in your integration. When an event happens, we’ll send an HTTP POST request to the webhook URL you’ve configured.
To configure your webhook URL please refer to the Webhook Configuration guide.

​
Webhook Validation

Each webhook request will include the following headers for validation: 
{
  "X-TIMESTAMP": 1752670745,
  "X-SIGNATURE": "ohmVyfuNup6eKWOdOZBBZut5CMPdPTfFSB/zDT/eXQo="
}
  • X-TIMESTAMP: Unix timestamp when the webhook was generated.
  • X-SIGNATURE: HMAC-SHA256 signature, Base64 encoded. You should verify every incoming webhook by validating the signature using your api_key & api_secret. Below is a sample Python code snippet for generating and verifying webhook signatures:
import base64
import hmac
import hashlib
import time
import json
def generate_hmac_signature(api_key, api_secret, timestamp, body={}):
    """Generates HMAC signature"""
    # sort the body
    body = json.dumps(body, sort_keys=True, separators=(",", ":"))
    message = f"{api_key}|{timestamp}|{body}".encode()
    print("mesage to sign", message)
    signature = hmac.new(api_secret.encode(), message, hashlib.sha256).digest()
    return base64.b64encode(signature).decode()
def verify_hmac_signature(api_key, timestamp, signature, body, api_secret):
    """Verify API key and HMAC signature"""
    expected_signature = generate_hmac_signature(api_key, api_secret, timestamp, body)
    print(expected_signature)
    if not hmac.compare_digest(expected_signature, signature): return False
    return True
Usage Example: 
is_valid = verify_hmac_signature(
    api_key="your_api_key",
    api_secret="your_api_secret",
    timestamp=received_timestamp,
    signature=received_signature,
    body=webhook_body_dict,
)
if not is_valid:
    # Reject the webhook
    ...
Always verify the signature and timestamp before processing any webhook data.

​
Webhook Structure

All webhook notifications follow this consistent structure: 
{
  "type": "string",           // The entity type (e.g., "PAYOUT", "PAYIN", "CUSTOMER", "BANK", "EDD")
  "id": "string"              // Unique ID of the entity 
  "event": "string",          // The state change event
  "timestamp": "timestamp",
  "metadata": {
    "failure_reason": "string", // In case of FAILED event,
    .
    .
    .
  }
}

​
Metadata Fields

The metadata object in webhook payloads contains additional context-specific information based on the event type and state. Below are the potential fields that may appear in metadata:

​
Payin Events

  • failure_reason (string): Present when the payin event is FAILED. Contains the specific reason for the failure (e.g., INCORRECT_UTR, PAYMENT_NOT_RECEIVED etc). See Failure Reason Reference for all possible values.
  • refund_reason (string): Present when the payin event is REFUND_INITIATED or REFUNDED. Contains the reason why the refund was initiated. Possible values include: INCORRECT_AMOUNT, PAYMENT_FROM_NON_WHITELISTED_ACCOUNT, THIRD_PARTY_PAYMENT. See Failure Reason Reference for all possible values.

​
Customer Events

  • failure_reason (string): Present when the customer event is FAILED. Contains the specific reason for KYC verification failure (e.g., DOCUMENT_VERIFICATION_FAILED, TAX_VERIFICATION_FAILED, KYC_FAILED). See Failure Reason Reference for all possible values.

​
Bank Events

  • failure_reason (string): Present when the bank event is FAILED. Contains the specific reason for bank verification failure (e.g., ACCOUNT_TYPE_NRE, PENNY_DROP_FAILED, NAME_MISMATCH, BANK_RISK_CHECK_FAILED etc). See Failure Reason Reference for all possible values.
Metadata fields are only included when relevant to the event. For successful events or events without additional context, the metadata object may be empty {}.

​
Webhook Events

​
Customer Events

Customer webhooks are triggered when a customer’s verification status changes. Below are the possible customer states:
EventDescription
VERIFIEDCustomer has completed KYC verification
FAILEDCustomer verification failed or account suspended
Example customer webhook payload:
{
  "type": "CUSTOMER",
  "event": "FAILED",
  "id": "12348400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "failure_reason": "TAX_VERIFICATION_FAILED"
  }
}

​
Bank Events

Bank webhooks are triggered when a customer’s bank account details or UPI ID is verified. Below are the possible states:
EventDescription
VERIFIEDBank Account or UPI ID is verified successfully and can be used to place orders
FAILEDBank Account or UPI ID verification failed and the bank account cannot be used to place orders
Example bank webhook payloads: VERIFIED event: 
{
  "type": "BANK",
  "event": "VERIFIED",
  "id": "12348400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {}
}
FAILED event: 
{
  "type": "BANK",
  "event": "FAILED",
  "id": "12348400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "failure_reason": "BANK_RISK_CHECK_FAILED"
  }
}

​
Payout Events

Payout webhooks are triggered when the status of a payout changes. Below are the possible payout states:
EventDescription
SUCCESSThe payout has been successfully completed
FAILEDThe payout has failed (e.g., AML Screening failed)
REFUNDEDThe payout amount has been reversed
CANCELLEDThe payout has been cancelled
Example payout webhook payload:
{
  "type": "PAYOUT",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "SUCCESS",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "utr": "RATN12341234XYZ"
  }
}

​
Payin Events

Payin webhooks are triggered when the status of a payin changes. Below are the possible payin states:
EventDescription
SUCCESSThe payin has been successfully completed
FAILEDThe payin has failed (e.g., AML Screening failed)
REFUND_INITIATEDThe refund has been initiated for this payin
REFUNDEDThe payin amount has been reversed
ON_HOLDThe payin is put on hold
Example payin webhook payloads: SUCCESS event: 
{
  "type": "PAYIN",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "SUCCESS",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {}
}
FAILED event: 
{
  "type": "PAYIN",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "FAILED",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "failure_reason": "INCORRECT_UTR"
  }
}
REFUND_INITIATED event: 
{
  "type": "PAYIN",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "REFUND_INITIATED",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "refund_reason": "INCORRECT_AMOUNT"
  }
}
REFUNDED event: 
{
  "type": "PAYIN",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "REFUNDED",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "refund_reason": "THIRD_PARTY_PAYMENT"
  }
}

​
EDD Events

EDD webhooks are triggered when a customer’s enhanced due diligence verification status changes. Below are the possible states:
EventDescription
VERIFIEDCustomer’s EDD is verified successfully and customer will now have enhanced onramp limits
FAILEDCustomer’s EDD verification failed. The payin limits will remain unchanged
Example customer webhook payload:
{
  "type": "EDD",
  "event": "VERIFIED",
  "id": "12348400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {}
}