Skip to main content
API docs by Redocly

Convenient Checkout Api (v1)

Download OpenAPI specification:Download

Karthik S. Balaram: balaramk@optum.com Terms of Service

Convenient Checkout Gateway API - Prod

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>

Specify the Source System Identifier

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

payment details

object (Customer)

customer details

object (Appearance)

Custom Styling More info

object (SessionConfig)
object (Agent)
object (Consent)
object (SessionPaymentMethod)

Responses

Request samples

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

Response samples

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

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

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

Amount in Cents (United States)

object (Customer)

customer details

object (IIASPaymentDetails)
object

Payment metadata key value pairs. Example - Order Id, Invoice date etc. Max 20 metadata entries. Max key length is 40. Max value length is 100.

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. 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
required
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)
authRequired
boolean

Responses

Request samples

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

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

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

Amount in Cents (United States). Max Capture amount is limited by the original authorized amount. If no amount is specified, it attempts to capture the full authorized amount

object

Additional payment metadata. This metadata will be merged with the original payment metadata used for authorizing this payment. Max 20 metadata entries. Max key length is 40. Max value length is 100.

Responses

Request samples

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

Response samples

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

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

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

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

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)

customer details

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 (Customer)

customer details

name
string
Deprecated
firstName
string
lastName
string
email
string <email>
ssnLastFour
string
object (PhoneNumber)
dateOfBirth
string <date>
zip5
string^\d{5}$
hsid
string <uuid>

HealthSafeId of the customer. More info

enterpriseId
string

EnterpriseId of the customer. More info

object

Merchant specific customer identifiers as key value pairs. These could be internal customer ids. Example MemberId, CustomerId etc. Max 20 metadata entries. Max key length is 40. Max value length is 100.

Responses

Request samples

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

Response samples

Content type
application/json
[
  • {
    }
]

Get details of 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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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

Request Body schema: application/json
isDefault
boolean
nickname
string <= 30 characters

can only contain letters and numbers (cannot contain card number applicable only for cards)

object
Deprecated

Deprecated in favour of paymentMethodDetails.

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
[
  • {
    }
]

Delete 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

Content-Type
required
string
Value: "application/json"
Request Body schema: application/json
optional
firstName
string <= 50 characters

first name of the agent. This field is required for Agent flow.

lastName
string <= 50 characters

last name of the agent. This field is required for Agent flow.

userId
string <= 50 characters

msid of the agent. This field is required for Agent flow.

isAccessVerified
boolean

when merchant verifies access for the agent to allow entry of 16 digit card number, this can be set to true.

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "userId": "string",
  • "isAccessVerified": true
}

Response samples

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

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

Request Body schema: application/json
required
requestId
string <uuid>
object (Customer)

customer details

object (SavePaymentMethodToken)

Responses

Request samples

Content type
application/json
{
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "customer": {
    },
  • "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

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

Amount in Cents (United States)

object (Customer)

customer details

object (IIASPaymentDetails)
object (PaymentMethodToken)
object

Payment metadata key value pairs. Example - Order Id, Invoice date etc. Max 20 metadata entries. Max key length is 40. Max value length is 100.

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