Direct-to-V2 Integration Steps
This page covers integration for a net-new merchant — no existing V1 integration, no data migration involved. If you're upgrading an existing integration instead, see the V1 to V2 Migration Guide.
Prerequisites
Before integrating, complete:
Credentials & Scopes
Your HCP registration grants your application the API scope(s) it needs. The required scopes depend on which V2 APIs your integration uses:
| Scope | Required for |
|---|---|
merchant | Sessions, Payments (capture/cancel), Refunds |
user | Creating and retrieving payment intents (alongside merchant) |
merchant-pci | Token-based PCI payment flows (/token/payments) only |
user (customer-facing) | Checkout Sessions (/v2/checkout-sessions/*), confirming payment intents |
merchant-wallet-management | Payment Methods API — see the caution below before using |
The full scope identifiers per environment (e.g., financial/commerce/nonprodcheckout:merchant)
are listed in Authorization. Work with
your CCG onboarding contact to confirm which scopes to request during HCP registration.
API Base URLs
All V2 API calls go to one of these base URLs depending on your target environment:
| Environment | Base URL |
|---|---|
| Non-production | https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2 |
| Production | https://api.uhg.com/api/financial/commerce/checkout/v2 |
Append the operation path (e.g., /sessions, /payments) to the base URL for each request. The
OAuth token endpoint (https://api.uhg.com/oauth2/token) is the same in all environments.
Authentication
V2 uses OAuth 2.0 client credentials flow. Every API request requires a Bearer token.
1. Request a token
POST https://api.uhg.com/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=<your-client-id>
&client_secret=<your-client-secret>
&scope=<environment-scope>
Use scope financial/commerce/nonprodcheckout:merchant for non-production and
financial/commerce/checkout:merchant for production. Additional scopes (user,
merchant-pci, merchant-wallet-management) follow the same naming pattern.
The response contains an access_token valid for 3600 seconds.
2. Include the token on every request
Authorization: Bearer <access_token>
X-Merchant-Id: <your-merchant-id> # required for merchant-scoped operations
X-Upstream-Env: <dev|stage|...> # required for non-production requests only
See Authorization for the full header reference, a complete scope list, and worked request/response examples.
Choose Your Integration Path
| Path | Best for | Effort |
|---|---|---|
| UI Components (Widget) | Fastest path to production, standard checkout flows | Low — mostly frontend |
| Direct API Integration | Custom UI, full control over the checkout experience | High — backend & frontend |
Widget Integration
Use the v3 Bootstrapper pattern — the current, actively-maintained widget integration — documented in the "v3" tab of the Embedded Experience guide.
Other pages in this docs set reference an older widget integration pattern (the "v2" tab on the same page, and the snippet on the general Getting Started with CCG page). As a net-new merchant, use the v3 pattern only — don't follow the v2 snippet.
The Embedded Experience guide's setup section contains curl examples that call the v1 sessions
path. Ignore those. Your backend must call POST /sessions using the V2 createSession
operation (merchant scope) — the same endpoint documented in the
V2 API Reference. Using a v1 session with the v3
widget produces undefined behaviour.
API Integration (merchant-backend)
Build your own UI against the V2 API. The following merchant-backend operations require the
merchant scope and are confirmed available:
| Capability | Scope | Reference |
|---|---|---|
| Sessions | merchant | V2 API Reference |
| Payments (create/get intent) | merchant + user | V2 API Reference |
| Payments (capture/cancel) | merchant | V2 API Reference |
| Refunds | merchant | V2 API Reference |
| Split Tender Payments | merchant | Split Tender Payments API |
Checkout Sessions (customer-facing)
Checkout Session operations (/v2/checkout-sessions/*) use the user scope and serve the
customer actor, not your merchant backend. They are created and managed by the widget flow — you
typically do not call these endpoints directly from your server. See the
V2 API Reference for the full contract.
Not every V2 operation is production-ready for every merchant. Before going live:
- Confirm that each operation you use is both production-available and enabled for your merchant
- Stage readiness must be validated separately — passing staging tests does not establish production access
- See V2 Environment Availability for the complete availability matrix
The V1 to V2 Capability Parity Matrix marks the Payment Methods and Token Flow V2 endpoints as having no blanket cross-version commitment and production readiness unconfirmed. If your integration needs stored-payment-method or tokenization flows, confirm current readiness with your CCG onboarding contact before building against them — don't assume production-readiness from this guide alone.
Webhooks
Configure webhooks per the Webhook Configuration guide.
Idempotent processing is required for all merchants. Retries fire on any non-2XX response not
in the non-retriable set (400, 401, 403, 404, 413), and on endpoint timeouts (no
response within 30 seconds) — exponential backoff, up to 5 attempts within a 50-minute window. Your
endpoint must handle duplicate deliveries without creating duplicate side effects. See
Error Handling & Retry Strategies
for the full policy.
As a net-new merchant, you do not need to handle mixed-version payload deduplication: that complexity only applies to merchants migrating from V1, who can receive both an old-shape and a new-shape event for the same transaction during coexistence. You will only ever receive the current V2 event shape.
Reports
No special configuration is needed for V2 — see Reporting for setup. Reports work the same way regardless of adoption path.
Optional: Split Tender
Split tender lets a customer divide one payment across two saved cards. It's off by default — ask your CCG onboarding contact to enable it if you need it, then follow the Split Tender Payments API guide.