Split Tender Backward Compatibility

Backward compatibility is a one-directional bridge that enables v2 API endpoints to operate seamlessly on v1-origin payment and refund resources. This eliminates operational gaps during migration by allowing in-flight v1 resources to be managed through v2 APIs without requiring a hard migration window.

Integration Details

• Use Case: Merchants migrating from v1 to v2 APIs with in-flight or historical v1 payments and refunds
• Scope: GET, PATCH /capture, PATCH /cancel, and POST /refunds operations on v1-origin resources
• Bridge Type: One-directional — v2 endpoints operate on v1-origin resources; v1 endpoints cannot operate on v2-native resources
• API Endpoints:
  • GET /v2/payments/{paymentId}
  • PATCH /v2/payments/{paymentId}/capture
  • PATCH /v2/payments/{paymentId}/cancel
  • POST /v2/refunds
  • GET /v2/refunds/{refundId}
• Request Format: Standard v2 structure; no branch logic or version-specific changes required
• API Response Schema: All API responses conform to v2 schema regardless of resource origin
• Webhook Schema: During parallel use, webhook schema follows resource version; after full v2 migration, all webhooks are delivered in v2 schema
• API Reference: Get Payment | Capture Payment | Cancel Payment | Create Refund | Get Refund

Business Context

For business rules, lifecycle, and full migration strategy, see Split Tender Payments - Business Guide and Split Tender Refunds - Business Guide.

---

---

API Request

Call v2 endpoints with the standard v2 request format exactly as you would for v2-native resources. No request changes or version-specific branching logic is required.

Use the API Reference links below for the exact request schema, required headers, parameters, and request body details.

Operation	Method and Path	Purpose	API Reference
Get Payment	GET /v2/payments/{paymentId}	Retrieve payment status and allocation details for a v1-origin payment using v2 schema	Get Payment
Capture Payment	PATCH /v2/payments/{paymentId}/capture	Capture an authorized v1-origin payment through v2 flow	Capture Payment
Cancel Payment	PATCH /v2/payments/{paymentId}/cancel	Cancel an authorized v1-origin payment through v2 flow	Cancel Payment
Create Refund	POST /v2/refunds	Create a refund for a v1-origin payment by providing paymentId in request body	Create Refund
Get Refund	GET /v2/refunds/{refundId}	Retrieve refund status and allocation details in v2 schema	Get Refund

Linked Partial Refund

For refunds on v1-origin payments in this backward compatibility scenario, include only one entry in refundAllocations, and ensure its paymentAllocationId belongs to the paymentId supplied in the request body. If they do not match, the request is rejected. See Error Handling for the corresponding error.

Sample Request - Partial Linked Refund

{
  "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "merchantTransactionId": "refund_v1_origin_partial_001",
  "reason": "REQUESTED_BY_CUSTOMER",
  "metadata": {
    "orderId": "12345",
    "invoiceDate": "2025-08-22"
  },
  "refundAllocations": [
    {
      "paymentAllocationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "amount": 1000
    }
  ]
}

Request construction guidance:

• Use the exact headers and required fields defined in each linked API Reference operation.
• Use merchant-scoped authentication exactly as documented in api-reference-v2.
• For backward compatibility scenarios, only the resource origin differs; request format remains standard v2.
• For a full linked refund on a v1-origin payment, send paymentId and a unique merchantTransactionId, and omit refundAllocations.
• For a partial linked refund on a v1-origin payment, send paymentId, a unique merchantTransactionId, and exactly one refundAllocations[] item containing paymentAllocationId and amount.
• Every new refund request requires a unique merchantTransactionId. Reusing a value returns 422; it does not safely replay the original refund.

---

API Response

v1-origin resources are returned in v2 response shape with response normalization applied. The response structure is identical to v2-native resources.

Use the API Reference links below for the exact response schema, response codes, and field-level details.

Operation	Response Documentation
Get Payment	Get Payment Response
Capture Payment	Capture Payment Response
Cancel Payment	Cancel Payment Response
Create Refund	Create Refund Response
Get Refund	Get Refund Response

Sample Response Envelope (GET Payment for a v1-origin resource)

In backward compatibility responses for v1-origin payments, only one allocation is provided in paymentAllocations.

{
  "url": "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "merchantTransactionId": "mtx_12345",
    "checkoutId": "a21b4d66-7585-4979-80ec-60ea35b35821",
    "amount": 2500,
    "currencyCode": "USD",
    "paymentDateUtc": "2024-01-15T14:30:00Z",
    "status": "COMPLETED",
    "customer": {
      "id": "b0b3c48d-4cf6-404a-a554-e14640a51c5b"
    },
    "metadata": {
      "orderId": "12345",
      "invoiceDate": "2025-08-22"
    },
    "paymentAllocations": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "amount": 2500,
        "authorizedAmount": 2500,
        "capturedAmount": 2500,
        "status": "COMPLETED",
        "paymentMethod": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "paymentMethodDetails": {
            "type": "CARD",
            "last4": "1234",
            "cardBrand": "VISA",
            "status": "ACTIVE"
          }
        },
        "vendor": {
          "name": "STRIPE",
          "paymentId": "pi_3NabcXYZ123456789"
        }
      }
    ]
  }
}

---

Status Handling

v1 and v2 use the same payment and refund status values. When retrieving v1-origin resources through v2, status values are returned unchanged with no translation or mapping.

For detailed status handling workflows, see Payment Status Handling and Refund Status Handling.

Polling Guidance:

Poll v1-origin resources using:

• GET /v2/payments/{paymentId} for payment status transitions
• GET /v2/refunds/{refundId} for refund status transitions

For both payments and refunds, validate top-level status and allocation-level status (paymentAllocations[0].status / refundAllocations[0].status) to ensure accurate state tracking.

---

Webhooks

Webhook delivery behavior is summarized below.

Use v1 payment webhooks for the parallel capture and cancel payload shape, and v2 refund webhooks for refund payload schemas.

Phase	Operation	Webhook Shape	Notes
Parallel use (v1 and v2 together)	PATCH /v2/payments/{id}/capture	v1	Capture is applied to a v1-origin payment, so notification remains in v1 shape during parallel use
Parallel use (v1 and v2 together)	PATCH /v2/payments/{id}/cancel	v1	Cancel is applied to a v1-origin payment, so notification remains in v1 shape during parallel use
Parallel use (v1 and v2 together)	POST /v2/refunds	v2	Refund resource is created through v2 flow; webhook is emitted in v2 shape
Parallel use (v1 and v2 together)	GET /v2/payments/{id}	None	Read-only operation returns data only and does not publish webhook events
Parallel use (v1 and v2 together)	GET /v2/refunds/{id}	None	Read-only operation returns data only and does not publish webhook events
After full v2 migration	All webhook-emitting operations	v2	After merchant-level webhook migration is activated, all subsequent webhook payloads are delivered in v2 shape

The webhook contract does not provide a standalone delivery ID. Make handling idempotent as follows:

1. Select the V1 or V2 parser from the documented resource and operation rules above; do not infer version from delivery order.
2. Canonicalize the complete webhook body and store a cryptographic hash with the webhook version, name, and resource ID (paymentId or refundId). Treat an identical hash as a duplicate delivery.
3. Upsert parent and allocation state by resource ID. Do not repeat a financial or fulfillment side effect when that resource and state were already applied.
4. If a delivery is out of order, conflicts with stored state, or cannot be classified, retrieve the resource through its owning API and reconcile before taking an irreversible action.

---

Error Handling

Cross-version operations may encounter version-specific errors. Handle these in addition to standard payment errors.

When backward compatibility is not enabled, operation-specific outcomes are listed in the table below.

Error Code	HTTP Status	Scope (Endpoints)	Cause	Resolution
NOT_FOUND	404	GET /v2/payments/{paymentId} GET /v2/refunds/{refundId}	Backward compatibility is disabled, so v1-origin resources are not resolved by standard v2 lookup	Use the correct resource version path or enable backward compatibility for v1-origin resource access through v2
CROSS_VERSION_NOT_ENABLED	409	Merchant-ready V2 cross-version write operations	A V2 cross-version write was attempted on a V1-origin resource without compatibility enablement	Contact support to enable backward compatibility; verify the operation in the parity and environment pages before retrying
UNPROCESSABLE_ENTITY	422	POST /v2/refunds	refundAllocations[n].paymentAllocationId does not belong to the paymentId in the request body, or the request contains more than one refundAllocations entry for a refund against a v1-origin payment	Ensure each refundAllocations[n].paymentAllocationId is an allocation of the body paymentId, and for refunds on v1-origin payments send only one refundAllocations entry
VERSION_CONFLICT	409	V1 operations on V2-native resources	A V1 operation was attempted on a V2-native resource	Use V2 APIs for V2-native resources; use V1 APIs for V1-native resources

Error Response Messages (409 and 422)

The following payload examples cover common 409 and 422 error responses for backward compatibility scenarios.

Sample Error Response Payloads

V1 GET on v2 Payment

{
  "title": "INVALID_REQUEST",
  "status": 409,
  "detail": "GET not allowed: resource is v2-native and cannot be modified via v1 API.",
  "errorCode": "VERSION_CONFLICT"
}

V1 Capture on v2 Payment

{
  "title": "INVALID_REQUEST",
  "status": 409,
  "detail": "Capture not allowed: resource is v2-native and cannot be modified via v1 API.",
  "errorCode": "VERSION_CONFLICT"
}

V1 Cancel on v2 Payment

{
  "title": "INVALID_REQUEST",
  "status": 409,
  "detail": "Cancel not allowed: resource is v2-native and cannot be modified via v1 API.",
  "errorCode": "VERSION_CONFLICT"
}

V1 Refund on v2 Payment

{
  "title": "INVALID_REQUEST",
  "status": 409,
  "detail": "Refund not allowed: resource is v2-native and cannot be modified via v1 API.",
  "errorCode": "VERSION_CONFLICT"
}

CROSS_VERSION_NOT_ENABLED

{
  "title": "INVALID_REQUEST",
  "status": 409,
  "detail": "Cross-version compatibility is not enabled.",
  "errorCode": "CROSS_VERSION_NOT_ENABLED"
}

UNPROCESSABLE_ENTITY — paymentAllocationId/paymentId mismatch

{
  "title": "UNPROCESSABLE_ENTITY",
  "status": 422,
  "detail": "refundAllocations[n].paymentAllocationId must be associated with the specified paymentId"
}

UNPROCESSABLE_ENTITY — More than one allocation for v1 payment refund

{
  "title": "UNPROCESSABLE_ENTITY",
  "status": 422,
  "detail": "Maximum number of refundAllocations allowed for v1 payment is 1"
}

Merchant-Facing Outcomes

• Success: v1-origin resources are returned in v2 schema, with a single entry in paymentAllocations[] for payments and refundAllocations[] for refunds.
• Not Found: If the payment or refund ID does not exist, the API returns the standard not-found outcome for that endpoint.
• Migration Support Not Active: GET lookups return not-found for v1-origin resources. Cross-version write operations return 409 CROSS_VERSION_NOT_ENABLED.

For the complete list of split tender error codes, see Payment Error Codes.

---

Version Comparison

The following table summarizes behavioral differences between v1 and v2 when operating on v1-origin resources through backward compatibility.

Behavior Reference: Merchant-Initiated API Operations

v1 Resource	Merchant Calls (v2 API)	Response Shape	Webhook Shape (Parallel Use)	Webhook Shape (Post-Migration)
v1 Payment or v1 Refund	GET /v2/payments/{id} or GET /v2/refunds/{id}	v2 response	Not applicable	Not applicable
v1 Payment	PATCH /v2/payments/{id}/capture when the state and environment are eligible	v2 response	v1 webhook	v2 webhook
v1 Payment	PATCH /v2/payments/{id}/cancel when the state and environment are eligible	v2 response	v1 webhook	v2 webhook
v1 Payment	POST /v2/refunds when the state and environment are eligible	v2 response	v2 webhook	v2 webhook

Key Differences:

• Request Format: V2 request construction applies, but allocation requirements and supported operations vary by resource origin.
• Response Format: Identical for both; all responses use v2 schema
• Status Mapping: No mapping required; v1 and v2 share the same status values
• Webhook Transition: Keep version-aware webhook handling during parallel use; V1-origin payment actions and V2-created refunds can emit different webhook versions.
• No Hard Cutover: Backward compatibility allows gradual migration without operational freeze

Check the capability parity matrix and V2 environment availability before using capture, cancel, or refund operations.

---

FAQ

Can I use v2 to operate on a v1 payment?

Only supported cross-version operations can operate on eligible v1-origin payments when backward compatibility is enabled. Retrieval, capture, cancel, and refund support depend on the resource state and current endpoint readiness. Check the capability parity matrix and V2 environment availability before implementation.

Do I need different integration logic for v1-origin vs. v2-native resources?

Both return the v2 response schema, so response parsing can be shared. Authentication, request construction, allocation handling, supported operations, and mixed webhook versions still require migration-specific logic.

What happens to in-flight v1 transactions during migration?

In-flight transactions continue following their original version behavior. Backward compatibility enables v2 operations on those resources once migration support is activated for the merchant account. There is no required v1 freeze window before migration activation.

How does webhook shape work during parallel use and after full v2 migration?

During parallel use, supported payment actions on v1-origin resources emit v1 payment webhooks, while refunds created through v2 emit v2 refund webhooks. V2-native resources emit v2 webhooks. Keep version-aware parsing and deduplication until all V1-origin activity is complete.

Can I use v1 APIs to modify a v2-native payment?

No. v1 write operations on v2-native resources are blocked with 409 VERSION_CONFLICT. v1 APIs cannot interact with v2-native resources.

Do GET operations trigger webhooks?

No. Read operations (GET) return data only and do not emit webhook events.

What if backward compatibility is not enabled for my account?

A V1-origin GET through V2 normally returns 404. A merchant-ready V2 cross-version write on a V1-origin resource returns 409 CROSS_VERSION_NOT_ENABLED. Contact support to enable backward compatibility, then confirm operation readiness in the parity and environment pages.

---

Integration Checklist

• Confirm backward compatibility is enabled for the merchant account.
• Update all applicable integration flows to v2 endpoints.
• Validate merchant-ready v2 retrieval, capture, cancel, and refund operations on eligible v1-origin resources.
• Validate webhook handling during parallel use (v1 shape for v1-origin payment capture/cancel, v2 shape for refunds).
• Confirm status tracking checks both top-level and allocation-level status for payments and refunds.
• Implement handling for VERSION_CONFLICT and CROSS_VERSION_NOT_ENABLED responses.
• Keep version-aware webhook handling until all V1-origin activity is complete.

---

Related Documentation

• V1 to V2 Migration Guide
• Split Tender Payments Integration Guide
• Split Tender Refunds
• Split Tender Payments - Business Guide
• Split Tender Refunds - Business Guide
• Customer and Payment Method Data Migration