Skip to main content

​
Account Events

​
us_account.created

Triggered when a new US bank account is successfully created. 
{
  "event_id": "evt_1234567895",
  "event_type": "us_account.created",
  "timestamp": "2023-10-01T12:39:00Z",
  "data": {
    "account_id": "12345hgyd78yuyu9",
    "user_id": "12345",
    "account_status": "INACTIVE",
    "balance": 0,
    "numbers": {
      "ACH": {
        "account_number": "0000",
        "routing_number": "021000021"
      },
      "RTP": {
        "account_number": "0000",
        "routing_number": "021000021"
      },
      "WIRE": {
        "account_number": "0000",
        "routing_number": "021000021"
      }
    }
  }
}

​
us_account.ready

Triggered when a new US bank account is ready for use. 
{
  "event_id": "evt_1234567895",
  "event_type": "us_account.ready",
  "timestamp": "2023-10-01T12:39:00Z",
  "data": {
    "account_id": "12345hgyd78yuyu9",
    "user_id": "12345",
    "account_status": "ACTIVE",
    "balance": 0,
    "numbers": {
      "ACH": {
        "account_number": "0000",
        "routing_number": "021000021"
      },
      "RTP": {
        "account_number": "0000",
        "routing_number": "021000021"
      },
      "WIRE": {
        "account_number": "0000",
        "routing_number": "021000021"
      }
    }
  }
}

​
Funding Events

​
zelle_id.update

Triggered when a submitted zelle id validation has a new update. 
{
  "event_id": "evt_1234567895",
  "event_type": "zelle_id.update",
  "timestamp": "2023-10-01T12:39:00Z",
  "data": {
    "zelle_id": "user@example.com",
    "user_id": "12345",
    "status": "VERIFIED"
  }
}

​
zelle.collections

Triggered when a merchant’s customer funds their wallet via Zelle. 
{
  "event_id": "evt_1234567895",
  "event_type": "zelle.collections",
  "timestamp": "2023-10-01T12:39:00Z",
  "data": {
    "id": "txn_12345",
    "user_id": "12345",
    "zelle_id": "user@example.com",
    "amount": 0,
    "transaction_date": "2023-10-01T12:34:56Z"
  }
}

​
us_account.collections

Triggered when a merchant’s customer funds their US bank account. 
{
  "event_id": "evt_1234567895",
  "event_type": "us_account.collections",
  "timestamp": "2023-10-01T12:39:00Z",
  "data": {
    "id": "txn_12345",
    "user_id": "12345",
    "description": "Wallet FUnding",
    "amount": 0,
    "type": "ACH|WIRE",
    "transaction_date": "2023-10-01T12:34:56Z"
  }
}

​
Card Events

​
card.created

Triggered when a new virtual card is successfully created. 
{
  "event_id": "evt_1234567892",
  "event_type": "card.created",
  "timestamp": "2023-10-01T12:36:00Z",
  "data": {
    "card_id": "card_12345",
    "user_id": "12345",
    "card_name": "John D. Card",
    "card_type": "Virtual",
    "card_brand": "Visa",
    "card_status": "Active",
    "card_balance": 1000,
    "currency": "USD",
    "last_four": "7890"
  }
}

​
card.terminated

Triggered when a virtual card is terminated or deleted. 
{
  "event_id": "evt_1234567893",
  "event_type": "card.terminated",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "card_id": "card_12345",
    "card_type": "Virtual",
    "card_brand": "Visa",
    "card_status": "Deleted",
    "balance_before_termination": 1,
    "currency": "USD",
    "last_four": "7890",
    "auth_message": "Card terminated due to multiple failed debits"
  }
}

​
card.auth.approved

Triggered when a virtual card authorization has been successfully approved during a purchase transaction. 
{
  "event_id": "evt_1234567893",
  "event_type": "card.auth.approved",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_id": "txn_12347",
    "card_id": "card_12345",
    "amount": 50.25,
    "availableBalance": 10,
    "currency": "USD",
    "merchant_name": "Store Inc.",
    "transaction_date": "2023-10-01T12:38:00Z",
    "description": "Purchase at Store",
    "auth_message": "Approved or completed successfully"
  }
}

​
card.auth.settled

Triggered when a virtual card authorization has been settled successfully. 
{
  "event_id": "evt_1234567893",
  "event_type": "card.auth.settled",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_id": "txn_12347",
    "card_id": "card_12345",
    "amount": 50.25,
    "availableBalance": 10,
    "currency": "USD",
    "merchant_name": "Store Inc.",
    "transaction_date": "2023-10-01T12:38:00Z",
    "description": "Purchase at Store",
    "auth_message": "Approved or completed successfully"
  }
}

​
card.auth.declined

Triggered when a virtual card authorization has been declined. 
{
  "event_id": "evt_1234567893",
  "event_type": "card.auth.declined",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_id": "txn_12347",
    "card_id": "card_12345",
    "amount": 50.25,
    "availableBalance": 10,
    "currency": "USD",
    "merchant_name": "Store Inc.",
    "transaction_date": "2023-10-01T12:38:00Z",
    "description": "Purchase at Store",
    "auth_message": "No sufficient funds"
  }
}

​
card.auth.reversal

Triggered when a virtual card previously authorized transaction is reversed. 
{
  "event_id": "evt_1234567893",
  "event_type": "card.auth.reversal",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_id": "txn_12347",
    "card_id": "card_12345",
    "amount": 50.25,
    "availableBalance": 10,
    "currency": "USD",
    "merchant_name": "Store Inc.",
    "transaction_date": "2023-10-01T12:38:00Z",
    "description": "Purchase at Store",
    "auth_message": "Reversal completed successfully"
  }
}

​
card.cross-border.charge

Triggered when a virtual card is used to make a none USD payment. 
{
  "event_id": "evt_1234567893",
  "event_type": "card.cross-border.charge",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_id": "txn_12347",
    "card_id": "card_12345",
    "amount": 1.25,
    "availableBalance": 10,
    "currency": "USD",
    "merchant_name": "Store Inc.",
    "transaction_date": "2023-10-01T12:38:00Z",
    "description": "Purchase at Store",
    "auth_message": "Cross border charge for purchase @ Store Inc."
  }
}

​
card.decline.charge

Triggered when a virtual card authorization is declined for a customer’s transaction due to insufficient funds. 
{
  "event_id": "evt_1234567893",
  "event_type": "card.decline.charge",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_id": "txn_12347",
    "card_id": "card_12345",
    "amount": 1.25,
    "availableBalance": 10,
    "currency": "USD",
    "merchant_name": "Store Inc.",
    "transaction_date": "2023-10-01T12:38:00Z",
    "description": "Purchase at Store",
    "auth_message": "Decline charge for purchase @ Store Inc."
  }
}

​
card.topup

Triggered when a virtual card is topped up with a specified amount. 
{
  "event_id": "evt_1234567893",
  "event_type": "card.topup",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_ref": "trf_12347",
    "card_id": "card_12345",
    "amount": 50.25,
    "oldBalance": 10.0,
    "newBalance": 60.25,
    "currency": "USD",
    "transaction_date": "2023-10-01T12:38:00Z"
  }
}

​
card.withdrawal

Triggered when a withdrawal is made from a virtual card. 
{
  "event_id": "evt_1234567893",
  "event_type": "card.withdrawal",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_ref": "trf_12347",
    "card_id": "card_12345",
    "amount": 10.0,
    "oldBalance": 60.25,
    "newBalance": 50.25,
    "currency": "USD",
    "transaction_date": "2023-10-01T12:38:00Z"
  }
}

​
Payments Events

​
transaction.completed

Triggered when a pending/processing transaction (USD transfer, card push, or PayPal payout) completes successfully. 
{
  "event_id": "evt_1234567890",
  "event_type": "transaction.completed",
  "timestamp": "2023-10-01T12:34:56Z",
  "data": {
    "transaction_id": "txn_12345",
    "transaction_type": "usd_transfer|push_to_card|paypal_payout",
    "amount": 100.5,
    "currency": "USD",
    "status": "successful",
    "account_id": "12345hgyd78yuyu9",
    "reference": "12345hgyd78yuyu9",
    "description": "Payment for services",
    "transaction_date": "2023-10-01T12:34:56Z"
  }
}

​
transaction.failed

Triggered when a pending/processing transaction fails to process. 
{
  "event_id": "evt_1234567891",
  "event_type": "transaction.failed",
  "timestamp": "2023-10-01T12:35:00Z",
  "data": {
    "transaction_id": "txn_12346",
    "transaction_type": "push_to_card",
    "amount": 50.0,
    "currency": "USD",
    "status": "failed",
    "account_id": "12345hgyd78yuyu9",
    "reference": "12345",
    "description": "Failed payment",
    "transaction_date": "2023-10-01T12:35:00Z",
    "failure_reason": "Insufficient funds"
  }
}

​
Event Types Reference

Event TypeDescription
transaction.completedTransaction successfully processed
transaction.failedTransaction failed to process
card.createdVirtual card created
card.terminatedVirtual card deleted
card.transactionTransaction made with virtual card
account.createdUS bank account created

​
Handling Webhook Events

async function handleWebhook(event) {
  switch (event.event_type) {
    case 'transaction.completed':
      await handleTransactionCompleted(event.data);
      break;
    case 'transaction.failed':
      await handleTransactionFailed(event.data);
      break;
    case 'card.transaction':
      await handleCardTransaction(event.data);
      break;
    // Add more cases as needed
    default:
      console.log('Unhandled event type:', event.event_type);
  }
}