V2 Changelog
Keep track of changes and upgrades to the Convenient Checkout API.
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 return amounts to each original payment method in the same charged proportion; allocation splits cannot be changed at refund time. | ⚠ 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. |