Webhook Events

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 Type	Description
`transaction.completed`	Transaction successfully processed
`transaction.failed`	Transaction failed to process
`card.created`	Virtual card created
`card.terminated`	Virtual card deleted
`card.transaction`	Transaction made with virtual card
`account.created`	US 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);
  }
}

def handle_webhook(event):
    event_type = event['event_type']
    
    if event_type == 'transaction.completed':
        handle_transaction_completed(event['data'])
    elif event_type == 'transaction.failed':
        handle_transaction_failed(event['data'])
    elif event_type == 'card.transaction':
        handle_card_transaction(event['data'])
    else:
        print(f"Unhandled event type: {event_type}")

function handleWebhook($event) {
    switch ($event['event_type']) {
        case 'transaction.completed':
            handleTransactionCompleted($event['data']);
            break;
        case 'transaction.failed':
            handleTransactionFailed($event['data']);
            break;
        case 'card.transaction':
            handleCardTransaction($event['data']);
            break;
        default:
            error_log("Unhandled event type: " . $event['event_type']);
    }
}

API

Users

Accounts

Cards

Payments

Fund With Zelle

Webhooks

Webhook Events

Account Events

us_account.created

us_account.ready

Funding Events

zelle_id.update

zelle.collections

us_account.collections

Card Events

card.created

card.terminated

card.auth.approved

card.auth.settled

card.auth.declined

card.auth.reversal

card.cross-border.charge

card.decline.charge

card.topup

card.withdrawal

Payments Events

transaction.completed

transaction.failed

Event Types Reference

Handling Webhook Events

​Account Events

​us_account.created

​us_account.ready

​Funding Events

​zelle_id.update

​zelle.collections

​us_account.collections

​Card Events

​card.created

​card.terminated

​card.auth.approved

​card.auth.settled

​card.auth.declined

​card.auth.reversal

​card.cross-border.charge

​card.decline.charge

​card.topup

​card.withdrawal

​Payments Events

​transaction.completed

​transaction.failed

​Event Types Reference

​Handling Webhook Events

Account Events

us_account.created

us_account.ready

Funding Events

zelle_id.update

zelle.collections

us_account.collections

Card Events

card.created

card.terminated

card.auth.approved

card.auth.settled

card.auth.declined

card.auth.reversal

card.cross-border.charge

card.decline.charge

card.topup

card.withdrawal

Payments Events

transaction.completed

transaction.failed

Event Types Reference

Handling Webhook Events