Skip to main content

v1 to v2 Migration Guide

This guide covers what changed between SDK v1 (@zkp2p/pay-sdk@1.x) and v2 (@zkp2p/pay-sdk@2.0.0 / @zkp2p/pay-shared@2.0.0).

Required SDK Upgrade​

npm install @zkp2p/pay-sdk@2.0.0 @zkp2p/pay-shared@2.0.0

Summary​

v2 unifies Zelle on a single rail. Previously a Zelle payment could carry a bank-specific rail value (zelle-chase, zelle-bofa, zelle-citi); as of v2 the rail is always the base platform:

  • payment.rail is always zelle for Zelle payments — in API responses, checkout aggregates, and webhook payloads.
  • The customer's bank pick is exposed separately as the new payment.paymentMethodId field (zelle-chase | zelle-bofa | zelle-citi, null for non-Zelle rails). It is display/routing metadata, not a rail.
  • enabledRails and preselectedMethod continue to use base platform values (zelle) — nothing changes there.

Breaking Changes​

payment.rail no longer carries Zelle bank variants​

If your integration matched on zelle-chase, zelle-bofa, or zelle-citi (for example in webhook handlers or reconciliation), match on zelle instead. Read the bank from payment.paymentMethodId if you need it for display.

// v1
if (payment.rail.startsWith('zelle')) { /* ... */ }

// v2
if (payment.rail === 'zelle') {
  const bank = payment.paymentMethodId; // 'zelle-chase' | 'zelle-bofa' | 'zelle-citi' | null
}

Historic payments created before the cutover keep their original stored rail values in your records; only new payments are affected.

Removed @zkp2p/pay-shared exports​

The following Zelle-variant helpers were removed. They existed to support the retired per-bank rails and have no v2 equivalent because quoting and settlement are now variant-free:

  • ZELLE_QUOTE_PLATFORMS
  • expandZelleQuotePlatforms
  • zelleCompatibleMethods
  • SUPPORTED_ZELLE_RAIL_VARIANTS
  • isSupportedZelleRailVariant

If you validated bank picks with isSupportedZelleRailVariant, use the new ZELLE_PAYMENT_METHOD_IDS set instead.

Renamed export​

  • ZELLE_VARIANT_ACTION_SUFFIX → ZELLE_METHOD_ACTION_SUFFIX (same keys and values; now keyed by paymentMethodId).

New in v2​

  • payment.paymentMethodId on payment objects (see TypeScript Types).
  • Create-payment accepts an optional paymentMethodId when rail is zelle (zelle-chase | zelle-bofa | zelle-citi). Hosted checkout sends it automatically; direct API integrations may pass it to preserve the customer's bank pick across sessions.
  • New @zkp2p/pay-shared helpers: ZELLE_PAYMENT_METHOD_IDS, ZELLE_BUYER_TEE_ACTION_TYPES, isGenericZellePaymentMethodHash.

No Action Needed If…​

  • You only use createCheckout / hosted checkout URLs and handle webhooks by order status: nothing in your integration observes Zelle bank variants.
  • You already treat rail values as opaque base-platform strings.