Skip to main content
API docs by Redocly

Convenient Checkout API (v2)

Download OpenAPI specification:Download

CCGLeads: CCGLeads@ds.uhc.com Terms of Service

The Convenient Checkout Gateway (CCG) API provides a unified interface for merchants to manage payment transactions, including session management, payment processing, and refunds. It supports various payment methods and flows, enabling merchants to offer a seamless checkout experience to their customers.

🔀 Migrating from V1?

Compare everything that changed between v1 and v2 — new endpoints, removed fields, response schema updates, and more.

View V1 vs V2 Diff →

Merchant

Provides a comprehensive set of operations for merchants, enabling them to initiate new payment transactions, capture authorized payments, cancel pending or authorized payments, and process both full and partial refunds. These operations are designed to support the complete payment lifecycle, ensuring flexibility and control over payment management for merchants.

Create Session

This API enables merchants to create a session for initializing the convenient checkout widget.

The session provides a secure context for payment processing and manages the lifecycle of the checkout process.

Authorizations:
ProductionStaging
header Parameters
X-Merchant-Id
required
string <uuid>

Unique identifier for the merchant. This is used to identify the merchant making the request. Learn More

X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

Specify the Upstream Environment value. Learn More

Only required for Non-Prod Environment

X-Source
string <= 50 characters

Specify the Source System Identifier. Learn More

Request Body schema: application/json
required
object (SessionPaymentRequest)
object (Customer)

The customer object is required for authenticated user flows. Learn More

Processing Rules

The customer object must be provided when

  • Adding payment methods
  • Making payments using a stored payment method, Pay and Store, One Time Pay
  • Issuing Credits

For guest payments, including the customer object is optional.

object (appearance)

Appearance configuration for the checkout session

object (SessionConfig)
object (Agent)

Information about the agent when a request is submitted on behalf of a customer. Learn More

object (SessionPaymentMethod)

Responses

Request samples

Content type
application/json
{
  • "payment": {
    },
  • "customer": {
    },
  • "appearance": {
    },
  • "config": {
    },
  • "agent": {
    },
  • "paymentMethod": {
    }
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "data": {
    }
}

Get Session

This API allows merchants to retrieve details about a specific session, including its current state and information.

Authorizations:
ProductionStaging
path Parameters
sessionId
required
string <uuid>
header Parameters
X-Merchant-Id
required
string <uuid>

Unique identifier for the merchant. This is used to identify the merchant making the request. Learn More

X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

Specify the Upstream Environment value. Learn More

Only required for Non-Prod Environment

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create Payment

This API enables merchants to create a payment transaction. It supports various payment methods and allows for split payments.

Supported Payment Flows

Single Payment

  • Pay With Wallet - Pay using a stored payment method
  • Pay & Save - Process payment and save the method for future use
  • One Time Pay - Process a single transaction without saving the method
  • Supported payment methods:
    • CARD
    • BANK_ACCOUNT

Split Payment

  • Pay With Wallet only - Multiple payment methods in a single transaction
  • Supported payment method combinations:
    • CARD + CARD only (maximum 2 allocations)
Authorizations:
ProductionStaging
header Parameters
X-Merchant-Id
required
string <uuid>

Unique identifier for the merchant. This is used to identify the merchant making the request. Learn More

X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

Specify the Upstream Environment value. Learn More

Only required for Non-Prod Environment

X-Source
string <= 50 characters

Specify the Source System Identifier. Learn More

Request Body schema: application/json
required
amount
required
integer <int64> [ 1 .. 100000000 ]

Total payment amount in cents.

Must exactly equal the sum of all paymentAllocations[*].amount values

merchantTransactionId
required
string [ 1 .. 50 ] characters

Unique identifier provided by the merchant for the payment. Serves as the idempotency key to prevent duplicate payment processing.

Processing Rules
  • Must be unique per merchant.
  • Allows the merchant to retry the same payment request using the same merchantTransactionId up to 4 times (5 total attempts including the initial one).
  • After 4 retries (5th attempt), a new merchantTransactionId must be used.
currencyCode
string
Default: "USD"
Value: "USD"

ISO 4217 currency code specifying the currency for the payment amount.

USD: United States Dollar (only supported currency)

description
string or null <= 100 characters
Default: null

Text description providing context about the payment for internal tracking, receipts, or administrative purposes. Does not appear on customer's bank statement.

statementDescriptorSuffix
string or null <= 10 characters ^(?=.*[A-Za-z])[A-Za-z0-9 .-]{1,10}$
Default: null

Suffix appended to the merchant's default statement descriptor on the customer's bank statement. Full descriptor format: [Merchant Descriptor] * [Suffix].

object or null (MetadataRequest) <= 20 properties
Default: null

Set of key-value pairs that you can attach to an object.

This can be useful for storing additional information about the object in a structured format.

Processing Rules
  • Constraints:
    • Key length: 1-40 characters
    • Value length: 1-100 characters
  • Non-PII recommendation: Avoid storing sensitive personal information (SSN, DOB, full card numbers).
object or null (PaymentDetailsRequest)
Default: null

Healthcare-related payment information for FSA/HSA card processing including qualified medical amounts, vision amounts, and prescription details.

Processing Rules
  • Applicability: Only applicable for CARD payment methods. Ignored for BANK_ACCOUNT payment method.
  • Required: Yes, for CARD payment methods involving FSA/HSA cards.
object
Default: null

Agent information provided by the caller. Learn More

authorizeCard
boolean
Default: false

Controls whether to use a two-step authorization flow (hold funds) or one-step authorization + capture (charge immediately).

Processing Rules
  • Applicability: CARD payment method only. Ignored for BANK_ACCOUNT payment types.
  • Constraint: When authorizeCard is true, partialAuthorization should also be true — the two flags are complementary and should not be used in isolation.

When true — two-step flow (authorize, then capture):

  • Funds are held (authorized) but not immediately charged (captured)
  • Payment status transitions to AUTHORIZED and awaits explicit capture
  • A subsequent POST /payments/{paymentId}/capture call is required to complete the charge
  • Authorization holds expire after 7 days; the payment must be re-authorized after expiry
  • Typical use cases: hotel/rental pre-authorization holds, split-tender with deferred capture, payment verification

When false — one-step flow (authorize + capture):

  • Authorization and capture occur simultaneously in a single operation
  • The customer's card is charged immediately
  • Payment status transitions to COMPLETED on success
partialAuthorization
boolean
Default: false

Controls whether the payment processor can authorize a partial amount when the full requested amount is not available on the card. Particularly important for healthcare cards (FSA/HSA) and split-tender scenarios.

Processing Rules
  • Applicability: CARD payment method only. Ignored for BANK_ACCOUNT payment types.
  • Constraint: Should be set to true when authorizeCard is true.

When true:

  • The card issuer may approve a lesser amount than requested
  • Payment succeeds with the authorized (partial) amount; status transitions to COMPLETED or AUTHORIZED
  • The merchant is responsible for handling the remaining balance (e.g., charging a second payment method)
  • Particularly important for healthcare cards (FSA/HSA) where the eligible amount may be less than the total

When false:

  • The full requested amount must be authorized or the payment is declined
  • No partial approvals are accepted from the card issuer
object or null or object or null (ConsentRequest)
Default: null

Customer consent details required for BANK_ACCOUNT payment methods. Captures consent identifier, consent text, collection timestamp, and collection method details.

Processing Rules
  • Applicability: This consent schema is applicable for BANK_ACCOUNT payment methods. Defaulted to null for CARD payment methods.
  • Constraint: When consent type is PPD, the agent field at payment level is required.
  • Consent records are immutable once created and should be retained for compliance purposes.
required
object (CustomerRequest)

Customer details for identification and contact purposes. Includes identifiers (hsid, enterpriseIdentifier), contact information (email, phone), and custom metadata.

Processing Rules

Customer Identification:

  • At least one customer identifier must be provided for customer lookup:
    • enterpriseIdentifier
    • hsid
    • metadata
  • Lookup Priority: When multiple identifiers are provided, below is the lookup priority order:
    • enterpriseIdentifier (highest priority)
    • hsid
    • metadata (lowest priority)
  • Fallback Behavior:
    • If enterpriseIdentifier lookup fails → falls back to hsid
    • If hsid lookup fails → falls back to metadata
    • If metadata lookup fails → customer lookup fails
required
Array of objects [ 1 .. 2 ] items

Payment allocations specifying how the total payment amount is distributed across one or more payment methods. Enables split-tender scenarios (e.g., FSA card + credit card).

Processing Rules
  • At least one allocation is required (minItems: 1).
  • Each allocation must include:
    • amount (minimum 1), and
    • exactly one payment source:
      • paymentMethodId (saved payment method), or
      • paymentMethod (inline payment method details).
    • If both are provided, system will fail the request as invalid.
  • The sum of all allocation amounts must exactly equal the top-level payment amount.
  • Split-tender execution is treated as atomic from a business perspective: if any allocation fails, the system attempts remediation (cancel/reverse) for previously successful allocations to avoid partial completion.

Responses

Request samples

Content type
application/json
{
  • "amount": 15000,
  • "merchantTransactionId": "order-12345",
  • "currencyCode": "USD",
  • "description": "Payment for order #12345",
  • "statementDescriptorSuffix": "ORDER123",
  • "metadata": {
    },
  • "paymentDetails": {
    },
  • "agent": null,
  • "authorizeCard": false,
  • "partialAuthorization": false,
  • "consent": null,
  • "customer": {
    },
  • "paymentAllocations": [
    ]
}

Response samples

Content type
application/json
{
  • "url": "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/payments/550e8400-e29b-41d4-a716-446655440000",
  • "data": {
    }
}

Get Payment by Merchant Transaction Id

This API allows merchants to retrieve payment details using the merchant transaction ID.

It returns the status, amounts, payment method, and other relevant information for the specified transaction.

Use this endpoint to track payment status, reconcile transactions, and manage post-payment operations.

Authorizations:
ProductionStaging
query Parameters
merchantTransactionId
required
string <= 50 characters

Unique identifier that can be used to track this transaction.

This identifier will make sure to prevent duplicate transactions.

header Parameters
X-Merchant-Id
required
string <uuid>

Unique identifier for the merchant. This is used to identify the merchant making the request. Learn More

X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

Specify the Upstream Environment value. Learn More

Only required for Non-Prod Environment

Responses

Response samples

Content type
application/json
{
  • "url": "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/payments/550e8400-e29b-41d4-a716-446655440000",
  • "data": {
    }
}

Get Payment by PaymentId

This API allows merchants to retrieve payment details using the payment ID. It returns the status, amounts, payment method, and other relevant information for the specified transaction.

Use this endpoint to track payment status, reconcile transactions, and manage post-payment operations.

Authorizations:
ProductionStaging
path Parameters
paymentId
required
string <uuid>
header Parameters
X-Merchant-Id
required
string <uuid>

Unique identifier for the merchant. This is used to identify the merchant making the request. Learn More

X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

Specify the Upstream Environment value. Learn More

Only required for Non-Prod Environment

Responses

Response samples

Content type
application/json
{
  • "url": "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/payments/550e8400-e29b-41d4-a716-446655440000",
  • "data": {
    }
}

Cancel payment by PaymentId

Authorizations:
ProductionStaging
path Parameters
paymentId
required
string <uuid>

Id of the payment needs to be cancelled.

header Parameters
X-Merchant-Id
required
string <uuid>

Unique identifier for the merchant. This is used to identify the merchant making the request. Learn More

X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

Specify the Upstream Environment value. Learn More

Only required for Non-Prod Environment

X-Source
string <= 50 characters

Specify the Source System Identifier. Learn More

Request Body schema: application/json
paymentCancellationReason
required
string (PaymentCancellationReason)
Enum: "DUPLICATE" "FRAUDULENT" "REQUESTED_BY_CUSTOMER" "ABANDONED"

Payment cancellation reason.

Processing Rules
  • Required: Yes, if the payment is being cancelled.
  • Value must be one of the following:
    • DUPLICATE: Cancellation due to duplicate payment
    • FRAUDULENT: Cancellation due to suspected fraud
    • REQUESTED_BY_CUSTOMER: Cancellation requested by customer
    • ABANDONED: Cancellation due to abandoned payment (e.g. customer did not complete 3DS authentication)
paymentCancellationMessage
string
Default: null

Additional context for the cancellation.

Responses

Request samples

Content type
application/json
{
  • "paymentCancellationReason": "DUPLICATE",
  • "paymentCancellationMessage": "Customer requested cancellation"
}

Response samples

Content type
application/json
{
  • "url": "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/payments/550e8400-e29b-41d4-a716-446655440000",
  • "data": {
    }
}

Capture payment by PaymentId

Capture an authorized payment by its ID.

This endpoint captures card payments that are in AUTHORIZED state. It supports full capture, partial capture, and capturing specific allocations individually in split-tender payments.

Authorizations:
ProductionStaging
path Parameters
paymentId
required
string <uuid>

Platform-generated unique payment identifier of the payment to capture.

header Parameters
X-Merchant-Id
required
string <uuid>

Unique identifier for the merchant. This is used to identify the merchant making the request. Learn More

X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

Specify the Upstream Environment value. Learn More

Only required for Non-Prod Environment

X-Source
string <= 50 characters

Specify the Source System Identifier. Learn More

Request Body schema: application/json
Array of objects or null (CaptureAllocation)
Default: null

List of allocations to be captured.

Processing Rules
  • Applicability: For partial capture or capturing specific allocations individually.
  • Omitted allocations are automatically canceled with reason CCG_AUTOMATED_CANCEL This enables partial fulfillment scenarios
object or null (Metadata) <= 20 properties
Default: null

Additional metadata to merge with existing payment metadata during capture.

Processing Rules
  • Constraints:
    • Combined count (existing + new metadata) must not exceed 20 entries
    • Key length: 1-40 characters
    • Value length: 1-100 characters

Responses

Request samples

Content type
application/json
{
  • "paymentAllocations": null,
  • "metadata": null
}

Response samples

Content type
application/json
{
  • "url": "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/payments/550e8400-e29b-41d4-a716-446655440000",
  • "data": {
    }
}

Create Refund

Submit a refund request for a payment.

Supported refund types:

  • Linked refunds: Issued against a specific payment, allowing for full or partial refund amounts. Applicable for payments completed by authenticated and guest users.
  • Unlinked refunds: Processed directly to a stored payment method in the wallet against an existing user without referencing a particular payment.

Learn more

Authorizations:
ProductionStaging
header Parameters
X-Merchant-Id
required
string <uuid>

Unique identifier for the merchant. This is used to identify the merchant making the request. Learn More

X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

Specify the Upstream Environment value. Learn More

Only required for Non-Prod Environment

X-Source
string <= 50 characters

Specify the Source System Identifier. Learn More

Request Body schema: application/json
required
paymentId
string or null <uuid>
Default: null

Original payment ID to refund against.

Processing Rules
  • Required: Yes, for linked refund
  • Payment must exist and have status COMPLETED.
  • Provide either paymentId or refundAllocations[0].paymentMethodId.
    • The request must not include both fields.
    • Exactly one of the two fields is required.
reason
string or null
Default: null
Enum: "REQUESTED_BY_CUSTOMER" "DUPLICATE" "FRAUDULENT"

Reason for processing the refund.

Processing Rules
  • When provided, the value must be one of the allowed values below:
    • REQUESTED_BY_CUSTOMER: Customer requested the refund
    • DUPLICATE: Customer was charged multiple times for the same product/service
    • FRAUDULENT: Payment was found to be fraudulent
merchantTransactionId
required
string <= 50 characters

Unique identifier provided by the merchant to prevent duplicate refund submissions. Learn more

  • Must be unique per merchant across all refund requests
object or null (MetadataRequest) <= 20 properties
Default: null

Set of key-value pairs that you can attach to an object.

This can be useful for storing additional information about the object in a structured format.

Processing Rules
  • Constraints:
    • Key length: 1-40 characters
    • Value length: 1-100 characters
  • Non-PII recommendation: Avoid storing sensitive personal information (SSN, DOB, full card numbers).
Array of objects or (RefundAllocationsRequest)
Default: null

Specifies how the refund amount should be distributed across one or more payment methods.

Processing Rules
  • Required: Yes, for partial linked and un-linked refunds.
  • Constraints:
    • Max items: 2 for linked refunds
    • Max items: 1 for un-linked refunds.
  • When not provided, linked refunds will be processed as full refunds.
object or null (AgentRequest)
Default: null

Agent information provided by the caller. Learn More

object or null (CustomerRequest)
Default: null

Customer details for identification and contact purposes. Includes identifiers (hsid, enterpriseIdentifier), contact information (email, phone), and custom metadata.

Processing Rules
  • Required: Yes, for un-linked refunds.
  • Customer Identification:
    • At least one customer identifier must be provided for customer lookup:
    • enterpriseIdentifier
    • hsid
    • metadata
  • Lookup Priority: When multiple identifiers are provided, below is the lookup priority order:
    • enterpriseIdentifier (highest priority)
    • hsid
    • metadata (lowest priority)
  • Fallback Behavior:
    • If enterpriseIdentifier lookup fails → falls back to hsid
    • If hsid lookup fails → falls back to metadata

Responses

Request samples

Content type
application/json
{
  • "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "reason": "REQUESTED_BY_CUSTOMER",
  • "merchantTransactionId": "564b6ee6",
  • "metadata": {
    },
  • "refundAllocations": null,
  • "agent": {
    },
  • "customer": {
    }
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "data": {
    }
}

Get Refund by RefundId

Authorizations:
ProductionStaging
path Parameters
refund-id
required
string <uuid>
header Parameters
X-Merchant-Id
required
string <uuid>

Unique identifier for the merchant. This is used to identify the merchant making the request. Learn More

X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

Specify the Upstream Environment value. Learn More

Only required for Non-Prod Environment

Responses

Response samples

Content type
application/json
{
  • "url": "string",
  • "data": {
    }
}

User

Provides a comprehensive set of operations for widget, enabling them to initiate new payment transactions. These operations are designed to support the complete payment, manage wallet, ensuring flexibility and control over payment management for Convenient Checkout UI.

Create Child CheckOut Session

Authorizations:
ProductionStaging
path Parameters
sessionId
required
string

Parent session ID

header Parameters
X-Merchant-Id
required
string <uuid>

Unique identifier for the merchant. This is used to identify the merchant making the request. Learn More

Request Body schema: application/json
required
email
string <email>

Customer's email address. Must be in a valid email format (e.g., example@domain.com).

object (PhoneNumber)
childSessionMode
string
Enum: "TEXT_TO_ADD" "EMAIL_TO_ADD" "TEXT_TO_PAY" "EMAIL_TO_PAY"

Specifies the mode of the child checkout session, such as text or email for adding or paying Learn more

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "phone": {
    },
  • "childSessionMode": "TEXT_TO_ADD"
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "data": {
    }
}

Get CheckOut Session

path Parameters
sessionId
required
string

Session ID

query Parameters
init
boolean

If true, the appearance object will be returned; otherwise, the appearance object is null.

Responses

Response samples

Content type
application/json
{
  • "url": "string",
  • "data": {
    }
}

Cancel CheckOut Session

Authorizations:
ProductionStaging
path Parameters
sessionId
required
string

Session ID

header Parameters
X-Merchant-Id
required
string <uuid>

Unique identifier for the merchant. This is used to identify the merchant making the request. Learn More

Responses

Response samples

Content type
application/json
{
  • "url": "string",
  • "data": {
    }
}

Create Payment

This API enables end users, through the Convenient Checkout UI, to create a payment for the current checkout session. It supports multiple payment methods and wallet-based flows.

Supported Payment Flows

Single Payment

  • Pay With Wallet - Pay using a stored payment method
  • Pay & Save - Process payment and save the method for future use
  • One Time Pay - Pay using a payment method without saving it to the wallet
  • Guest Pay - Pay without creating a wallet or providing customer information
  • Supported payment methods:
    • CARD
    • BANK_ACCOUNT
Authorizations:
ProductionStaging
header Parameters
X-Merchant-Id
required
string <uuid>

Unique identifier for the merchant. This is used to identify the merchant making the request. Learn More

X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

Specify the Upstream Environment value. Learn More

Only required for Non-Prod Environment

X-Checkout-Id
required
string

sessionId

X-Customer-Id
required
string

wallet Customer Id

Request Body schema: application/json
required
amount
required
integer <int64> [ 1 .. 100000000 ]

Total payment amount in cents.

Must exactly equal the sum of all paymentAllocations[*].amount values

merchantTransactionId
required
string [ 1 .. 50 ] characters

Unique identifier provided by the merchant for the payment. Serves as the idempotency key to prevent duplicate payment processing.

Processing Rules
  • Must be unique per merchant.
  • Allows the merchant to retry the same payment request using the same merchantTransactionId up to 4 times (5 total attempts including the initial one).
  • After 4 retries (5th attempt), a new merchantTransactionId must be used.
currencyCode
string
Default: "USD"
Value: "USD"

ISO 4217 currency code specifying the currency for the payment amount.

USD: United States Dollar (only supported currency)

description
string or null <= 100 characters
Default: null

Text description providing context about the payment for internal tracking, receipts, or administrative purposes. Does not appear on customer's bank statement.

statementDescriptorSuffix
string or null <= 10 characters ^(?=.*[A-Za-z])[A-Za-z0-9 .-]{1,10}$
Default: null

Suffix appended to the merchant's default statement descriptor on the customer's bank statement. Full descriptor format: [Merchant Descriptor] * [Suffix].

object or null (MetadataRequest) <= 20 properties
Default: null

Set of key-value pairs that you can attach to an object.

This can be useful for storing additional information about the object in a structured format.

Processing Rules
  • Constraints:
    • Key length: 1-40 characters
    • Value length: 1-100 characters
  • Non-PII recommendation: Avoid storing sensitive personal information (SSN, DOB, full card numbers).
object or null (PaymentDetailsRequest)
Default: null

Healthcare-related payment information for FSA/HSA card processing including qualified medical amounts, vision amounts, and prescription details.

Processing Rules
  • Applicability: Only applicable for CARD payment methods. Ignored for BANK_ACCOUNT payment method.
  • Required: Yes, for CARD payment methods involving FSA/HSA cards.
object
Default: null

Agent information provided by the caller. Learn More

authorizeCard
boolean
Default: false

Controls whether to use a two-step authorization flow (hold funds) or one-step authorization + capture (charge immediately).

Processing Rules
  • Applicability: CARD payment method only. Ignored for BANK_ACCOUNT payment types.
  • Constraint: When authorizeCard is true, partialAuthorization should also be true — the two flags are complementary and should not be used in isolation.

When true — two-step flow (authorize, then capture):

  • Funds are held (authorized) but not immediately charged (captured)
  • Payment status transitions to AUTHORIZED and awaits explicit capture
  • A subsequent POST /payments/{paymentId}/capture call is required to complete the charge
  • Authorization holds expire after 7 days; the payment must be re-authorized after expiry
  • Typical use cases: hotel/rental pre-authorization holds, split-tender with deferred capture, payment verification

When false — one-step flow (authorize + capture):

  • Authorization and capture occur simultaneously in a single operation
  • The customer's card is charged immediately
  • Payment status transitions to COMPLETED on success
partialAuthorization
boolean
Default: false

Controls whether the payment processor can authorize a partial amount when the full requested amount is not available on the card. Particularly important for healthcare cards (FSA/HSA) and split-tender scenarios.

Processing Rules
  • Applicability: CARD payment method only. Ignored for BANK_ACCOUNT payment types.
  • Constraint: Should be set to true when authorizeCard is true.

When true:

  • The card issuer may approve a lesser amount than requested
  • Payment succeeds with the authorized (partial) amount; status transitions to COMPLETED or AUTHORIZED
  • The merchant is responsible for handling the remaining balance (e.g., charging a second payment method)
  • Particularly important for healthcare cards (FSA/HSA) where the eligible amount may be less than the total

When false:

  • The full requested amount must be authorized or the payment is declined
  • No partial approvals are accepted from the card issuer
authRequired
boolean
Default: false

Indicates whether additional customer authentication (for example, SCA / 3DS) is required for the payment. When enabled, the customer may be prompted to complete an authentication challenge during processing.

Processing Rules
  • Required: Yes, for SCA/3DS CARD payments.
  • If true:
    • authentication is enforced when required (for example, 3DS challenge). Payment proceeds only after successful authentication.
  • If false:
    • no explicit authentication is required; the system attempts auto-confirmation (default behavior).
object (ConsentRequest)
Default: null

Customer consent details required for BANK_ACCOUNT payment methods. Captures consent identifier, consent text, collection timestamp, and collection method details.

Processing Rules
  • Applicability: This consent schema is applicable for BANK_ACCOUNT payment methods. Defaulted to null for CARD payment methods.
  • Constraint: When consent type is PPD, the agent field at payment level is required.
  • Consent records are immutable once created and should be retained for compliance purposes.
object or null (CustomerRequest)
Default: null

Customer details for identification and contact purposes. Includes identifiers (hsid, enterpriseIdentifier), contact information (email, phone), and custom metadata.

Processing Rules

Customer Identification:

  • At least one customer identifier must be provided for customer lookup:
    • enterpriseIdentifier
    • hsid
    • metadata
  • Lookup Priority: When multiple identifiers are provided, below is the lookup priority order:
    • enterpriseIdentifier (highest priority)
    • hsid
    • metadata (lowest priority)
  • Fallback Behavior:
    • If enterpriseIdentifier lookup fails → falls back to hsid
    • If hsid lookup fails → falls back to metadata
    • If metadata lookup fails → customer lookup fails
required
Array of objects or objects [ 1 .. 2 ] items

Payment allocations specifying how the total payment amount is distributed across one or more payment methods. Enables split-tender scenarios (e.g., FSA card + credit card).

Processing Rules
  • At least one allocation is required (minItems: 1).
  • Each allocation must include:
    • amount (minimum 1), and
    • exactly one payment source:
      • paymentMethodId (saved payment method), or
      • paymentMethod (inline payment method details).
    • If both are provided, system will fail the request as invalid.
  • The sum of all allocation amounts must exactly equal the top-level payment amount.
  • Split-tender execution is treated as atomic from a business perspective: if any allocation fails, the system attempts remediation (cancel/reverse) for previously successful allocations to avoid partial completion.

Responses

Request samples

Content type
application/json
{
  • "amount": 15000,
  • "merchantTransactionId": "order-12345",
  • "currencyCode": "USD",
  • "description": "Payment for order #12345",
  • "statementDescriptorSuffix": "ORDER123",
  • "metadata": {
    },
  • "paymentDetails": {
    },
  • "agent": null,
  • "authorizeCard": false,
  • "partialAuthorization": false,
  • "authRequired": true,
  • "consent": {
    },
  • "customer": {
    },
  • "paymentAllocations": [
    ]
}

Response samples

Content type
application/json
{
  • "url": "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/payments/550e8400-e29b-41d4-a716-446655440000",
  • "data": {
    }
}

Get Payment by PaymentId

This API enables end users, through the Convenient Checkout UI, track payment status, reconcile transactions, and manage post-payment operations for a specific payment.

Supported Payment Flows

Single Payment

  • Pay With Wallet - Pay using a stored payment method
  • Pay & Save - Process payment and save the method for future use
  • One Time Pay - Pay using a payment method without saving it to the wallet
  • Supported payment methods:
    • CARD
    • BANK_ACCOUNT
Authorizations:
ProductionStaging
path Parameters
paymentId
required
string <uuid>
header Parameters
X-Merchant-Id
required
string <uuid>

Unique identifier for the merchant. This is used to identify the merchant making the request. Learn More

X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

Specify the Upstream Environment value. Learn More

Only required for Non-Prod Environment

X-Checkout-Id
required
string

sessionId

X-Customer-Id
required
string

wallet Customer Id

Responses

Response samples

Content type
application/json
{
  • "url": "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/payments/550e8400-e29b-41d4-a716-446655440000",
  • "data": {
    }
}

Merchant - PCI

Provides operations for merchants with PCI scope, enabling them to create and retrieve payment methods in the wallet, and initiate payments. These operations are designed to support merchants in securely handling payment information without exposing sensitive card data, ensuring compliance with PCI requirements.

Create Payment

This API enables merchants to create a payment transaction.

Supported Payment Flows

Single Payment

  • Pay & Save - Process payment and save the method for future use
  • One Time Pay - Pay using a payment method without saving it to the wallet
  • Supported payment methods:
    • CARD
    • BANK_ACCOUNT
Authorizations:
ProductionStaging
header Parameters
X-Merchant-Id
required
string <uuid>

Unique identifier for the merchant. This is used to identify the merchant making the request. Learn More

X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

Specify the Upstream Environment value. Learn More

Only required for Non-Prod Environment

X-Source
string <= 50 characters

Specify the Source System Identifier. Learn More

Request Body schema: application/json
required
amount
required
integer <int64> [ 1 .. 100000000 ]

Total payment amount in cents.

Must exactly equal the sum of all paymentAllocations[*].amount values

merchantTransactionId
required
string [ 1 .. 50 ] characters

Unique identifier provided by the merchant for the payment. Serves as the idempotency key to prevent duplicate payment processing.

Processing Rules
  • Must be unique per merchant.
  • Allows the merchant to retry the same payment request using the same merchantTransactionId up to 4 times (5 total attempts including the initial one).
  • After 4 retries (5th attempt), a new merchantTransactionId must be used.
currencyCode
string
Default: "USD"
Value: "USD"

ISO 4217 currency code specifying the currency for the payment amount.

USD: United States Dollar (only supported currency)

description
string or null <= 100 characters
Default: null

Text description providing context about the payment for internal tracking, receipts, or administrative purposes. Does not appear on customer's bank statement.

statementDescriptorSuffix
string or null <= 10 characters ^(?=.*[A-Za-z])[A-Za-z0-9 .-]{1,10}$
Default: null

Suffix appended to the merchant's default statement descriptor on the customer's bank statement. Full descriptor format: [Merchant Descriptor] * [Suffix].

object or null (MetadataRequest) <= 20 properties
Default: null

Set of key-value pairs that you can attach to an object.

This can be useful for storing additional information about the object in a structured format.

Processing Rules
  • Constraints:
    • Key length: 1-40 characters
    • Value length: 1-100 characters
  • Non-PII recommendation: Avoid storing sensitive personal information (SSN, DOB, full card numbers).
object or null (PaymentDetailsRequest)
Default: null

Healthcare-related payment information for FSA/HSA card processing including qualified medical amounts, vision amounts, and prescription details.

Processing Rules
  • Applicability: Only applicable for CARD payment methods. Ignored for BANK_ACCOUNT payment method.
  • Required: Yes, for CARD payment methods involving FSA/HSA cards.
object
Default: null

Agent information provided by the caller. Learn More

authorizeCard
boolean
Default: false

Controls whether to use a two-step authorization flow (hold funds) or one-step authorization + capture (charge immediately).

Processing Rules
  • Applicability: CARD payment method only. Ignored for BANK_ACCOUNT payment types.
  • Constraint: When authorizeCard is true, partialAuthorization should also be true — the two flags are complementary and should not be used in isolation.

When true — two-step flow (authorize, then capture):

  • Funds are held (authorized) but not immediately charged (captured)
  • Payment status transitions to AUTHORIZED and awaits explicit capture
  • A subsequent POST /payments/{paymentId}/capture call is required to complete the charge
  • Authorization holds expire after 7 days; the payment must be re-authorized after expiry
  • Typical use cases: hotel/rental pre-authorization holds, split-tender with deferred capture, payment verification

When false — one-step flow (authorize + capture):

  • Authorization and capture occur simultaneously in a single operation
  • The customer's card is charged immediately
  • Payment status transitions to COMPLETED on success
partialAuthorization
boolean
Default: false

Controls whether the payment processor can authorize a partial amount when the full requested amount is not available on the card. Particularly important for healthcare cards (FSA/HSA) and split-tender scenarios.

Processing Rules
  • Applicability: CARD payment method only. Ignored for BANK_ACCOUNT payment types.
  • Constraint: Should be set to true when authorizeCard is true.

When true:

  • The card issuer may approve a lesser amount than requested
  • Payment succeeds with the authorized (partial) amount; status transitions to COMPLETED or AUTHORIZED
  • The merchant is responsible for handling the remaining balance (e.g., charging a second payment method)
  • Particularly important for healthcare cards (FSA/HSA) where the eligible amount may be less than the total

When false:

  • The full requested amount must be authorized or the payment is declined
  • No partial approvals are accepted from the card issuer
object or null or object or null (ConsentRequest)
Default: null

Customer consent details required for BANK_ACCOUNT payment methods. Captures consent identifier, consent text, collection timestamp, and collection method details.

Processing Rules
  • Applicability: This consent schema is applicable for BANK_ACCOUNT payment methods. Defaulted to null for CARD payment methods.
  • Constraint: When consent type is PPD, the agent field at payment level is required.
  • Consent records are immutable once created and should be retained for compliance purposes.
required
object (CustomerRequest)

Customer details for identification and contact purposes. Includes identifiers (hsid, enterpriseIdentifier), contact information (email, phone), and custom metadata.

Processing Rules

Customer Identification:

  • At least one customer identifier must be provided for customer lookup:
    • enterpriseIdentifier
    • hsid
    • metadata
  • Lookup Priority: When multiple identifiers are provided, below is the lookup priority order:
    • enterpriseIdentifier (highest priority)
    • hsid
    • metadata (lowest priority)
  • Fallback Behavior:
    • If enterpriseIdentifier lookup fails → falls back to hsid
    • If hsid lookup fails → falls back to metadata
    • If metadata lookup fails → customer lookup fails
required
Array of objects [ 1 .. 2 ] items

Responses

Request samples

Content type
application/json
{
  • "amount": 15000,
  • "merchantTransactionId": "order-12345",
  • "currencyCode": "USD",
  • "description": "Payment for order #12345",
  • "statementDescriptorSuffix": "ORDER123",
  • "metadata": {
    },
  • "paymentDetails": {
    },
  • "agent": null,
  • "authorizeCard": false,
  • "partialAuthorization": false,
  • "consent": null,
  • "customer": {
    },
  • "paymentAllocations": [
    ]
}

Response samples

Content type
application/json
{
  • "url": "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/payments/550e8400-e29b-41d4-a716-446655440000",
  • "data": {
    }
}