Webhooks

Overview

This document describes all outgoing webhook event payloads sent by the platform. Webhooks are HTTP 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`
Card TopUp	`topup.completed`, `topup.failed`

1. Transaction Events

Applicable event types: consume · refund · reversal · maintain_fee · settlement

These events are fired whenever a transaction lifecycle action occurs on a card.

Payload

{
  "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

Applicable event types: cardholder.reviewing · cardholder.approved · cardholder.rejected

These events track the lifecycle of a card holder's application from submission through final decision.

Payload

{
  "id": "evt_53260e2994bd4d72901036cf21333441",
  "type": "cardholder.approved",
  "createdAt": "2026-04-02T14:26:37.8721433Z",
  "data": {
    "customer_id": "f51b8db9-0bbf-4a91-b5fe-bf9d7b16f070",
    "first_name": "tarun",
    "last_name": "kumar",
    "email": "tarunkumar@yopmail.com",
    "application_status": "cardholder.approved",
    "application_reason": "Approved"
  }
}

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 Topup Events

Applicable event types: card.topup.completed · card.topup.failed

These events track the lifecycle of a card topup transaction from submission through final decision.

Payload

{
  "id": "evt_cdb5d44b89da4e2e84d0e981b3af5b18",
  "type": "card.topup.completed",
  "createdAt": "2026-04-01T13:27:35.2392299Z",
  "data": {
    "card_id": "b6aa7a4c-ac4f-43ca-9030-9c6936f7913c",
    "amount": 50,
    "currency": "USDT",
    "status": "Pending",
    "transaction_id": "41ac2f77-e2ad-4fac-b4c6-0d54a8bc3e2f",
    "performed_at": "2026-04-01T13:27:35.2278182Z"
  }
}

Field	Type	Description
`event`	`string`	Event type. One of `card.topup.completed`, `card.topup.failed`
`card_id`	`string`	Unique identifier of the card
`amount`	`number`	Amount added to the card
`currency`	`string`	Currency used for the topup
`status`	`string`	Current status of the topup (`pending`, `completed`, `failed`)
`transaction_id`	`string`	Unique identifier of the topup transaction
`performed_at`	`string`	Timestamp when the topup was performed

4. Card Action Events

Applicable event types: card.freeze · card.unfreeze · card.cancel · card.activate · card.set_pin

Fired when an action is performed on an existing card (freeze, unfreeze, cancel, activate, or PIN change). These events include a task_id to allow idempotent tracking of async operations.

Payload

{
  "id": "evt_3c990d0027974a269d69ecbbc6252934",
  "type": "card.frozen",
  "createdAt": "2026-04-01T12:14:27.8274318Z",
  "data": {
    "cardId": "b6aa7a4c-ac4f-43ca-9030-9c6936f7913c",
    "customerId": "a850b57a-23c8-48f5-846c-a25c8869ffe8",
    "productId": "cab4a136-6f58-467b-8fc0-c99d76fb0712",
    "cardType": "Virtual",
    "action": "freeze",
    "status": "Frozen",
    "message": "Card frozen successfully.",
    "taskId": "d9727b12-9de8-486e-acfc-3bf07c6bc391",
    "performedAt": "2026-04-01T12:14:27.8196246Z"
  }
}

Field Reference

Field	Type	Description
`event`	`string`	Event type (e.g., `card.frozen`)
`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., `Frozen`, `Active`, etc.)
`message`	`string`	Human-readable outcome message
`performed_at`	`string (ISO 8601)`	Timestamp when the action was performed

5. Card Status Events

Applicable event types: card.approved · card.rejected · card.under_review

Fired when a card's issuance status changes — for example, when a newly requested card is approved, rejected, or placed under review.

Payload

{
  "id": "evt_5377f5d53323457688ea939284e13406",
  "type": "card.created",
  "createdAt": "2026-04-01T12:07:51.2798593Z",
  "data": {
    "customer_id": "a850b57a-23c8-48f5-846c-a25c8869ffe8",
    "card_id": "b6aa7a4c-ac4f-43ca-9030-9c6936f7913c",
    "card_type": "Virtual",
    "application_status": "card.created",
    "application_reason": "Success"
  }
}

Field Reference

Field	Type	Description
`event`	`string`	Event type (e.g., `card.created`)
`customer_id`	`string`	Unique identifier of the customer
`card_id`	`string`	Unique identifier of the card
`card_type`	`string`	Card type — `Virtual` or `Physical`
`status`	`string`	Application status (e.g., `card.created`)
`message`	`string`	Human-readable status message or reason (e.g., `Success`)

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

Your endpoint should return an HTTP 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

Overview#

Payload Conventions#

Event Categories#

1. Transaction Events#

Payload#

Field Reference#

2. Card Holder Application Events#

Payload#

Field Reference#

3. Card Topup Events#

4. Card Action Events#

Payload#

Field Reference#

5. Card Status Events#

Payload#

Field Reference#

Status Values Quick Reference#

Transaction Status#

Card Holder Application Status#

Card Action & Card Status#

Error Handling#

Overview

Payload Conventions

Event Categories

1. Transaction Events

Payload

Field Reference

2. Card Holder Application Events

Payload

Field Reference

3. Card Topup Events

4. Card Action Events

Payload

Field Reference

5. Card Status Events

Payload

Field Reference

Status Values Quick Reference

Transaction Status

Card Holder Application Status

Card Action & Card Status

Error Handling