V2 Changelog
Keep track of changes and upgrades to the Convenient Checkout API.
Business Context
For the decision-level rationale for adopting V2, read Why Adopt V2.
V2 — 2026-10-13
Non-Breaking Enhancement
The following change is fully backward-compatible. No integration updates are required.
Payment Methods — HSA/FSA Card Tagging
Card payment method details now include an hsaTagged boolean field. This field is present wherever card payment method details (paymentMethodDetails of type CARD) are returned, including payments, refunds, payment method responses, and the corresponding webhook payloads.
| Field / Area | Change | Details | Breaking |
|---|---|---|---|
hsaTagged | Added | New boolean field on card payment method details (CardResponse) indicating whether the card is tagged as a Health Savings Account (HSA) card. Defaults to false. |
V2 — 2026-07-08
Non-Breaking Enhancement
The following change is fully backward-compatible. No integration updates are required.
Agent Identity — Email / UPN Support
The agent.userId field now accepts either an MSID or an email address / UPN (User Principal Name) as the agent's identity. Existing integrations that supply an MSID continue to work without modification.
| Field / Area | Change | Details | Breaking |
|---|---|---|---|
agent.userId | Changed | Now accepts either an **MSID** (maximum 50 characters) or an **email address / UPN** (maximum 250 characters). Existing MSID-only integrations continue to work without any changes. |
Constraints
| Identity Type | Max Length |
|---|---|
| MSID | 50 characters |
| Email / UPN | 250 characters |
V2 — 2026-05-27
Breaking Changes in V2
The following fields and behaviours have changed in ways that require updates to your integration before upgrading. See each section below for full details.
| Area | What Changed |
|---|---|
| Sessions | Flat ID fields removed from root: merchantId, customerId, vendorMerchantId, paymentId, paymentMethodId, childSessionId. Use structured sub-objects instead. |
| Sessions | paymentType removed from checkout request (was deprecated in V1). |
| Sessions | email and phoneNumber moved from the top-level request into the customer object. |
| Payments | paymentType removed (was deprecated in V1). |
| Payments | paymentAllocations added to support split-tender payments across multiple payment methods. |
| Refunds | refundAllocations added to represent allocation-level refund details for split-tender refunds. |
| Payment Methods | cardCategory renamed to cardCategories and changed from an object to an array. |
| Payment Methods | paymentMethodType removed; now inferred from the shape of paymentMethodDetails. |
| Payment Methods | card object removed (was deprecated in V1). |
Sessions
| Field / Area | Change | Details | Breaking |
|---|---|---|---|
merchant | Added | Structured object containing id, name, and merchantGroupId. Replaces flat merchantId and name fields. | |
customer | Added | Structured object containing id. Replaces flat customerId field. | |
payment.consent | Changed | Moved consent object inside the checkout payment object for ACH payments. | |
payment.description | Changed | Renamed from paymentDescription on the checkout request. | |
| Flat ID fields | Removed | merchantId, customerId, vendorMerchantId, paymentId, paymentMethodId, childSessionId removed from session root. Use merchant.id, customer.id, payment.id, etc. | ⚠ Breaking |
paymentType | Removed | Removed from checkout request. Was deprecated in V1. | ⚠ Breaking |
email, phoneNumber | Removed | Removed from the top-level checkout request. Both are now part of the customer object. | ⚠ Breaking |
Payments
| Field / Area | Change | Details | Breaking |
|---|---|---|---|
paymentAllocations | Added | New allocation-level array that enables split-tender payments across multiple payment methods. | ⚠ Breaking |
description | Changed | Renamed from paymentDescription in V1. String (nullable). Merchant-provided description for this payment. | ⚠ Breaking |
paymentType | Removed | Was deprecated in V1. Split tender is sale-only; payment type is no longer declared explicitly. | ⚠ Breaking |
| Internal vendor fields | Removed | vendor, vendorPaymentId, vendorMerchantId, and paymentMethodId were removed from the root payment shape and moved to paymentAllocations[].vendor. | ⚠ Breaking |
Refunds
| Field / Area | Change | Details | Breaking |
|---|---|---|---|
refundAllocations | Added | New allocation-level refund details support full and partial split-tender refunds while preserving linkage to original payment allocations. | ⚠ Breaking |
Payment Methods
| Field / Area | Change | Details | Breaking |
|---|---|---|---|
sourceProvider | Added | New object identifying the originating source of the payment method. | |
error | Changed | Now a structured object with a machine-readable code and human-readable description. | |
paymentMethodType | Removed | Removed (CARD | BANK_ACCOUNT). Payment method type is now inferred from the shape of paymentMethodDetails. | ⚠ Breaking |
card (CardResponse) | Removed | Was deprecated in V1; removed entirely in V2. | ⚠ Breaking |
vendorPaymentMethodFingerprint | Removed | Internal vendor field removed from card details. |