Dashboard
DocsPayment Method Live Updates | BotSubscription
Live Updates · Channels

Payment Method Live Updates

Subscribe to the payment-methods channel to reflect saved payment methods live in a customer-facing wallet, billing page, or checkout drawer — cards appear the moment they're tokenized, and disappear the moment they're removed.

Subscribing

No identifier is required. Subscribing returns every payment method event for the project the connection is authenticated against.

{ "action": "subscribe", "channel": "payment-methods" }

The server replies with subscribed. Use action: "unsubscribe" with the same channel to stop the feed.

Events

Both events arrive as named Socket.IO events with snake_case field names and the standard broadcast envelope (event_id, emitted_at).

payment-method.added

Fires when a new payment method is saved — either through your UI's setup flow or asynchronously via a provider webhook (e.g. when the upstream confirms a tokenization).

FieldTypeNotes
channelstringAlways "payment-methods".
project_idstringThe owning project.
payment_methodobjectThe saved method — see fields below.

payment_method fields:

FieldTypeNotes
payment_method_idUUIDBotSubscription identifier.
merchant_account_idUUIDThe merchant account the method is attached to.
labelstring | nullOptional human-readable label.
metadataobjectDisplay fields — varies by provider, see the table below.
user_idstring (optional)The customer the method belongs to, when applicable.

The metadata shape depends on the provider that issued the method:

ProviderFields in metadata
Cardlast4, brand, exp_month, exp_year, country, type, billing_country
PayPalpaypal_email, paypal_payer_id
Paystackpaystack_email
Note

Sensitive data is never sent. Raw provider tokens (the actual charging credential) are stripped before the payload leaves the gateway and never appear on the wire. The metadata fields are limited to what is safe to render in a UI. For Paystack specifically, the reusable authorization code lives only in the stripped provider-token field and is never exposed — your UI gets the customer's email and nothing else.

Example — a saved card:

{
  "event_id": "9b724ac8-f0e1-4b56-8d7a-2c9c0d11b2f1",
  "emitted_at": 1779836400000,
  "channel": "payment-methods",
  "project_id": "93425026-6bb8-4f81-a75d-63f538e1a123",
  "payment_method": {
    "payment_method_id": "11111111-1111-1111-1111-111111111111",
    "merchant_account_id": "22222222-2222-2222-2222-222222222222",
    "label": "My Visa",
    "metadata": {
      "last4": "4242",
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2027,
      "country": "US",
      "type": "credit",
      "billing_country": "US"
    }
  }
}
Tip

Duplicate detections are suppressed. When a method already exists for a customer and the provider reports it again (same external token, no database change), the gateway does not re-emit payment-method.added. The event fires only for genuinely new records and semantically-updated existing ones (for example, a refreshed provider token).

payment-method.deleted

Fires when a saved payment method is deleted. The payload includes only the identifier — you don't need the full method object to remove it from your UI.

{
  "event_id": "5e2a1b0d-7c61-4d83-9f10-aa00b2c3d4e5",
  "emitted_at": 1779836400000,
  "channel": "payment-methods",
  "project_id": "93425026-6bb8-4f81-a75d-63f538e1a123",
  "payment_method_id": "11111111-1111-1111-1111-111111111111"
}
  1. On ready, subscribe to payment-methods.
  2. Keep a local map keyed by payment_method_id.
  3. On payment-method.added, insert or overwrite the entry from the payment_method payload.
  4. On payment-method.deleted, remove the entry using payment_method_id.
  5. After a reconnect, resubscribe and reconcile from the REST API if your UI shows authoritative counts.

Next steps

Last updated: