Vendor Configuration

The vendors filter gives you precise control over which payment processor, payment method types, and channels are available in a checkout session. When you create a V2 session, the platform resolves processor configuration from your merchant account and returns it in vendorConfigs — a client-safe snapshot your frontend uses to initialize the payment SDK and present the right payment options to your customers.

---

V2 Feature

Vendor configuration is available on V2 sessions only (POST /v2/sessions). V1 sessions receive a subset of this behavior through legacy channel fields.

When you create a V2 checkout session, the platform resolves the payment processor configuration for your merchant account and attaches it to the session. This page describes how that configuration is scoped, what the response contains, what fields are safe to read client-side, and how the platform determines which processor handles a given transaction.

Integration Details

Integration Details

• Prerequisite: Merchant account onboarded to the CCG Platform with V2 session support. See Getting Started.
• API Endpoint: POST /v2/sessions — creates a V2 checkout session with vendor configuration
• API Spec: Create Session
• Scope: merchant
• Key Request Field: config.vendors — optional array to restrict session to specific processors, payment method types, and channels
• Key Response Field: checkoutRequest.config.vendorConfigs — resolved processor configuration; use to initialize the payment SDK
• Error Handling: See Session Error Codes for session-specific errors

---

---

API Request

API Specification

For complete field definitions, constraints, and validations, refer to the OpenAPI Spec.

Include config.vendors in your V2 session request to restrict the session to a specific processor, payment method type, and set of channels. Omit config.vendors to use your full merchant configuration.

Sample Request — V2 Session with Vendor Configuration (Stripe, Card, Apple Pay + Webform)

curl -X POST "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/sessions" \
  -H "Authorization: ******" \
  -H "X-Merchant-Id: <merchant-id>" \
  -H "X-Upstream-Env: dev" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@example.com",
      "hsid": "<customer-hsid>"
    },
    "payment": {
      "merchantTransactionId": "<unique-id>",
      "amount": 1500,
      "authorizeCard": false
    },
    "config": {
      "modes": ["PAYMENT"],
      "vendors": [
        {
          "vendor": "STRIPE",
          "paymentMethods": [
            {
              "type": "CARD",
              "channels": ["APPLE_PAY", "WEBFORM"]
            }
          ]
        }
      ]
    }
  }'

Sample Request — V2 Session without Vendor Filter (all configured processors)

curl -X POST "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/sessions" \
  -H "Authorization: ******" \
  -H "X-Merchant-Id: <merchant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@example.com",
      "hsid": "<customer-hsid>"
    },
    "payment": {
      "merchantTransactionId": "<unique-id>",
      "amount": 1500,
      "authorizeCard": false
    },
    "config": {
      "modes": ["PAYMENT"]
    }
  }'

---

API Response

Response Structure

Sample responses show key fields only. For the complete schema, refer to the OpenAPI Spec.

The checkoutRequest.config.vendorConfigs array in the response contains the resolved processor configuration for the session.

Sample Response — Session Created with Vendor Configuration (200)

{
  "data": {
    "checkoutSessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "hostedUrl": "https://walletprod.healthsafepay.com/wallet/v2/checkout?session=a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "url": "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "checkoutRequest": {
      "config": {
        "vendorConfigs": [
          {
            "vendor": "STRIPE",
            "vendorMerchantId": "acct_xxxxxxxxxxxx",
            "clientConfig": {
              "publicKey": "pk_live_xxxxxxxxxxxx"
            },
            "paymentMethods": [
              {
                "type": "CARD",
                "channels": [
                  { "type": "APPLE_PAY", "order": 0, "enabled": true },
                  { "type": "WEBFORM", "order": 1, "enabled": true }
                ]
              }
            ]
          }
        ]
      }
    }
  }
}

Sample Response — Session Created with No Matching Vendor (empty vendorConfigs)

{
  "data": {
    "checkoutSessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "checkoutRequest": {
      "config": {
        "vendorConfigs": []
      }
    }
  }
}

Sample Response — Business Rule Violation (400 — missing vendor field)

{
  "errors": [
    {
      "title": "INVALID_REQUEST",
      "detail": "config.vendors[0].vendor is required",
      "status": "400"
    }
  ]
}

---

Status Handling

Vendor configuration is resolved and embedded in vendorConfigs at session creation time. No additional polling is needed to retrieve vendor configuration — it is available in the create-session response.

After session creation, use the url field from the response to poll for session status, or use widget callbacks to detect completion.

Session Status	Description
ACCEPTED	Session created, initialization in progress
CREATED	Session ready; vendorConfigs is available and the widget can be loaded
COMPLETED	Transaction succeeded
FAILED	Transaction failed or an unrecoverable error occurred
EXPIRED	Session timed out before the user completed the flow
CANCELED	Session was explicitly canceled

See Sessions API for full session lifecycle and polling details.

---

Error Handling

For session-specific error codes and remediation steps, see Session Error Codes.

Common errors related to vendor configuration:

Error Title	HTTP Status	Cause	Action
INVALID_REQUEST	400	vendor field missing from a vendors entry, or unrecognized enum value	Verify config.vendors entries include a valid vendor value
UNAUTHORIZED	401	Invalid or expired JWT token	Refresh your token and retry
MERCHANT_NOT_FOUND	404	X-Merchant-Id does not match an active merchant	Verify merchant onboarding is complete

If vendorConfigs is empty or absent in a successful (200) response, it is not an error — see When vendorConfigs Is Absent or Empty.

---

Session-Level Scoping

The vendors Filter

The optional config.vendors array lets you restrict a session to a specific processor, payment method type, and set of channels. When omitted, the platform uses your full merchant configuration.

Example — restrict session to Stripe card payments via Apple Pay and web form

{
  "config": {
    "modes": ["PAYMENT"],
    "vendors": [
      {
        "vendor": "STRIPE",
        "paymentMethods": [
          {
            "type": "CARD",
            "channels": ["APPLE_PAY", "WEBFORM"]
          }
        ]
      }
    ]
  }
}

Supported Inputs

Field	Type	Description
vendor	string (required)	Processor identifier. Must exactly match a vendor configured on your merchant account.
paymentMethods[].type	string	Payment method type. Must be a valid type (CARD, BANK_ACCOUNT).
paymentMethods[].channels	array	Channels to include for this payment method type.

Scoping Behavior

Scenario	Behavior
vendors omitted	Session uses all payment methods and channels enabled for your merchant account.
vendors: [] (empty array)	Returns all payment methods and channels configured for your merchant account — same behavior as omitting vendors entirely.
Vendor not configured on your account	Session is created successfully; that vendor is silently excluded from vendorConfigs. No error is returned.
Channel not supported by the vendor	Silently excluded from vendorConfigs. Delivery channels (TEXT, EMAIL) are always stripped. WEBFORM is always added when supported.
Channel not supported by the vendor	Silently excluded from vendorConfigs. No error is returned.
Vendor specified but no matching payment method or channel survives	Session is created; vendorConfigs will be empty or absent for that vendor.
vendor field missing from an entry	Request is rejected — 400 Bad Request.
Unrecognized enum value in vendor	Request is rejected — 400 Bad Request.

tip

Your integration should always handle the case where vendorConfigs is empty or absent — see Client Behavior When Configuration Is Absent.

WEBFORM Default

WEBFORM is always included in vendorConfigs for a payment method type when the processor supports it, even if not explicitly listed in the channels filter. This ensures a web-based payment path is always available (V1 parity).

Delivery channels (TEXT, EMAIL) are always stripped from vendorConfigs — they are delivery mechanisms, not vendor SDK capabilities. Requesting only TEXT or TEXT alongside APPLE_PAY will result in WEBFORM being added as the fallback web entry point. WEBFORM is always included in the resolved channel set when the processor supports it, even if not explicitly requested. This ensures a web-based payment path is always available as a fallback.

---

Vendor Configuration in the Response

After a V2 session is created, the response contains a vendorConfigs array inside checkoutRequest.config. Each entry represents one payment processor configured for the session.

Example — vendorConfigs in session response

{
  "checkoutRequest": {
    "config": {
      "vendorConfigs": [
        {
          "vendor": "STRIPE",
          "vendorMerchantId": "acct_xxxxxxxxxxxx",
          "clientConfig": {
            "publicKey": "pk_live_xxxxxxxxxxxx"
          },
          "paymentMethods": [
            {
              "type": "CARD",
              "channels": [
                { "type": "APPLE_PAY", "order": 0, "enabled": true },
                { "type": "WEBFORM",   "order": 1, "enabled": true }
              ]
            }
          ]
        }
      ]
    }
  }
}

When vendorConfigs Is Present

The array contains one entry per processor that matched the session's scope. Each entry includes client-safe configuration your frontend can use to initialize the payment SDK.

When vendorConfigs Is Absent or Empty

Condition	Meaning	Recommended Action
vendorConfigs not present in response	Session was created on a V1-era merchant account. Legacy paymentMethodChannel applies.	Fall back to legacy channel handling.
vendorConfigs: [] (empty array)	A vendor filter was applied but no configured processor matched the requested scope.	Display an appropriate message; do not attempt payment.

Legacy Sessions (Pre-Migration)

Merchant accounts that were created before multi-processor support was introduced may not have vendorConfigs in the session response. In these cases:

• The paymentMethodChannel field in checkoutRequest.config reflects the available payment channels.
• The platform uses a single Stripe processor resolved from your legacy merchant configuration.
• No vendorConfigs entry is returned.

If you are using the CCG widget, it handles this automatically. If you are reading vendorConfigs directly, check for its presence before use.

---

Client-Safe Configuration

The fields inside each vendorConfigs entry are safe to read and use from client-side code (browser / mobile app). They contain only public-facing values — no server-only credentials, private keys, or internal identifiers are included.

Enumerated Client-Safe Fields

Field	Description	Example
vendor	Processor name. Use to select the correct SDK or flow.	"STRIPE"
vendorMerchantId	Your account ID with the payment processor, used to scope transactions to your merchant account. Pass to the payment SDK when initializing.	"acct_xxxxxxxxxxxx"
clientConfig.publicKey	Publishable API key for the processor SDK. Use to initialize the SDK on the client.	"pk_live_xxxxxxxxxxxx"
paymentMethods[].type	Payment method type available in this session.	"CARD"
paymentMethods[].channels[].type	Channel available for this payment method.	"APPLE_PAY"
paymentMethods[].channels[].enabled	Whether the channel is active for this session.	true
paymentMethods[].channels[].order	Display order for the channel in the UI.	0

How Values Are Sourced

Field	Source
vendor	Determined by your merchant's processor configuration.
vendorMerchantId	Your account ID with the payment processor, configured for your merchant account during onboarding.
clientConfig.publicKey	Your processor's publishable API key, configured for your merchant account.
paymentMethods	Intersection of your merchant's enabled payment methods and the session's vendors filter (if provided).
channels	Intersection of your merchant's enabled channels for this payment method and the session's channel filter (if provided).

When Configuration Is Missing or Excluded

Scenario	Behavior
clientConfig is null	Processor was matched but no client configuration is set up for your account. Contact your onboarding team.
clientConfig.publicKey is null or absent	Do not attempt to initialize the payment SDK. Display an error to the user.
paymentMethods is empty	No payment methods matched the session scope. Session was created but payment cannot proceed.
A specific channel (APPLE_PAY, etc.) is absent	That channel is not available for this session. Do not offer it to the user.

Client Behavior When Configuration Is Absent

If vendorConfigs is absent, empty, or missing clientConfig.publicKey:

1. Do not attempt payment SDK initialization.
2. Do not display payment method options that rely on processor-specific configuration.
3. Handle gracefully — show a user-friendly message or fall back to a supported path.
4. Do not re-create the session automatically. If vendorConfigs is empty, the session scope produced no valid processor match. Review your vendors filter and merchant configuration.

---

Deterministic Processor Routing

How Routing Works

The payment processor for a session is determined at session creation time, based on your merchant configuration and the payment method selected.

• The platform evaluates the requested payment method type (CARD, BANK_ACCOUNT) and channels against your configured processors.
• The matching processor is resolved and its configuration is embedded in vendorConfigs.
• No routing decision is made at payment submission time. The processor in vendorConfigs is the processor that will handle the transaction.

Key Guarantees

Guarantee	Description
Resolved at creation	The processor is determined when the session is created, not when the user submits payment.
Payment method determines processor	Each payment method type (CARD, BANK_ACCOUNT) routes to the processor configured for it on your account.
No automatic re-routing	If the processor in vendorConfigs is unavailable at payment time, the transaction fails. No automatic fallback to another processor occurs.
Deterministic	Given the same merchant configuration and session inputs, the same processor is always selected.

Routing and Multiple Processors

If your account supports multiple processors (for example, Stripe for cards and Optum Bank for bank accounts), each processor appears as a separate entry in vendorConfigs:

Example — multiple processors in a single session

{
  "vendorConfigs": [
    {
      "vendor": "STRIPE",
      "paymentMethods": [{ "type": "CARD", "channels": [...] }]
    },
    {
      "vendor": "OPTUM_BANK",
      "paymentMethods": [{ "type": "BANK_ACCOUNT", "channels": [...] }]
    }
  ]
}

The payment method the user selects during checkout determines which processor's configuration is used to complete the transaction.

On Routing Failure

If a transaction fails at the processor level after the session is created:

• The session transitions to FAILED.
• No re-routing to another processor occurs.
• Create a new session if you need to retry the transaction.

---

FAQ

Q: What happens if I specify a vendor that is not configured on my account?
A: The session is created successfully, but that vendor is silently excluded from vendorConfigs. No error is returned. Always verify vendorConfigs in the response before initializing the payment SDK.

Q: Can I use vendorConfigs from the browser / mobile client?
A: Yes. All fields in vendorConfigs are client-safe. Do not pass server-only fields (such as private API keys) from your backend to the client — they are not included in vendorConfigs.

Q: What does it mean if vendorConfigs is empty?
A: The session scope produced no matching processor configuration. This can happen if the vendors filter specifies channels or payment methods not enabled for your account. Review your filter and merchant configuration, then create a new session.

Q: Is vendorConfigs the same as paymentMethodChannel?
A: No. paymentMethodChannel is a legacy field retained for backward compatibility. vendorConfigs is the V2 replacement and provides richer, processor-specific configuration including the publicKey needed to initialize the payment SDK. Use vendorConfigs for all new integrations.

Q: If my account has Stripe for cards and Optum Bank for bank accounts, will both appear in vendorConfigs?
A: Yes, when both payment method types are available in the session scope, each processor appears as a separate entry in vendorConfigs.

Q: Can the processor change between session creation and payment submission?
A: No. The processor is resolved at session creation and does not change. The processor identified in vendorConfigs handles the transaction.

Q: What should I do if clientConfig.publicKey is missing?
A: Do not attempt to initialize the payment SDK. This indicates a configuration issue with your merchant account. Contact your onboarding or support team.

---

Integration Checklist

• Merchant account onboarded to the CCG Platform with V2 session support
• Session creation always performed server-side (JWT never exposed to browser)
• config.vendors entries each include a valid vendor value; omit the array to use all configured processors
• vendorConfigs presence and content verified in the response before initializing the payment SDK
• Client code handles vendorConfigs being absent or empty (legacy account or unmatched filter)
• clientConfig.publicKey checked for presence before passing to the payment SDK
• Payment SDK initialized using vendorMerchantId and clientConfig.publicKey from vendorConfigs
• Processor routing understood — processor is resolved at session creation and does not change
• Error handling implemented for 400 INVALID_REQUEST when config.vendors contains invalid entries
• Tested with sandbox/staging environment before going live

---

Related Documentation

• Sessions API — Session creation, lifecycle, and status handling
• Session Error Codes — Full error reference for session endpoints
• OpenAPI Spec — Complete field definitions and constraints for V2 session creation
• Widget Capabilities — Mode support matrix and configuration details
• Getting Started — Merchant onboarding and prerequisites