Skip to main content
API docs by Redocly

Convenient Checkout API (v2)

Download OpenAPI specification:Download

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

Convenient Checkout Gateway API - NonProd

API Error Codes Reference

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. The request must include the total amount, merchant transaction ID, and payment splits.

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 ] ^[1-9]\d*$

The total transaction amount in cents (USD).Learn More

Processing Rules

This value must exactly equal the sum of the amounts specified in paymentAllocations[:].amount.

merchantTransactionId
required
string <= 50 characters

Unique identifier that can be used to track this transaction. This identifier will make sure that there wont be any duplicate transaction. Learn More.

authorizeCard
boolean
Default: false

Authorizes the specified amount on the card without capturing funds immediately.

Processing Rules

About: When set to true, the credit card will be authorized for the specified amount, but the funds are not captured until a subsequent Capture API call is made.

Applicability: Only applicable when the paymentMethod.type = CARD.

The authorization remains valid for 7 days; after this period, the hold may expire and a new authorization may be required. To complete the transaction, the Capture API must be called after authorization.

Note: For any payment—single or split—involving ACH, the transaction will always be processed as a SALE, regardless of the value of the authorizeCard parameter.

partialAuthorization
boolean
Default: false

Allows the card issuer to approve a partial authorization if the full amount is not available.

Processing Rules

About: When set to true, the card issuer may approve a payment for less than the requested amount if the full amount cannot be authorized (e.g., insufficient funds).

Applicability: Only applicable when the paymentMethod.type = CARD and authorizeCard = true.

If enabled, the payment may be partially authorized and the merchant can decide whether to accept or decline the partial amount.

description
string <= 100 characters

An arbitrary string useful to user to track payments. Learn More

statementDescriptorSuffix
string <= 10 characters ^(?=.*[a-zA-Z])[a-zA-Z0-9 \-.]{0,10}$

Statement descriptors explain charges or payments on bank statements. Using clear and accurate statement descriptors can reduce chargebacks and disputes. Learn More.

Processing Rules
  • Must contain atleast one alphabetic character.
  • only of alphanumeric characters, spaces, hyphens, and periods.
  • Allowed Maximum Length is 10
  • Doesn't contain any of the following special characters: <, >, , ' " *.
object (IIASPaymentDetails)

IIAS (Inventory Information Approval System) Payments refer to transactions made using a healthcare payment card (such as a Flexible Spending Account or Health Savings Account card) at merchants equipped with IIAS. The IIAS system automatically verifies and approves eligible healthcare-related purchases in real-time, ensuring compliance with IRS regulations. Learn More

object (metadataRequest) <= 20 properties

Key-value pairs containing payment metadata, such as Order ID, Invoice date. Learn More

Processing Rules
  • A maximum of 20 metadata entries can be included per payment request. This is enforced by the API.
  • Each metadata key can be up to 40 characters in length, and each value can be up to 100 characters.
  • Only string values are supported for both keys and values.
  • Metadata should be used for non-sensitive, non-regulated information only. Do not include PHI, card numbers, or other sensitive data.
  • Examples: {'orderId': '12345', 'invoiceDate': '2025-08-22', 'OrderType': 'Gift purchase'}
object (components-schemas-Consent)
  • Captures the customer's or agent's agreement. Learn More
  • Consent is required when paymentMethod.type=BANK_ACCOUNT.
  • Consent records are immutable once created and should be retained for compliance purposes.
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.

Array of objects (paymentAllocationsRequest) <= 2 items

Array of payment splits for this transaction. Each entry specifies the payment method to use and the amount allocated to that split. Learn More

Processing Rules
  • Maximum of 2 splits allowed.
  • Each Splits must include paymentMethodId and Amount greater than zero
object (Agent)

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

Responses

Request samples

Content type
application/json
{
  • "amount": 1,
  • "merchantTransactionId": "string",
  • "authorizeCard": false,
  • "partialAuthorization": false,
  • "description": "string",
  • "statementDescriptorSuffix": "string",
  • "paymentDetails": {
    },
  • "metadata": {
    },
  • "consent": {
    },
  • "customer": {
    },
  • "paymentAllocations": [
    ],
  • "agent": {
    }
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "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 that there wont be any duplicate transaction.

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": {
    }
}

Get Payment by PaymentId

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
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": "string",
  • "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
Enum: "DUPLICATE" "FRAUDULENT" "REQUESTED_BY_CUSTOMER" "ABANDONED"

Payment cancellation reason. Learn More

paymentCancellationMessage
string

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": "string",
  • "data": {
    }
}

Create Refund

This API enables merchants to process refunds for previously completed payments. Refunds can be issued for either the full payment amount or a partial amount, based on the request. The refunded amount is returned to the original payment method used for the transaction. 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 <uuid>

payment.id of the payment that needs refund

Processing Rules - Payment requested for refund should be in completed status
paymentMethodId
string <uuid>

The unique identifier of the payment method to which the credit will be issued.

Processing Rules

This is used when issuing a credit to the customer that is not tied to a specific payment. This field is not applicable when a specific paymentId is provided.

merchantTransactionId
required
string <= 50 characters

Unique identifier that can be used to track this transaction. This identifier will make sure that there wont be any duplicate transaction. Learn More.

For refunds, the value of merchantTransactionId is different from the payment.merchantTransactionId.

reason
required
string
Enum: "REQUESTED_BY_CUSTOMER" "DUPLICATE" "FRAUDULENT"

Specifies the rationale for issuing a refund

Array of objects (RefundAllocationsRequest) >= 1

A list specifying the allocation details for the refund. This is used to define how the refund amount should be distributed, particularly for partial refunds.

Processing Rules
  • If this object is omitted, the system will automatically process a full refund for the specified transaction ID i.e paymentId
  • RefundAllocations is required for partial refunds
object (metadataRequest) <= 20 properties

Key-value pairs containing payment metadata, such as Order ID, Invoice date. Learn More

Processing Rules
  • A maximum of 20 metadata entries can be included per payment request. This is enforced by the API.
  • Each metadata key can be up to 40 characters in length, and each value can be up to 100 characters.
  • Only string values are supported for both keys and values.
  • Metadata should be used for non-sensitive, non-regulated information only. Do not include PHI, card numbers, or other sensitive data.
  • Examples: {'orderId': '12345', 'invoiceDate': '2025-08-22', 'OrderType': 'Gift purchase'}
object (Agent)

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

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.

Responses

Request samples

Content type
application/json
{
  • "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  • "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
  • "merchantTransactionId": "string",
  • "reason": "REQUESTED_BY_CUSTOMER",
  • "refundAllocations": [
    ],
  • "metadata": {
    },
  • "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

sessionId

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

sessionId

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 merchants to create a payment transaction. It supports various payment methods and allows for split payments. The request must include the total amount, merchant transaction ID, and payment splits.

Supported Session Modes:

  • PAYMENT
  • PAYMENT_WITH_WALLET
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 ] ^[1-9]\d*$

The total transaction amount in cents (USD).Learn More

Processing Rules

This value must exactly equal the sum of the amounts specified in paymentAllocations[:].amount.

merchantTransactionId
required
string <= 50 characters

Unique identifier that can be used to track this transaction. This identifier will make sure that there wont be any duplicate transaction. Learn More.

authorizeCard
boolean
Default: false

Authorizes the specified amount on the card without capturing funds immediately.

Processing Rules

About: When set to true, the credit card will be authorized for the specified amount, but the funds are not captured until a subsequent Capture API call is made.

Applicability: Only applicable when the paymentMethod.type = CARD.

The authorization remains valid for 7 days; after this period, the hold may expire and a new authorization may be required. To complete the transaction, the Capture API must be called after authorization.

Note: For any payment—single or split—involving ACH, the transaction will always be processed as a SALE, regardless of the value of the authorizeCard parameter.

partialAuthorization
boolean
Default: false

Allows the card issuer to approve a partial authorization if the full amount is not available.

Processing Rules

About: When set to true, the card issuer may approve a payment for less than the requested amount if the full amount cannot be authorized (e.g., insufficient funds).

Applicability: Only applicable when the paymentMethod.type = CARD and authorizeCard = true.

If enabled, the payment may be partially authorized and the merchant can decide whether to accept or decline the partial amount.

description
string <= 100 characters

An arbitrary string useful to user to track payments. Learn More

statementDescriptorSuffix
string <= 10 characters ^(?=.*[a-zA-Z])[a-zA-Z0-9 \-.]{0,10}$

Statement descriptors explain charges or payments on bank statements. Using clear and accurate statement descriptors can reduce chargebacks and disputes. Learn More.

Processing Rules
  • Must contain atleast one alphabetic character.
  • only of alphanumeric characters, spaces, hyphens, and periods.
  • Allowed Maximum Length is 10
  • Doesn't contain any of the following special characters: <, >, , ' " *.
object (IIASPaymentDetails)

IIAS (Inventory Information Approval System) Payments refer to transactions made using a healthcare payment card (such as a Flexible Spending Account or Health Savings Account card) at merchants equipped with IIAS. The IIAS system automatically verifies and approves eligible healthcare-related purchases in real-time, ensuring compliance with IRS regulations. Learn More

object (metadataRequest) <= 20 properties

Key-value pairs containing payment metadata, such as Order ID, Invoice date. Learn More

Processing Rules
  • A maximum of 20 metadata entries can be included per payment request. This is enforced by the API.
  • Each metadata key can be up to 40 characters in length, and each value can be up to 100 characters.
  • Only string values are supported for both keys and values.
  • Metadata should be used for non-sensitive, non-regulated information only. Do not include PHI, card numbers, or other sensitive data.
  • Examples: {'orderId': '12345', 'invoiceDate': '2025-08-22', 'OrderType': 'Gift purchase'}
object (Consent)
  • Captures the customer's or agent's agreement. Learn More
  • Consent is required when paymentMethod.type=BANK_ACCOUNT.
  • Consent records are immutable once created and should be retained for compliance purposes.
Array of objects (paymentAllocationsRequest) <= 2 items

Array of payment splits for this transaction. Each entry specifies the payment method to use and the amount allocated to that split. Learn More

Processing Rules
  • Maximum of 2 splits allowed.
  • Each Splits must include paymentMethodId and Amount greater than zero
authrequired
boolean
Default: false

Indicates if additional authentication (such as 3D Secure/3DS) is required for the payment. Learn More

Processing Rules

About: When set to true, the payment will require a 3DS authentication step. This is typically used for card payments where the card issuer or payment network requires extra verification (e.g., one-time password, biometric authentication) before approving the transactio Applicability: Only applicable when the paymentMethod.type = `CARD If true, the customer will be prompted for additional authentication during the payment flow.

object (Agent)

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

Responses

Request samples

Content type
application/json
{
  • "amount": 1,
  • "merchantTransactionId": "string",
  • "authorizeCard": false,
  • "partialAuthorization": false,
  • "description": "string",
  • "statementDescriptorSuffix": "string",
  • "paymentDetails": {
    },
  • "metadata": {
    },
  • "consent": {
    },
  • "paymentAllocations": [
    ],
  • "authrequired": false,
  • "agent": {
    }
}

Response samples

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

Get Payment by PaymentId

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

Supported Session Modes:

  • PAYMENT
  • PAYMENT_WITH_WALLET

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

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": "string",
  • "data": {
    }
}