V2 Changelog
Keep track of changes and upgrades to the Convenient Checkout API.
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. |