Skip to main content
API docs by Redocly

Convenient Checkout Internal API (v2)

Download OpenAPI specification:Download

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

wallet-merchant-service

API endpoints for wallet merchant service

Create a new merchant

Create a new merchant profile with vendor-scoped payment method configuration. Payment methods must be nested inside each vendorMerchant entry. Do NOT include paymentMethodSettings in the request body — it is computed from vendorMerchants[].paymentMethods[] and returned in the response only. If provided, it is silently ignored.

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

Merchant UUID.

Processing Rules
  • Required: No for POST (auto-generated), Yes for PATCH
  • Must be a valid UUID format when provided
  • On POST, the service auto-generates and returns the ID
merchantGroupId
required
string <uuid>

UUID of the merchant group this merchant belongs to.

Processing Rules
  • Required: Yes
  • Must be a valid UUID format
  • Must reference an existing merchant group
name
required
string <= 255 characters

Human-readable display name of the merchant.

Processing Rules
  • Required: Yes
  • Must not be blank
  • Max length: 255 characters
required
Array of objects (VendorMerchant) non-empty

Processor (vendor) accounts configured for this merchant. Each entry binds a vendor to the payment methods it handles.

THIS IS THE SOURCE OF TRUTH for payment method configuration. paymentMethodSettings is computed from this list and returned in the response only.

Processing Rules
  • Required: Yes
  • Must not be empty -- at least one entry required
  • Duplicate vendor values across entries are not permitted
  • Duplicate vendorMerchantId values across entries are not permitted
  • Each entry must have vendor (required, enum: STRIPE, OPTUM_BANK) + vendorMerchantId (required) + paymentMethods (required, at least 1)
  • vendor must be one of the allowed values: STRIPE, OPTUM_BANK -- any other value is rejected with 400
  • Each paymentMethod must have type + at least 1 channel
  • paymentMethod.type must be a valid enum value: CARD, BANK_ACCOUNT -- any other value is rejected with 400
  • paymentMethod.channels[].type must be a valid enum value for the given paymentMethod.type -- any other value is rejected with 400
  • Each PM type must be in the vendor's supportedPaymentMethods (YAML config)
  • Each channel must be supported for that PM type on that vendor (YAML config)
object
Default: {}

Merchant-level operational settings.

merchantAccAdGroup
string
Default: ""

Active Directory group name assigned to this merchant. Default is "".

Array of objects (OrderedCustomerSearchCriteria)
Default: []

Ordered group criteria used to look up enterprise customers during checkout. Each entry defines a precedence level and a list of customer search criteria to evaluate at that level.

Processing Rules
  • Required: No
  • Default: [] -- no enterprise lookup configured
  • Nullable: No
  • Each entry must have precedence and customerSearchCriteria
  • precedence defines evaluation order -- lower numbers are evaluated first
  • Each customerSearchCriteria entry maps merchant metadata keys to enterprise system fields
clientIds
required
Array of strings non-empty

Client application IDs permitted to create checkout sessions for this merchant.

Processing Rules
  • Required: Yes
  • Must not be empty (at least one clientId required)

Responses

Request samples

Content type
application/json
Example
{
  • "merchantGroupId": "3cf34cba-ffec-48fb-b7ca-09977db1077a",
  • "name": "Acme Health",
  • "vendorMerchants": [
    ],
  • "settings": {
    },
  • "enterpriseSettings": [
    ],
  • "clientIds": [
    ],
  • "merchantAccAdGroup": "merchant-acme-admins"
}

Response samples

Content type
application/json
{
  • "id": "9489b357-a0a1-4196-a3c9-1244de090640",
  • "merchantGroupId": "3cf34cba-ffec-48fb-b7ca-09977db1077a",
  • "name": "Acme Health",
  • "vendorMerchants": [
    ],
  • "paymentMethodSettings": {
    },
  • "settings": {
    },
  • "enterpriseSettings": [
    ],
  • "clientIds": [
    ],
  • "merchantAccAdGroup": "merchant-acme-admins"
}

Update merchant

Update an existing merchant profile. id is required in the request body. Do NOT include paymentMethodSettings in the request body — it is computed from vendorMerchants[].paymentMethods[] and returned in the response only. If provided, it is silently ignored.

Returns 204 No Content with no body in two cases:

  • The merchant is not found for the given id
  • The merchant data is unchanged (no-op — request matches existing state)
Request Body schema: application/json
required
id
string or null <uuid>
Default: null

Merchant UUID.

Processing Rules
  • Required: No for POST (auto-generated), Yes for PATCH
  • Must be a valid UUID format when provided
  • On POST, the service auto-generates and returns the ID
merchantGroupId
required
string <uuid>

UUID of the merchant group this merchant belongs to.

Processing Rules
  • Required: Yes
  • Must be a valid UUID format
  • Must reference an existing merchant group
name
required
string <= 255 characters

Human-readable display name of the merchant.

Processing Rules
  • Required: Yes
  • Must not be blank
  • Max length: 255 characters
required
Array of objects (VendorMerchant) non-empty

Processor (vendor) accounts configured for this merchant. Each entry binds a vendor to the payment methods it handles.

THIS IS THE SOURCE OF TRUTH for payment method configuration. paymentMethodSettings is computed from this list and returned in the response only.

Processing Rules
  • Required: Yes
  • Must not be empty -- at least one entry required
  • Duplicate vendor values across entries are not permitted
  • Duplicate vendorMerchantId values across entries are not permitted
  • Each entry must have vendor (required, enum: STRIPE, OPTUM_BANK) + vendorMerchantId (required) + paymentMethods (required, at least 1)
  • vendor must be one of the allowed values: STRIPE, OPTUM_BANK -- any other value is rejected with 400
  • Each paymentMethod must have type + at least 1 channel
  • paymentMethod.type must be a valid enum value: CARD, BANK_ACCOUNT -- any other value is rejected with 400
  • paymentMethod.channels[].type must be a valid enum value for the given paymentMethod.type -- any other value is rejected with 400
  • Each PM type must be in the vendor's supportedPaymentMethods (YAML config)
  • Each channel must be supported for that PM type on that vendor (YAML config)
object
Default: {}

Merchant-level operational settings.

merchantAccAdGroup
string
Default: ""

Active Directory group name assigned to this merchant. Default is "".

Array of objects (OrderedCustomerSearchCriteria)
Default: []

Ordered group criteria used to look up enterprise customers during checkout. Each entry defines a precedence level and a list of customer search criteria to evaluate at that level.

Processing Rules
  • Required: No
  • Default: [] -- no enterprise lookup configured
  • Nullable: No
  • Each entry must have precedence and customerSearchCriteria
  • precedence defines evaluation order -- lower numbers are evaluated first
  • Each customerSearchCriteria entry maps merchant metadata keys to enterprise system fields
clientIds
required
Array of strings non-empty

Client application IDs permitted to create checkout sessions for this merchant.

Processing Rules
  • Required: Yes
  • Must not be empty (at least one clientId required)

Responses

Request samples

Content type
application/json
Example
{
  • "id": "9489b357-a0a1-4196-a3c9-1244de090640",
  • "merchantGroupId": "3cf34cba-ffec-48fb-b7ca-09977db1077a",
  • "name": "Acme Health",
  • "vendorMerchants": [
    ],
  • "settings": {
    },
  • "enterpriseSettings": [
    ],
  • "clientIds": [
    ],
  • "merchantAccAdGroup": "merchant-acme-admins"
}

Response samples

Content type
application/json
{
  • "id": "9489b357-a0a1-4196-a3c9-1244de090640",
  • "merchantGroupId": "3cf34cba-ffec-48fb-b7ca-09977db1077a",
  • "name": "Acme Health",
  • "vendorMerchants": [
    ],
  • "paymentMethodSettings": {
    },
  • "settings": {
    },
  • "enterpriseSettings": [
    ],
  • "clientIds": [
    ],
  • "merchantAccAdGroup": "merchant-acme-admins"
}

Get all merchants

Retrieve all merchant profiles. Supports optional filtering by vendor and vendorMerchantId.

Returns an array of merchant objects, each containing both the vendor-scoped source of truth (vendorMerchants) and the computed projection (paymentMethodSettings).

query Parameters
vendor
string
Enum: "STRIPE" "OPTUM_BANK"
Example: vendor=STRIPE

Processor platform to filter merchants by.

Processing Rules
  • Required: No
  • Must be used together with vendorMerchantId to apply filtering
  • If either vendor or vendorMerchantId is omitted or empty, all merchants are returned (no filter applied)
  • Allowed values: STRIPE, OPTUM_BANK
vendorMerchantId
string
Example: vendorMerchantId=acct_1NiY8rIgxHxRIfDJ

Processor-assigned account ID to filter merchants by.

Processing Rules
  • Required: No
  • Must be used together with vendor to apply filtering
  • If either vendorMerchantId or vendor is omitted or empty, all merchants are returned (no filter applied)
  • When both vendor and vendorMerchantId are provided, returns only the merchant matching both values

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a specific merchant by ID

Retrieve a single merchant profile by its UUID.

Returns the full merchant object including both vendorMerchants (source of truth) and paymentMethodSettings (computed projection).

path Parameters
merchantId
required
string <uuid>
Example: 9489b357-a0a1-4196-a3c9-1244de090640

Platform-generated unique merchant identifier.

Responses

Response samples

Content type
application/json
{
  • "id": "9489b357-a0a1-4196-a3c9-1244de090640",
  • "merchantGroupId": "3cf34cba-ffec-48fb-b7ca-09977db1077a",
  • "name": "Acme Health",
  • "vendorMerchants": [
    ],
  • "paymentMethodSettings": {
    },
  • "settings": {
    },
  • "enterpriseSettings": [
    ],
  • "clientIds": [
    ],
  • "merchantAccAdGroup": "merchant-acme-admins"
}