V1 to V2 Capability Parity Matrix
Use this matrix during migration planning to confirm whether each V1 capability is already supported in V2, changed in V2, deferred for a later phase, or unsupported in the current rollout.
Merchant-safe availability statement
Last validated: 2026-08-26
Accountable owners: CCG Product and API owners
V2 is available in production. Availability is operation-specific. Before migration, confirm that every operation in scope is production-ready and enabled for the merchant. Deferred operations and operations not listed in the environment matrix are not merchant-ready.
Status meanings
| Status | Meaning |
|---|---|
| Supported | The capability is available for merchant use in the relevant V2 flow. |
| Changed | The capability exists in V2, but the contract, payload shape, scope, or operational model changed. |
| Deferred | The capability is planned or partially published, but is not merchant-ready for the current rollout phase. |
| Unsupported | No approved V2 path is currently available for the migration phase in scope. |
Capability matrix
| Area | Capability | V1 operation | V2 operation | V2 readiness | Contract status | Cross-version support | Environment availability | Merchant action | Source |
|---|---|---|---|---|---|---|---|---|---|
| Payments | Create | POST /payments | POST /v2/payments | Changed | Published; allocation-based request and response | Creates V2-native resources only | Production-ready when enabled for the merchant; stage requires separate confirmation | Update request construction and allocation parsing | OpenAPI |
| Payments | Retrieve by ID | GET /payments/{paymentId} | GET /v2/payments/{paymentId} | Changed | Published; V2 {url, data} envelope | Eligible V1-origin payments when compatibility is enabled; otherwise normally 404 | Production-ready when compatibility is enabled for the merchant; stage requires separate confirmation | Enable compatibility and use the V2 parser | Backward compatibility |
| Payments | Search by merchant transaction ID | GET /payments?merchantTransactionId={id} | GET /v2/payments?merchantTransactionId={id} | Changed | Published; V2 response shape | Validate V1-origin search with compatibility enabled | Production-ready when compatibility is enabled for the merchant; stage requires separate confirmation | Update parsing and verify merchant-scoped lookup behavior | OpenAPI |
| Payments | Capture | PATCH /payments/{paymentId}/capture | PATCH /v2/payments/{paymentId}/capture | Changed | Published; allocation-aware response | Eligible V1-origin payments when compatibility is enabled | Production-ready when enabled for the merchant; stage requires separate confirmation | Verify eligible states and V1 webhook handling | Environment availability |
| Payments | Cancel | PATCH /payments/{paymentId}/cancel | PATCH /v2/payments/{paymentId}/cancel | Changed | Published; V2 cancellation contract | Eligible V1-origin payments when compatibility is enabled | Production-ready when enabled for the merchant; stage requires separate confirmation | Verify eligible states and V1 webhook handling | Environment availability |
| Refunds | Create | POST /refunds | POST /v2/refunds | Changed | Published; allocation-based response and unique refund ID | Supported for eligible V1-origin payments when compatibility is enabled | Production-ready when enabled for the merchant; stage requires separate confirmation | Apply full or partial linked-refund construction rules | OpenAPI |
| Refunds | Retrieve by ID | GET /refunds/{refundId} | GET /v2/refunds/{refundId} | Changed | Published; refundAllocations[] response | Eligible V1-origin refunds when compatibility is enabled | Production-ready when enabled for the merchant; stage requires separate confirmation | Update parser and poll by parent refundId | OpenAPI |
| Sessions | Create | POST /sessions | POST /v2/sessions | Changed | Published; revised session request | No cross-version bridge; migrate flow by flow | Production-ready when enabled for the merchant; stage requires separate confirmation | Update request fields and session modes | Session comparison |
| Sessions | Retrieve by ID | GET /sessions/{sessionId} | GET /v2/sessions/{sessionId} | Changed | Published; revised response | No cross-version bridge; migrate flow by flow | Production-ready when enabled for the merchant; stage requires separate confirmation | Update response parsing | Session comparison |
| Checkout sessions | Retrieve | GET /checkout-sessions/{sessionId} | GET /v2/checkout-sessions/{sessionId} | Changed | Published retrieval contract | Use when enabled for the merchant | Production-ready when enabled for the merchant; stage requires separate confirmation | Update response parsing and validate session state handling | Environment availability |
| Checkout sessions | Update | PATCH /checkout-sessions/{sessionId} | PATCH /v2/checkout-sessions/{sessionId} | Changed | Published operation-based update contract | Use when enabled for the merchant | Production-ready when enabled for the merchant; stage requires separate confirmation | Update request construction and response handling | Update comparison |
| Checkout sessions | Cancel | PATCH /checkout-sessions/{sessionId}/cancel | PATCH /v2/checkout-sessions/{sessionId}/cancel | Changed | Published cancellation contract | Use for eligible sessions when enabled for the merchant | Production-ready when enabled for the merchant; stage requires separate confirmation | Validate session state and cancellation response | Cancel comparison |
| Checkout sessions | Create child session | POST /checkout-sessions/{sessionId}/child-sessions | POST /v2/checkout-sessions/{sessionId}/child-sessions | Changed | Published child-session contract | Use when parent-session and child-session rules are satisfied | Production-ready when enabled for the merchant; stage requires separate confirmation | Validate parent state, child-session rules, and response handling | Child-session comparison |
| Payment methods | Retrieve by ID | GET /payment-methods/{payment-method-id} | GET /v2/payment-methods/{id} | Changed | Published; revised wallet response | No blanket cross-version commitment | Production readiness unconfirmed | Validate the flow and environment before migration | OpenAPI |
| Payment methods | Update | PATCH /payment-methods/{payment-method-id} | PATCH /v2/payment-methods/{id} | Changed | Published; revised request and response | No blanket cross-version commitment | Production readiness unconfirmed | Validate IDs, scope, and contract per flow | OpenAPI |
| Payment methods | Delete | DELETE /payment-methods/{payment-method-id} | DELETE /v2/payment-methods/{id} | Changed | Published; revised wallet contract | No blanket cross-version commitment | Production readiness unconfirmed | Validate IDs, scope, and contract per flow | OpenAPI |
| Payment methods | Search | POST /payment-methods/search | POST /v2/payment-methods/search | Changed | Published; revised search contract | No blanket cross-version commitment | Production readiness unconfirmed | Validate identity inputs and response shape | OpenAPI |
| Token flows | Create payment | POST /token/payments | POST /v2/token/payments | Changed | Published; revised PCI payment contract | No blanket cross-version commitment | Production readiness unconfirmed | Update payload and use the environment-specific PCI scope | OpenAPI |
| Token flows | Set up payment method | POST /token/setup-payment-methods | POST /v2/token/setup-payment-methods | Changed | Published; revised setup contract | No blanket cross-version commitment | Production readiness unconfirmed | Update payload and use the environment-specific PCI scope | OpenAPI |
| Token flows | Retrieve setup status | GET /token/setup-payment-methods/{setupPaymentMethodId} | GET /v2/token/setup-payment-methods/{setupPaymentMethodId} | Changed | Published; revised response | No blanket cross-version commitment | Production readiness unconfirmed | Update response parsing | OpenAPI |
| Webhooks | Payment events | V1 payment webhook | V2 payment webhook | Changed | Published; V2 allocation payload | V1-origin payment actions can emit V1 payment webhooks during parallel use | Available only when the corresponding operation and environment are available | Parse both versions and deduplicate events | Payment comparison |
| Webhooks | Refund events | V1 refund webhook | V2 refund webhook | Changed | Published; V2 allocation payload | Refunds created through V2 emit V2 refund webhooks | Available only when refund creation is available | Parse both versions and deduplicate events | Refund comparison |
| 3DS | Confirm payment allocation | No merchant-facing V1 equivalent | PATCH /v2/payments/{paymentId}/allocations/{allocationId}/confirm | Changed | Published user-scoped operation | Applies to V2 payment allocations; not a merchant-backend recovery call | Production readiness unconfirmed | Let the customer-facing checkout flow call it with user scope | 3DS confirmation |
How to use this matrix
- List every V1 flow in the current integration.
- Match each flow to an operation row and record its Supported, Changed, Deferred, or Unsupported readiness.
- For every Changed row, validate the exact request, response, webhook, and status behavior in the linked source pages.
- Treat “not listed in the environment matrix” as unconfirmed, not available.
- Do not schedule cutover for Deferred or Unsupported operations without an approved exception or alternate path.