Bank Webhook - Sample Responses

This page provides sample webhook payloads for each bank verification status. The same payloads are sent for both On-Ramp and Off-Ramp users.

Each request is a POST to your configured bank webhook URL with the X-Onmeta-Signature header. See Webhook - Bank for how to verify it.

Status	message
SUCCESS	account successfully added
PENDING	account verification pending
FAILED	account/pan name mismatch. ACCOUNT HOLDER NAME: <name>
MANUAL	pending for manual verification

SUCCESS

This event is triggered when the bank account has been verified and added to the user's account.

{
  "name": "Ravi Kumar",
  "email": "ravi@example.com",
  "bankDetails": {
    "accountNumber": "123456789012",
    "accountName": "RAVI KUMAR",
    "ifsc": "HDFC0001234",
    "branchAddress": "MG Road, Bengaluru",
    "referenceNumber": "a1b2c3d4-1234-5678-abcd-ef1234567890",
    "tenantId": "65ef27a598b805cba22fb3b5",
    "status": "SUCCESS"
  },
  "message": "account successfully added",
  "reason": "account successfully added"
}

PENDING

This event is triggered when the bank account verification is still in progress.

{
  "name": "Ravi Kumar",
  "email": "ravi@example.com",
  "bankDetails": {
    "accountNumber": "123456789012",
    "ifsc": "HDFC0001234",
    "referenceNumber": "a1b2c3d4-1234-5678-abcd-ef1234567890",
    "tenantId": "65ef27a598b805cba22fb3b5",
    "status": "PENDING"
  },
  "message": "account verification pending",
  "reason": "failed to verify account, please retry after some time"
}

FAILED

This event is triggered when the account holder name does not match the user's KYC name. The message ends with the account holder name returned by the bank.

{
  "name": "Ravi Kumar",
  "email": "ravi@example.com",
  "bankDetails": {
    "accountNumber": "123456789012",
    "accountName": "SURESH SHARMA",
    "ifsc": "HDFC0001234",
    "branchAddress": "MG Road, Bengaluru",
    "referenceNumber": "a1b2c3d4-1234-5678-abcd-ef1234567890",
    "tenantId": "65ef27a598b805cba22fb3b5",
    "status": "FAILED"
  },
  "message": "account/pan name mismatch. ACCOUNT HOLDER NAME: SURESH SHARMA",
  "reason": "kyc name mismatch. ACCOUNT HOLDER NAME: SURESH SHARMA, kycNames: RAVI KUMAR"
}

MANUAL

This event is triggered when the account holder name could not be matched automatically with the user's KYC name and the account has been sent to Onmeta for manual review.

{
  "name": "Ravi Kumar",
  "email": "ravi@example.com",
  "bankDetails": {
    "accountNumber": "123456789012",
    "accountName": "RAVI K",
    "ifsc": "HDFC0001234",
    "branchAddress": "MG Road, Bengaluru",
    "referenceNumber": "a1b2c3d4-1234-5678-abcd-ef1234567890",
    "tenantId": "65ef27a598b805cba22fb3b5",
    "status": "MANUAL"
  },
  "message": "pending for manual verification",
  "reason": "kyc name mismatch. ACCOUNT HOLDER NAME: RAVI K, kycNames: RAVI KUMAR"
}

Field Notes

• reason is always present. It depends on the status:
  • SUCCESS: account successfully added.
  • PENDING: the verification provider's message when there is one, otherwise account verification pending.
  • FAILED and MANUAL: kyc name mismatch. ACCOUNT HOLDER NAME: <name>, kycNames: <names>. kycNames lists the user's KYC names (comma-separated) that the account holder name was compared against.
• Fields inside bankDetails other than status are left out when they have no value. For example, accountName and branchAddress can be missing while verification is PENDING.
• The FAILED message includes the account holder name, so do not match on the full message text. Use bankDetails.status.
• The same status can be delivered more than once for a bank account. Key on bankDetails.referenceNumber and bankDetails.status so repeated events are harmless.