Checking access…

Skip to main content
Version: v2

V1 to V2 Migration — Pre-Launch Checklist

Use this checklist before sending production traffic to confirm that your V1 to V2 migration is complete. Complete every applicable item before cutover — items in sections marked "if applicable" may be excluded with documented justification. Any unchecked applicable item is a blocker.

This checklist covers the technical go-live gate. For the full migration steps, see the V1 to V2 Migration Guide.

Environment and access​

  • V2 API is available in the target production environment for all in-scope operations. See V2 Environment Availability.
  • V2 and backward compatibility are enabled for your merchant by your CCG representative — confirmed in writing, not assumed.
  • Credentials (client ID, client secret, merchant ID) are confirmed for the production environment.
  • OAuth 2.0 token request uses the production scope: financial/commerce/checkout:merchant.
  • All required request headers are in place: Authorization, X-Merchant-Id, and any operation-specific headers.

API contract​

  • Every V1 operation in scope has an approved V2 operation or an approved exclusion. No inventory row is left as Unsupported/unconfirmed.
  • Request construction has been updated for V2: paymentAllocations[], allocation totals, and required headers.
  • Response parsing handles the complete V2 envelope and iterates data.paymentAllocations[] and data.refundAllocations[].
  • V1-origin resource retrieval (GET /v2/payments/{paymentId} with compatibility enabled) is tested and confirmed.
  • Full linked refund on a V1-origin payment is tested and confirmed (include paymentId, unique merchantTransactionId, omit refundAllocations).
  • Partial linked refund on a V1-origin payment is tested and confirmed (include paymentId, unique merchantTransactionId, and exactly one refundAllocations[] item).
  • Duplicate merchantTransactionId on refunds is confirmed: reusing a merchantTransactionId that already exists on a refund returns 422; no automatic replay occurs.
  • Uncertain refund outcome procedure is understood and owned: if a refund request times out with no refundId, escalate to CCG before submitting another request.

Widget​

  • Widget has been updated from v2 to v3. See Widget Versioning for the current supported version.
  • Widget CDN script src uses the correct production domain (walletprod.healthsafepay.com) and a supported v3 version.
  • Widget is initialized with a checkoutSessionId from POST /v2/sessions (not V1 sessions).
  • Widget loads and renders correctly in production. Test with a real session ID.
  • onSuccess, onError, and onEvent callbacks are wired and tested.

3DS (if applicable)​

  • 3DS challenge is handled by the customer-facing checkout application (not the merchant backend).
  • The PATCH /v2/payments/{paymentId}/allocations/{allocationId}/confirm operation uses the user-scoped operation with financial/commerce/checkout:user scope in production.
  • Merchant backend does not call the confirm operation directly.

Webhooks​

  • Webhook routing handles both V1-shaped and V2-shaped payloads during the coexistence period.
  • Webhook idempotency covers both safeguards from the canonical webhook procedure:
    • Hash the canonical body with version, event name, and resource ID; ignore an identical hash (guards against duplicate deliveries of the same payload).
    • Upsert parent and allocation state by resource ID; suppress any financial or fulfillment side effect already applied to that resource and state (guards against re-delivery of a logically identical event in a different payload shape).
  • Webhook delivery and retry behavior is tested in non-production. See Webhook Error Handling.

Monitoring and recovery​

  • Approved numeric thresholds are recorded: ramp increments, maximum V2 error rate, maximum pending age, minimum webhook success rate, maximum unreconciled financial resources (must be 0).
  • Rollback owner is named and reachable.
  • Escalation contacts are confirmed — contact your CCG representative to record the right contacts for production incidents.
  • On-call alerting covers V2 error rates and webhook delivery failures.

Sign-off​

  • Merchant migration owner has approved go-live.
  • CCG Product or API owner has confirmed all in-scope V2 operations are production-ready and enabled for the merchant.
  • V1 retirement criteria are agreed and recorded.

After go-live​

Once all items above are checked and production traffic is running on V2:

  1. Monitor V2 error rates, webhook delivery, and reconciliation for the agreed observation period.
  2. Retire V1 only after all cutover gates in the V1 to V2 Migration Guide Step 7 are confirmed passed.
  3. Keep V1 available until the CCG representative and merchant owner sign off on retirement.