Webhooks
Overview
POST requests with a Content-Type: application/json header delivered to your configured endpoint URL.Payload Conventions
| Convention | Detail |
|---|---|
| Format | JSON |
| HTTP Method | POST |
| Content-Type | application/json |
| Null fields | Included as null (not omitted) |
| Timestamps | ISO 8601 — YYYY-MM-DDTHH:mm:ssZ |
| Amounts | Decimal string or number in the currency's minor/major unit as configured |
Event Categories
| Category | Events |
|---|---|
| Transaction | consume, refund, reversal, maintain_fee, settlement |
| Card Holder Application | cardholder.reviewing, cardholder.approved, cardholder.rejected |
| Card Action | card.freeze, card.unfreeze, card.cancel, card.activate, card.set_pin |
| Card Status | card.approved, card.rejected, card.under_review |
1. Transaction Events
consume · refund · reversal · maintain_fee · settlementPayload
{
"event": "consume",
"transaction_id": "txn_001abc",
"card_id": "card_001abc",
"customer_id": "cust_001abc",
"original_transaction_id": "txn_000xyz",
"local_currency": "INR",
"local_amount": "1500.00",
"authorized_amount": "18.25",
"authorized_currency": "USD",
"authorization_code": "AUTH123",
"authorized_at": "2025-06-01T10:30:00Z",
"fee": "0.50",
"fee_currency": "USD",
"crossborder_fee": "0.25",
"crossborder_fee_currency": "USD",
"settle_amount": "18.00",
"settle_currency": "USD",
"settle_date": "2025-06-02T00:00:00Z",
"merchant_name": "Amazon IN",
"merchant_category_code": "5411",
"merchant_country": "IN",
"merchant_city": "Mumbai",
"type": "consume",
"sub_type": "consume",
"status": "approved",
"description": "Grocery purchase"
}Field Reference
| Field | Type | Description |
|---|---|---|
event | string | Event type. One of consume, refund, reversal, maintain_fee, settlement |
transaction_id | string | Unique identifier of this transaction |
card_id | string | Card on which the transaction occurred |
customer_id | string | Customer who owns the card |
original_transaction_id | string | Reference to the original/parent transaction (relevant for refund, reversal) |
local_currency | string | ISO 4217 currency code of the transaction at the point of sale |
local_amount | string | Amount in the local currency |
authorized_amount | string | Amount authorized in the card's billing currency |
authorized_currency | string | ISO 4217 code of the card's billing/wallet currency |
authorization_code | string | Authorization code returned by the network |
authorized_at | string | ISO 8601 timestamp when authorization was issued |
fee | string | Platform or card fee applied |
fee_currency | string | Currency of the fee |
crossborder_fee | string | Cross-border/FX conversion fee, if applicable |
crossborder_fee_currency | string | Currency of the cross-border fee |
settle_amount | string | Pre-settlement amount |
settle_currency | string | Currency of the settlement amount |
settle_date | string | ISO 8601 expected or actual settlement date |
merchant_name | string | Name of the merchant |
merchant_category_code | string | ISO 18245 MCC code |
merchant_country | string | ISO 3166-1 alpha-2 merchant country code |
merchant_city | string | City where the merchant is located |
type | string | Transaction type (mirrors the event) |
sub_type | string | Transaction sub-type for further classification |
status | string | Final status of the transaction (e.g., approved, declined, pending) |
description | string | Human-readable remarks or transaction description |
2. Card Holder Application Events
cardholder.reviewing · cardholder.approved · cardholder.rejectedPayload
{
"event": "cardholder.approved",
"customer_id": "cust_001abc",
"product_id": "prod_001abc",
"first_name": "Ravi",
"last_name": "Kumar",
"email": "ravi.kumar@example.com",
"application_status": "approved",
"application_reason": "All checks passed"
}Field Reference
| Field | Type | Description |
|---|---|---|
event | string | Event type. One of cardholder.reviewing, cardholder.approved, cardholder.rejected |
customer_id | string | Unique identifier of the customer |
product_id | string | Card product associated with the application |
first_name | string | Applicant's first name |
last_name | string | Applicant's last name |
email | string | Applicant's email address |
application_status | string | Current status of the application (reviewing, approved, rejected) |
application_reason | string | Human-readable reason or message accompanying the status decision |
3. Card Action Events
card.freeze · card.unfreeze · card.cancel · card.activate · card.set_pintask_id to allow idempotent tracking of async operations.Payload
{
"event": "card.freeze",
"task_id": "task_001abc",
"customer_id": "cust_001abc",
"product_id": "prod_001abc",
"card_id": "card_001abc",
"card_type": "virtual",
"action": "freeze",
"status": "success",
"message": "Card has been frozen successfully"
}Field Reference
| Field | Type | Description |
|---|---|---|
event | string | Event type. One of card.freeze, card.unfreeze, card.cancel, card.activate, card.set_pin |
task_id | string | Unique identifier for the async task/operation |
customer_id | string | Unique identifier of the customer |
product_id | string | Card product identifier |
card_id | string | Unique identifier of the card |
card_type | string | Card type — virtual or physical |
action | string | The action performed (e.g., freeze, unfreeze, cancel, activate, set_pin) |
status | string | Result of the action (e.g., success, failed, pending) |
message | string | Human-readable outcome message |
4. Card Status Events
card.approved · card.rejected · card.under_reviewPayload
{
"event": "card.approved",
"customer_id": "cust_001abc",
"product_id": "prod_001abc",
"card_id": "card_001abc",
"card_type": "physical",
"status": "approved",
"message": "Card has been approved and is ready for use"
}Field Reference
| Field | Type | Description |
|---|---|---|
event | string | Event type. One of card.approved, card.rejected, card.under_review |
customer_id | string | Unique identifier of the customer |
product_id | string | Card product identifier |
card_id | string | Unique identifier of the card |
card_type | string | Card type — virtual or physical |
status | string | Issuance status (approved, rejected, under_review) |
message | string | Human-readable status message or reason |
Status Values Quick Reference
Transaction Status
| Value | Description |
|---|---|
approved | Transaction was authorized and approved |
declined | Transaction was declined by the network or issuer |
pending | Transaction is pending settlement |
reversed | Transaction has been reversed |
settled | Transaction has been fully settled |
Card Holder Application Status
| Value | Description |
|---|---|
reviewing | Application is under review |
approved | Application has been approved |
rejected | Application has been rejected |
Card Action & Card Status
| Value | Description |
|---|---|
success | Action completed successfully |
failed | Action failed |
pending | Action is being processed asynchronously |
approved | Card issuance approved |
rejected | Card issuance rejected |
under_review | Card issuance under review |
Error Handling
2xx status code to acknowledge receipt. If a non-2xx response is returned or the request times out, the platform may retry delivery with exponential backoff.| Scenario | Recommendation |
|---|---|
| Duplicate events | Use transaction_id, task_id, or card_id + event for idempotency |
| Unknown event type | Acknowledge (200 OK) and ignore gracefully |
| Processing failure | Return 500 to trigger retry |
Modified at 2026-02-18 10:05:31