Migrating from v0 to v1

Update your integration for the new event-driven API.

Version 1.0 introduces a simpler, event-driven API. Callbacks are deprecated — use DOM events instead.

Breaking Changes: v1.0.0 includes breaking changes to the events API, callbacks, and data structures. Review this guide before upgrading.

Summary of changes

Breaking changes

Area	Change
Event payloads	paymentSummary renamed to payment in success/failure events
Vault events	Namespace removed: primer:vault:methods-update → primer:vault-methods-update
Callbacks	All callbacks deprecated (onPaymentSuccess, onPaymentFailure, onPaymentPrepare, onPaymentStart, onVaultedMethodsUpdate)
Collections	Removed .toArray() — vaulted payments and payment methods are now arrays directly

New features

• primer:payment-start is now preventable with abortPaymentCreation() and continuePaymentCreation()
• primer:payment-start supports idempotency keys via continuePaymentCreation({ idempotencyKey })
• primer:vault-methods-update now includes cvvRecapture
• New primer:payment-cancel event for cancelled payments

Update payment handling

Before (v0):

checkout.addEventListener('primer:ready', (event) => {
  const primer = event.detail;

  primer.onPaymentSuccess = ({ payment }) => {
    window.location.href = `/confirmation?order=${payment.orderId}`;
  };

  primer.onPaymentFailure = ({ error }) => {
    console.error('Payment failed:', error.message);
  };
});

After (v1):

checkout.addEventListener('primer:payment-success', (event) => {
  const { payment } = event.detail;
  window.location.href = `/confirmation?order=${payment.orderId}`;
});

checkout.addEventListener('primer:payment-failure', (event) => {
  const { error } = event.detail;
  console.error('Payment failed:', error.message);
});

Update pre-payment validation

If you used onPaymentPrepare to validate before payment, use primer:payment-start with preventDefault().

Before (v0):

primer.onPaymentPrepare = (data, handler) => {
  if (!termsAccepted) {
    handler.abortPaymentCreation();
  } else {
    handler.continuePaymentCreation();
  }
};

After (v1):

checkout.addEventListener('primer:payment-start', (event) => {
  const { continuePaymentCreation, abortPaymentCreation } = event.detail;
  
  event.preventDefault();
  
  if (!termsAccepted) {
    abortPaymentCreation();
  } else {
    // Optionally pass an idempotency key
    continuePaymentCreation({ idempotencyKey: 'your-key' });
  }
});

Update vault handling

The onVaultedMethodsUpdate callback is replaced by the primer:vault-methods-update event. Note the event name change (hyphen instead of colon before methods).

Before (v0):

primer.onVaultedMethodsUpdate = ({ vaultedPayments, cvvRecapture }) => {
  const methods = vaultedPayments.toArray();
  // render methods
};

After (v1):

checkout.addEventListener('primer:vault-methods-update', (event) => {
  const { vaultedPayments, cvvRecapture } = event.detail;
  // vaultedPayments is already an array — no .toArray() needed
  vaultedPayments.forEach(method => {
    console.log(method.paymentInstrumentData?.last4Digits);
  });
});

Update payment methods handling

Before (v0):

checkout.addEventListener('primer:methods-update', (event) => {
  const methods = event.detail.toArray();
  // render methods
});

After (v1):

checkout.addEventListener('primer:methods-update', (event) => {
  const methods = event.detail;
  // methods is already an array — no .toArray() needed
  methods.forEach(method => {
    console.log(method.type);
  });
});

Event reference

Event	Payload	Description
primer:payment-success	{ payment, paymentMethodType, timestamp }	Payment completed
primer:payment-failure	{ error, payment?, paymentMethodType, timestamp }	Payment failed
primer:payment-start	{ paymentMethodType, continuePaymentCreation, abortPaymentCreation, timestamp }	Payment creation starting (preventable)
primer:payment-cancel	{ paymentMethodType, timestamp }	Payment cancelled
primer:vault-methods-update	{ vaultedPayments, cvvRecapture, timestamp }	Vaulted methods loaded
primer:vault-selection-change	{ paymentMethodId, timestamp }	User selected a saved method
primer:methods-update	InitializedPaymentMethod[]	Payment methods loaded

Deprecation timeline

Callbacks continue to work in v1 as a fallback but will be removed in a future major version. Migrate to events now to avoid breaking changes later.

See also

Events Guide

Updated event system overview

Events Reference

Full payload reference