Skip to main content
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

AreaChange
Event payloadspaymentSummary renamed to payment in success/failure events
Vault eventsNamespace removed: primer:vault:methods-update → primer:vault-methods-update
CallbacksAll callbacks deprecated (onPaymentSuccess, onPaymentFailure, onPaymentPrepare, onPaymentStart, onVaultedMethodsUpdate)
CollectionsRemoved .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

EventPayloadDescription
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-updateInitializedPaymentMethod[]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