Authorization

The Convenient Checkout API uses OAuth 2.0 for authorization. This document describes the authentication flow and available scopes.

OAuth 2.0 Gateway

Gateway	OAuth2 Type	Flow Type	Token URL
gateway	OAuth2	clientCredentials	https://api.uhg.com/oauth2/token

API Base URLs

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

Use api-stg.uhg.com for non-production API requests. The OAuth token endpoint remains api.uhg.com in both environments.

Available Scopes

Scope	Environment	Description
https://api.uhg.com/.default	All	Default scope assigned to all clients
financial/commerce/checkout:all	Production	Full scope
financial/commerce/checkout:merchant	Production	Merchant scope
financial/commerce/checkout:merchant-wallet-management	Production	Merchant wallet management scope
financial/commerce/checkout:merchant-pci	Production	Merchant PCI scope
financial/commerce/nonprodcheckout:all	Non-production	Full scope
financial/commerce/nonprodcheckout:merchant	Non-production	Merchant scope
financial/commerce/nonprodcheckout:merchant-wallet-management	Non-production	Merchant wallet management scope
financial/commerce/nonprodcheckout:merchant-pci	Non-production	Merchant PCI scope

OAuth 2.0 Client Credentials Flow

The Client Credentials flow is used for server-to-server API requests where a front-end user is not present. This is typically used for backend integrations with the Convenient Checkout API.

Steps to Acquire an Access Token

1. Make a POST request to the token endpoint: https://api.uhg.com/oauth2/token
2. Include the following parameters:
   • grant_type: Must be client_credentials
   • scope: Space-separated list of requested scopes
   • client_id: Your application's client ID
   • client_secret: Your application's client secret

Example Request

This non-production example requests only the non-production merchant scope. Use the corresponding financial/commerce/checkout:* scope for production. Do not combine production and non-production scopes unless CCG explicitly approves it for your client.

POST /oauth2/token HTTP/1.1
Host: api.uhg.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&scope=financial/commerce/nonprodcheckout:merchant
&client_id=your-client-id
&client_secret=your-client-secret

Example Response

{
  "access_token": "[REDACTED]",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "financial/commerce/nonprodcheckout:merchant"
}

Using the Access Token

Once you have obtained an access token, include it in the Authorization header.

Headers by environment and operation

Header	Non-production	Production	When to send it
Authorization	Required	Required	Every authenticated API request
X-Merchant-Id	Required	Required	Merchant operations
X-Upstream-Env	Required	Omit	Non-production routing only
X-Source	When required by the operation	When required by the operation	Operations such as refund creation and user-scoped confirmation
X-Checkout-Id	When required by the operation	When required by the operation	Applicable user and checkout operations
Content-Type	Requests with a body	Requests with a body	Use the media type required by the request body; omit it for bodyless GET requests

Non-production API examples

Retrieve a payment:

GET /api/financial/commerce/nonprodcheckout/v2/payments/{paymentId} HTTP/1.1
Host: api-stg.uhg.com
Authorization: Bearer [REDACTED]
X-Merchant-Id: your-merchant-id
X-Upstream-Env: dev

Create a full linked refund:

POST /api/financial/commerce/nonprodcheckout/v2/refunds HTTP/1.1
Host: api-stg.uhg.com
Authorization: Bearer [REDACTED]
X-Merchant-Id: your-merchant-id
X-Upstream-Env: dev
X-Source: your-source
Content-Type: application/json

{
  "paymentId": "your-payment-id",
  "merchantTransactionId": "new-unique-refund-id",
  "reason": "REQUESTED_BY_CUSTOMER"
}

Best Practices

1. Token Storage: Store access tokens securely and never expose them to clients
2. Token Refresh: Implement token refresh logic before the access token expires
3. Scope Management: Request only the scopes needed for your application
4. Production vs. Non-Production: Be aware of the environment-specific scopes
5. Error Handling: Implement proper error handling for authorization failures

Related Documentation

• API Headers