Checking access…

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.

Applicable Session Modes
  • PAYMENT_WITH_WALLET: Session is created for processing a payment using a stored payment method in the wallet. The session will be used to present the user with their saved payment methods and facilitate the checkout process.
  • PAYMENT_AND_SAVE: Session is created for processing a payment and saving the new payment method to the wallet. The session will guide the user through entering their payment details, processing the payment, and securely storing the new payment method for future use.
  • PAYMENT: Session is created for processing a one-time payment without saving the payment method. The session will allow the user to enter their payment details and complete the transaction without storing the payment method in the wallet.
  • WALLET: Session is created for wallet management operations, such as adding or managing stored payment methods. The session will provide the necessary context for securely handling payment method information and facilitating wallet-related interactions.
  • PAYMENT_METHOD_ENTRY: Session is created for entering new payment method details without processing a payment. The session will allow the user to input their payment information, which can then be saved to the wallet for future transactions.
  • PAYMENT_METHOD_SELECT: Session is created for selecting from existing payment methods in the wallet without processing a payment. The session will present the user with their saved payment methods and allow them to choose one for future transactions.
  • PAYMENT_METHOD_DISPLAY: Session is created for displaying existing payment methods in the wallet without processing a payment. The session will show the user their saved payment methods for informational purposes without allowing selection or entry of new payment details.
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.

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

Specify the Upstream Environment value.

Only required for Non-Prod Environment

X-Source
string <= 50 characters

Specify the Source System Identifier.

Request Body schema: application/json
required
object or null (SessionPaymentMethod)
Default: null

References a saved payment method from the customer's wallet for wallet-based payment scenarios.

  • Required:
    • PAYMENT_METHOD_DISPLAY mode.
object or null (SessionPaymentRequest)
Default: null

Payment payload for transaction creation.

Processing Rules
  • Applicability:
    • Session flows that create a payment transaction during session processing such as PAYMENT and PAYMENT_WITH_WALLET.
object or null (CustomerRequest)
Default: null

Customer context used for user-scoped session flows.

Processing Rules
  • Applicability:
    • Session modes that require customer context (for example, PAYMENT_WITH_WALLET).
  • For session flows that support both customer and guest contexts, the presence of the customer object indicates a customer-scoped session, while its absence (or null value) indicates a guest session.
object or null (SessionConfig)
Default: null

Session configuration options.

object or null (appearance)
Default: null

Appearance configuration for the checkout session

object or null (AgentRequest)
Default: null

Agent information provided by the caller.

Responses

Request samples

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

Response samples

Content type
application/json
Example
{}

Get Session

Retrieves merchant-facing session status.

Authorizations:
ProductionStaging
path Parameters
sessionId
required
string <uuid>
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Unique identifier of the session which needs to be retrieved. Generated when the session is created.

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

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

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

Specify the Upstream Environment value.

Only required for Non-Prod Environment

Responses

Response samples

Content type
application/json
{
  • "url": "string",
  • "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.

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

Specify the Upstream Environment value.

Only required for Non-Prod Environment

X-Source
string <= 50 characters

Specify the Source System Identifier.

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

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 or null (AgentRequest)
Default: null

Agent information provided by the caller.

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 (schemas-ConsentRequest)

Customer consent details required for ACH/bank account payments.

Processing Rules
  • Applicability: Required when payment method type is BANK_ACCOUNT. Null allowed for CARD-only payments.
  • Identifier field depends on payment flow:
    • Session flow (X-Checkout-Id header present): merchantConsentText is required.
    • Merchant-initiated or guest flow (no X-Checkout-Id): merchantConsentId is required.
  • Constraint: When consent type is PPD, the agent field at the payment level is required. No collectionDetails sub-object is needed beyond type.
  • Constraint: When consent type is TEL, the tel object must be non-null. inboundPhoneNumber and its sub-fields are optional.
  • 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 Saved_Payment_Method (object) or Inline_Payment_Method (object) (PaymentAllocationRequestCommon) [ 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.

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

Specify the Upstream Environment value.

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.

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

Specify the Upstream Environment value.

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

⚠️ Under Active Development — This endpoint is not yet implemented and will be available in a future release. Calling this endpoint returns 501 Not Implemented in lower environments (dev / test / reg / perf) and 503 Service Unavailable in stage and prod.

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.

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

Specify the Upstream Environment value.

Only required for Non-Prod Environment

X-Source
string <= 50 characters

Specify the Source System Identifier.

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 or null
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 (omit amount) or partial capture (specify amount).

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.

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

Specify the Upstream Environment value.

Only required for Non-Prod Environment

X-Source
string <= 50 characters

Specify the Source System Identifier.

Request Body schema: application/json
Array of objects

Array of payment allocation objects for distributed payment capture.

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": [
    ],
  • "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.
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.

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

Specify the Upstream Environment value.

Only required for Non-Prod Environment

X-Source
string <= 50 characters

Specify the Source System Identifier.

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.

  • 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 Linked Refund Allocation (object) or Unlinked Refund Allocation (object) 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.

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.

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

Specify the Upstream Environment value.

Only required for Non-Prod Environment

Responses

Response samples

Content type
application/json
{
  • "url": "string",
  • "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.

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

Specify the Upstream Environment value.

Only required for Non-Prod Environment

X-Source
string <= 50 characters

Specify the Source System Identifier.

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

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 or null (AgentRequest)
Default: null

Agent information provided by the caller.

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 (schemas-ConsentRequest)

Customer consent details required for ACH/bank account payments.

Processing Rules
  • Applicability: Required when payment method type is BANK_ACCOUNT. Null allowed for CARD-only payments.
  • Identifier field depends on payment flow:
    • Session flow (X-Checkout-Id header present): merchantConsentText is required.
    • Merchant-initiated or guest flow (no X-Checkout-Id): merchantConsentId is required.
  • Constraint: When consent type is PPD, the agent field at the payment level is required. No collectionDetails sub-object is needed beyond type.
  • Constraint: When consent type is TEL, the tel object must be non-null. inboundPhoneNumber and its sub-fields are optional.
  • 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 Saved_Payment_Method (object) or Inline_Payment_Method (object) (PaymentAllocationRequestCommon) [ 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": {
    }
}

Setup Payment Method

This API enables merchants with PCI scope to set up and save a payment method for future transactions.

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.

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

Specify the Upstream Environment value.

Only required for Non-Prod Environment

X-Source
string <= 50 characters

Specify the Source System Identifier.

Request Body schema: application/json
required
paymentMethodType
string (PaymentMethodType)
Enum: "CARD" "BANK_ACCOUNT"

Type of payment method.

required
object (PaymentMethodRequest)

Payment method details which needs to be set up. This can either be a new payment method (with details provided in this request) or an existing vaulted payment method (identified by vendorPaymentMethodId) that should be linked to the customer.

paymentId
string <uuid>

Optional reference to an existing payment

savePaymentMethod
boolean

Whether to persist the payment method after setup

object or null (MetadataRequest) <= 20 properties

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).

Responses

Request samples

Content type
application/json
{
  • "paymentMethodType": "CARD",
  • "paymentMethod": {
    },
  • "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  • "savePaymentMethod": true,
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "url": "string",
  • "metadata": {
    }
}

Get Setup Payment Method

Retrieves the status and details of a setup payment method by its identifier.

Authorizations:
ProductionStaging
path Parameters
setupPaymentMethodId
required
string <uuid>

Unique identifier of the setup payment method.

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

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

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

Specify the Upstream Environment value.

Only required for Non-Prod Environment

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "url": "string",
  • "metadata": {
    }
}

Merchant-Wallet-Management

Provides operations for managing wallet payment methods, including setup and retrieval flows for stored payment methods. These operations are designed to support merchant wallet maintenance while preserving PCI-safe handling of payment data.

Get payment method by ID

Authorizations:
ProductionStaging
path Parameters
id
required
string <uuid>

Payment method UUID

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

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

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

Specify the Upstream Environment value.

Only required for Non-Prod Environment

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "url": "string",
  • "metadata": {
    }
}

Update payment method

Authorizations:
ProductionStaging
path Parameters
id
required
string <uuid>

Payment method UUID

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

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

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

Specify the Upstream Environment value.

Only required for Non-Prod Environment

x-source
string <= 50 characters

Source identifier (max 50 characters)

Request Body schema: application/json
required
isDefault
boolean

Flag indicating if this payment method should be set as default

nickname
string or null <= 30 characters ^(?!\s{2,})(?=.{0,30}$)([a-zA-Z0-9]+(\s[a-zA-...
Default: null

Friendly name assigned by the customer to identify this payment method in their wallet (e.g., "My Primary Card", "Work Account", "HSA Card"). When omitted or null, no nickname is saved.

Processing Rules
  • Optional: Field for customers to personalize their saved payment methods.
  • Recommended: Not to contain sensitive payment method details like card numbers or bank account numbers.
object (CardRequest)
Deprecated

Deprecated legacy update object; use paymentMethodDetails instead

object or null

Agent performing the update on behalf of the customer

source
string <= 50 characters

Optional source identifier for update operations.

object (PaymentMethod)

Polymorphic update details object

Responses

Request samples

Content type
application/json
{
  • "isDefault": true,
  • "nickname": null,
  • "card": {
    },
  • "agent": {
    },
  • "source": "string",
  • "paymentMethodDetails": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ],
  • "url": "string",
  • "metadata": {
    }
}

Delete payment method

Authorizations:
ProductionStaging
path Parameters
id
required
string <uuid>

Payment method UUID

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

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

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

Specify the Upstream Environment value.

Only required for Non-Prod Environment

x-source
string <= 50 characters

Source identifier (max 50 characters)

Request Body schema: application/json
optional
object or null

Agent performing the deletion on behalf of the customer

firstName
string or null <= 50 characters
Default: null

Agent's first name.

lastName
string or null <= 50 characters
Default: null

Agent's last name.

required
string or string

Agent identity. Accepts either an MSID or an email/UPN. Existing MSID-only integrations remain supported.

Responses

Request samples

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

Search Payment Methods

Search for stored payment methods associated with a customer by identity (email or HSID).

Returns all active payment methods in the customer's wallet that are accessible to the merchant.

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.

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

Specify the Upstream Environment value.

Only required for Non-Prod Environment

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

Customer whose payment methods are being searched

object or null

Agent performing the search on behalf of the customer

Responses

Request samples

Content type
application/json
{
  • "customer": {
    },
  • "agent": {
    }
}

Response samples

Content type
application/json
[ ]