Skip to main content
API docs by Redocly

Convenient Checkout API (v1)

Download OpenAPI specification:Download

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

Convenient Checkout Gateway API - Prod

User

Internal CCG widget/service APIs

Update Payment Method by payment-method-id

Authorizations:
gateway
path Parameters
payment-method-id
required
string <uuid>
header Parameters
X-Upstream-Env
required
string <string>
Enum: "dev" "stage" "test"

Specify the env value, Only required for Non-Prod

X-Merchant-Id
required
string
X-Customer-Id
required
string
X-Checkout-Id
required
string <uuid>
Request Body schema: application/json
isDefault
boolean
nickname
string <= 30 characters

can only contain letters and numbers

object
object (Agent)
UpdateCard (object) or UpdateUSBankAccountDetails (object)

Responses

Request samples

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

Response samples

Content type
application/json
[
  • {
    }
]

Create Checkout Session

Authorizations:
gateway
header Parameters
X-Merchant-Id
required
string <uuid>
Request Body schema: application/json
required
paymentType
string
Enum: "PRE_AUTH" "SALE"
authorizeCard
boolean
merchantTransactionId
string
paymentDescription
string
statementDescriptorSuffix
string
amount
integer <int64>
object
object (CheckoutSessionConfig)

Responses

Request samples

Content type
application/json
{
  • "paymentType": "PRE_AUTH",
  • "authorizeCard": true,
  • "merchantTransactionId": "string",
  • "paymentDescription": "string",
  • "statementDescriptorSuffix": "string",
  • "amount": 0,
  • "metadata": {
    },
  • "config": {
    }
}

Response samples

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

Create Child CheckOut Session

Authorizations:
gateway
path Parameters
sessionId
required
string

parent session Id

header Parameters
X-Merchant-Id
required
string <uuid>
Request Body schema: application/json
required
email
string
object (PhoneNumber)
childSessionMode
string
Enum: "TEXT_TO_ADD" "EMAIL_TO_ADD" "TEXT_TO_PAY" "EMAIL_TO_PAY"

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "phone": {
    },
  • "childSessionMode": "TEXT_TO_ADD"
}

Response samples

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

Get CheckOut Session

Authorizations:
gateway
path Parameters
sessionId
required
string

sessionId

query Parameters
init
boolean

if true, appearance object will be returned, else apperance object is null

Responses

Response samples

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

Cancel CheckOut Session

Authorizations:
gateway
path Parameters
sessionId
required
string

sessionId

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

Responses

Response samples

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

Create Payment

ALLOWED SESSION MODES - PAYMENT_WITH_WALLET PAYMENT

Authorizations:
gateway
header Parameters
X-Merchant-Id
required
string <uuid>
X-Customer-Id
required
string
X-Checkout-Id
required
string <uuid>
X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

applicable only for Non prod

Request Body schema: application/json
required
amount
required
integer <int64>
object (CustomerDetail)
object
paymentType
string
Deprecated
Enum: "SALE" "PRE_AUTH"
authorizeCard
boolean
Default: false

false - SALE, true - PRE_AUTH; Applicable payment method types = [CARD]

partialAuthorization
boolean
Default: false

When true, card issuers will consider the payment for partial authorization. This flag shall be provided in combination with authorizeCard flag. Applicable payment method types = [CARD]

paymentMethodId
string <uuid>

required, only when making payment with stored paymentMethod;

object (paymentMethodRequest)

required, only for PayAndSave/OneTimePay

paymentDescription
string <= 100 characters

Payment description that will be useful for user to identify the payment.

merchantTransactionId
string

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "customer": {
    },
  • "metaData": {
    },
  • "paymentType": "SALE",
  • "authorizeCard": false,
  • "partialAuthorization": false,
  • "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
  • "paymentMethod": {
    },
  • "paymentDescription": "string",
  • "merchantTransactionId": "string"
}

Response samples

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

Get Payment Status by PaymentId

ALLOWED SESSION MODES - PAYMENT_WITH_WALLET, PAYMENT

Authorizations:
gateway
path Parameters
paymentId
required
string
header Parameters
X-Merchant-Id
required
string <uuid>
X-Customer-Id
required
string
X-Checkout-Id
required
string <uuid>
X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

applicable only for Non prod

Responses

Response samples

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

Confirm Payment Status by PaymentId

ALLOWED SESSION MODES - PAYMENT_WITH_WALLET, PAYMENT

Authorizations:
gateway
path Parameters
paymentId
required
string
header Parameters
X-Merchant-Id
required
string <uuid>
X-Checkout-Id
required
string <uuid>
X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

applicable only for Non prod

Responses

Response samples

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

Create Setup PaymentMethod

ALLOWED SESSION MODES - PAYMENT_WITH_WALLET PAYMENT_METHOD_ENTRY WALLET

Authorizations:
gateway
path Parameters
id
required
string <uuid>
header Parameters
X-Merchant-Id
required
string
X-Customer-Id
required
string
X-Checkout-Id
required
string <uuid>
X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

applicable only for Non prod

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

Responses

Request samples

Content type
application/json
{
  • "paymentMethodType": "CARD",
  • "paymentMethod": {
    }
}

Response samples

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

Get Setup PaymentMethod By Id

ALLOWED SESSION MODES - PAYMENT_WITH_WALLET PAYMENT_METHOD_ENTRY WALLET

Authorizations:
gateway
path Parameters
id
required
string <uuid>
setup-payment-method-id
required
string <uuid>
header Parameters
X-Merchant-Id
required
string
X-Customer-Id
required
string
X-Checkout-Id
required
string <uuid>
X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

applicable only for Non prod

Responses

Response samples

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

Get Payment Methods

ALLOWED SESSION MODES - PAYMENT_WITH_WALLET

Authorizations:
gateway
path Parameters
id
required
string <uuid>
header Parameters
X-Merchant-Id
required
string
X-Customer-Id
required
string
X-Checkout-Id
required
string <uuid>
X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

applicable only for Non prod

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Payment Method

ALLOWED SESSION MODES - PAYMENT_WITH_WALLET

Authorizations:
gateway
path Parameters
id
required
string <uuid>
payment-method-id
required
string <uuid>
header Parameters
X-Merchant-Id
required
string
X-Customer-Id
required
string
X-Checkout-Id
required
string <uuid>
X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

applicable only for Non prod

Responses

Response samples

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

Update Payment Method Deprecated

This API is deprecated, please update to /payment-methods/{payment-method-id}

Authorizations:
gateway
path Parameters
id
required
string <uuid>
payment-method-id
required
string <uuid>
header Parameters
X-Merchant-Id
required
string
X-Customer-Id
required
string
X-Checkout-Id
required
string <uuid>
X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

applicable only for Non prod

Request Body schema: application/json
required
default
boolean
expiryYear
integer <int32>
nameOnCard
string
expiryMonth
integer <int32>
nickname
string
zipCode
string

Responses

Request samples

Content type
application/json
{
  • "default": true,
  • "expiryYear": 0,
  • "nameOnCard": "string",
  • "expiryMonth": 0,
  • "nickname": "string",
  • "zipCode": "string"
}

Response samples

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

Delete Payment Method

ALLOWED SESSION MODES - PAYMENT_WITH_WALLET

Authorizations:
gateway
path Parameters
id
required
string <uuid>
payment-method-id
required
string <uuid>
header Parameters
X-Merchant-Id
required
string
X-Customer-Id
required
string
X-Checkout-Id
required
string <uuid>
X-Upstream-Env
required
string
Enum: "dev" "stage" "test"

applicable only for Non prod

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "detail": "string",
  • "status": 0
}

Get Bank Routing Number

Authorizations:
gateway
path Parameters
routingNumber
required
string

Routing number belonging to the bank you are trying to locate

Responses

Response samples

Content type
application/json
{
  • "bankName": "string"
}

Merchant

Draft - Create session for initializing the convenient checkout widget

This api is used for creating the session id that is required to load the convenient checkout widget. Refer docs for widget setup. When Customer information is not present or insufficient, the checkout will be a guest experience.

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

Merchant Identifier More info

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

Specify the env value, Only required for Non-Prod

X-source
string <string> <= 50 characters

Specify the Source System Identifier

Request Body schema: application/json
required
object (PaymentDetail)
object (CustomerDetail)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459"
}

Draft - Get session details for the convenient checkout widget

This api is used for getting the session details that is required to get the status of convenient checkout widget. Refer docs for widget setup. When Customer information is not present or insufficient, the checkout will be a guest experience.

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

Merchant Identifier More info

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

Specify the env value, Only required for Non-Prod

Responses

Response samples

Content type
application/json
{
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "data": {
    }
}

Draft - Get Payment by Merchant Transaction Id

Authorizations:
gateway
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>
X-Upstream-Env
required
string <string>
Enum: "dev" "stage" "test"

Specify the env value, Only required for Non-Prod

Responses

Response samples

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

Draft - Create Payment

Authorizations:
gateway
header Parameters
X-Merchant-Id
required
string <uuid>
X-Upstream-Env
required
string <string>
Enum: "dev" "stage" "test"

Specify the env value, Only required for Non-Prod

X-source
string <string> <= 50 characters

Specify the Source System Identifier

Request Body schema: application/json
required
amount
required
integer <int64>
object (CustomerDetail)
object
paymentType
string
Deprecated
Enum: "SALE" "PRE_AUTH"
authorizeCard
boolean
Default: false

false - SALE, true - PRE_AUTH; Applicable payment method types = [CARD]

partialAuthorization
boolean
Default: false

When true, card issuers will consider the payment for partial authorization. This flag shall be provided in combination with authorizeCard flag. Applicable payment method types = [CARD]

paymentMethodId
string <uuid>

required, only when making payment with stored paymentMethod;

object (paymentMethodRequest)

required, only for PayAndSave/OneTimePay

paymentDescription
string <= 100 characters

Payment description that will be useful for user to identify the payment.

merchantTransactionId
string

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "customer": {
    },
  • "metaData": {
    },
  • "paymentType": "SALE",
  • "authorizeCard": false,
  • "partialAuthorization": false,
  • "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
  • "paymentMethod": {
    },
  • "paymentDescription": "string",
  • "merchantTransactionId": "string"
}

Response samples

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

Draft - Get Payment by PaymentId

Authorizations:
gateway
path Parameters
paymentId
required
string <uuid>
header Parameters
X-Merchant-Id
required
string <uuid>
X-Upstream-Env
required
string <string>
Enum: "dev" "stage" "test"

Specify the env value, Only required for Non-Prod

Responses

Response samples

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

Capture partial or full amount in Auth operations by PaymentId

Authorizations:
gateway
path Parameters
paymentId
required
string <uuid>

PaymentId for the authorized payment

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

Merchant Identifier More info

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

Specify the env value, Only required for Non-Prod

X-source
string <string> <= 50 characters

Specify the Source System Identifier

Request Body schema: application/json
amount
integer <int64>
object

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "metadata": {
    }
}

Response samples

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

Cancel payment by PaymentId

Authorizations:
gateway
path Parameters
paymentId
required
string <uuid>

PaymentId for the payment

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

Merchant Identifier More info

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

Specify the env value, Only required for Non-Prod

X-source
string <string> <= 50 characters

Specify the Source System Identifier

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

Payment Cancellation Reason

paymentCancellationMessage
string

Responses

Request samples

Content type
application/json
{
  • "paymentCancellationReason": "DUPLICATE",
  • "paymentCancellationMessage": "string"
}

Response samples

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

Create Refund

Authorizations:
gateway
header Parameters
X-Merchant-Id
required
string <uuid>
X-Upstream-Env
required
string <string>
Enum: "dev" "stage" "test"

Specify the env value, Only required for Non-Prod

X-source
string <string> <= 50 characters

Specify the Source System Identifier

Request Body schema: application/json
required

Refund request can only processed either by paymentId or by valid paymentMethodId associated with customer.

paymentId
string <uuid>

paymentId of the payment that needs refund

paymentMethodId
string <uuid>

paymentMethodId that receives the refund. This is not applicable when paymentId is specified.

amount
integer <int64> [ 1 .. 100000000 ]

Amount in Cents (United States) and required when paymentMethodId is present. For refund associated with payments, if amount not provided full amount will be refunded.

reason
string
Enum: "REQUESTED_BY_CUSTOMER" "DUPLICATE" "FRAUDULENT"
merchantTransactionId
required
string [ 0 .. 50 ] characters
object

Additional payment metadata. Max 20 metadata entries. Max key length is 40. Max value length is 100.

object (Customer)
object (Agent)

Responses

Request samples

Content type
application/json
{
  • "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  • "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
  • "amount": 1,
  • "reason": "REQUESTED_BY_CUSTOMER",
  • "merchantTransactionId": "string",
  • "metadata": {
    },
  • "customer": {
    },
  • "agent": {
    }
}

Response samples

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

Get Refund by RefundId

Authorizations:
gateway
path Parameters
refund-id
required
string <uuid>
header Parameters
X-Merchant-Id
required
string <uuid>
X-Upstream-Env
required
string <string>
Enum: "dev" "stage" "test"

Specify the env value, Only required for Non-Prod

Responses

Response samples

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

Merchant-Wallet-Management

Find Payment Methods for customer

Authorizations:
gateway
header Parameters
X-Merchant-Id
required
string <uuid>
X-Upstream-Env
required
string <string>
Enum: "dev" "stage" "test"

Specify the env value, Only required for Non-Prod

Request Body schema: application/json
object (CustomerDetail)
name
string
email
required
string
ssnLastFour
string
object (PhoneNumber)
dateOfBirth
string <date>
statementDescriptorSuffix
string
hsid
string
object

Responses

Request samples

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

Response samples

Content type
application/json
[
  • {
    }
]

Merchant - PCI

Draft - Create Payment Method

Authorizations:
gateway
header Parameters
X-Merchant-Id
required
string <uuid>
X-Upstream-Env
required
string <string>
Enum: "dev" "stage" "test"

Specify the env value, Only required for Non-Prod

X-source
string <string> <= 50 characters

Specify the Source System Identifier

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

Responses

Request samples

Content type
application/json
{
  • "paymentMethodType": "CARD",
  • "paymentMethod": {
    }
}

Response samples

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

Draft - Get Payment Method

Authorizations:
gateway
header Parameters
X-Merchant-Id
required
string <uuid>
X-Upstream-Env
required
string <string>
Enum: "dev" "stage" "test"

Specify the env value, Only required for Non-Prod

Responses

Response samples

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

Draft - Create Payment

Authorizations:
gateway
header Parameters
X-Merchant-Id
required
string <uuid>
X-Upstream-Env
required
string <string>
Enum: "dev" "stage" "test"

Specify the env value, Only required for Non-Prod

X-source
string <string> <= 50 characters

Specify the Source System Identifier

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

Amount in Cents (United States)

object (Customer)
object (IIASPaymentDetails)
object (PaymentMethodToken)
object

Key-value pairs containing payment metadata, such as Order ID or Invoice date. A maximum of 20 entries is allowed, with each key up to 40 characters and each value up to 100 characters.

paymentType
string
Deprecated
Enum: "SALE" "PRE_AUTH"
authorizeCard
boolean
Default: false

When authorizeCard is set as true, the credit card will be authorized for the amount supplied. Later we need to call the Capture API to complete the transaction. The authorization is valid only for 7 days.

partialAuthorization
boolean
Default: false

When true, card issuers will consider the payment for partial authorization. This flag shall be provided in combination with authorizeCard flag. Applicable payment method types = [CARD]

paymentMethodId
string <uuid>

Payment method Id of the saved card/bankAccount. To get the payment method Id refer /payment-methods/search API.

paymentDescription
string <= 100 characters

Payment description that will be useful for user to identify the payment.

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.

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

Must contain a letter. Learn more about statement descriptors in docs.

object (Agent)
object (Consent)

Responses

Request samples

Content type
application/json
{
  • "amount": 1,
  • "customer": {
    },
  • "paymentDetails": {
    },
  • "paymentMethod": {
    },
  • "metadata": {
    },
  • "paymentType": "SALE",
  • "authorizeCard": false,
  • "partialAuthorization": false,
  • "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
  • "paymentDescription": "string",
  • "merchantTransactionId": "string",
  • "statementDescriptorSuffix": "string",
  • "agent": {
    },
  • "consent": {
    }
}

Response samples

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