> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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):**
```javascript theme={"dark"}
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):**
```javascript theme={"dark"}
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):**
```javascript theme={"dark"}
primer.onPaymentPrepare = (data, handler) => {
if (!termsAccepted) {
handler.abortPaymentCreation();
} else {
handler.continuePaymentCreation();
}
};
```
**After (v1):**
```javascript theme={"dark"}
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):**
```javascript theme={"dark"}
primer.onVaultedMethodsUpdate = ({ vaultedPayments, cvvRecapture }) => {
const methods = vaultedPayments.toArray();
// render methods
};
```
**After (v1):**
```javascript theme={"dark"}
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):**
```javascript theme={"dark"}
checkout.addEventListener('primer:methods-update', (event) => {
const methods = event.detail.toArray();
// render methods
});
```
**After (v1):**
```javascript theme={"dark"}
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
Updated event system overview
Full payload reference