Checking access…

Skip to main content
Version: v2

Convenient Checkout API Terminology

Quick Tip: Use this page as a reference for field definitions when integrating with the Convenient Checkout API. Each section below summarizes the key objects and headers you will encounter in API requests and responses.

Header Fields​

X-Upstream-Env​

X-UPSTREAM-ENV is a custom HTTP header commonly used in API ecosystems to indicate the target environment for an upstream service call. It helps route requests to the correct backend environment (e.g., dev, stage, prod) without changing the base URL

A required header for non-production environments. Accepts values: "dev", "stage", or "test". Used to specify the environment for the request. See Details

X-source​

The x-source header identifies the originating system or surface of a request. Merchants may operate multiple surfaces (such as web, mobile app, etc.) within the same organization, and the x-source header helps distinguish between them. This header is optional but valuable for tracking and analytics. Learn More

X-Merchant-Id​

Merchant Id is a unique identifier that is used to identify a merchant system. Merchant Id is created during the merchant onboarding process and will be provided to the respective team. Refer Merchant Onboarding document for more information

Session Object Fields​

Session Id​

A unique identifier for a checkout session, used to load and manage the Convenient Checkout Widget.

Hosted URL​

A URL provided for hosting or embedding the checkout session widget.

Config​

Configuration options for the session, such as modes, payment method channels, privacy policy URL, and sender email address.

Modes​

Specifies the supported session modes, such as PAYMENT, PAYMENT_WITH_WALLET, PAYMENT_METHOD_ENTRY, or WALLET.

Appearance​

Custom styling options for the checkout UI, including font, palette, and logo.

Payment Method​

Details about the payment method to be used or displayed in the session.

SessionConfig​

Defines configuration options for a checkout session, including supported modes, payment method channels, card category, privacy policy URL, sender email address, and additional options for session behavior and appearance. Refer Session Configuration docs for more information.

Checkout Session Status​

Current status of the checkout session.

  • CREATED: Session has been created.
  • INITIATED: Session has been initiated.
  • PENDING: Session is pending further action.
  • COMPLETED: Session has been completed successfully.
  • FAILED: Session has failed.
  • CANCELED: Session has been canceled.

Child Session Modes​

Specifies the mode of the child checkout session, such as text or email for adding or paying. The enum values define the allowed modes:

  • TEXT_TO_ADD: Use text channel to add a payment method.
  • TEXT_TO_PAY: Use text channel to pay.
  • EMAIL_TO_ADD: Use email channel to add a payment method.
  • EMAIL_TO_PAY: Use email channel to pay.

Refer Text Channel and Email Channel for more details.

Payment Object Fields​

payment.statementDescriptorSuffix​

Statement descriptors are the text that appears on a customer's bank statement for a transaction. The static descriptor is set during onboarding. A dynamic statement descriptor suffix can be set in the API request and must contain at least one letter. Refer Statement Descriptors Stripe Documentation

payment.merchantTransactionId​

Each payment or transaction has a unique identifier provided by merchant known as the merchantTransactionId. If a payment attempt fails, the same merchantTransactionId must be used for any retry to ensure it is recognised as part of the original transaction. Using a new merchantTransactionId initiates a separate transaction and is not treated as a retry.

This identifier is essential for tracking and referencing payment transactions. For more details, refer to Idempotency Handling.

payment.amount​

The total amount to be charged for the payment, specified as an integer value in cents (e.g., 1000 = $10.00). This field is required for all payment requests and must comply with the merchant's configuration and business rules.

  • Currency: All amounts are assumed to be in USD.
  • Validation: The amount is validated for minimum and maximum limits, and may also be subject to additional business logic (such as split tender rules).

payment.description​

A short, human-readable description to help users and merchants identify the purpose of the payment. This field is typically displayed in reports, and dashboards. Merchants can provide a custom description for each payment to clarify its context (e.g., "Order #12345", "Subscription Renewal", or "HSA Card Payment").

  • Default Value: If no description is provided by the merchant, the value will be set to UI widget payment when the payment is initiated through the Convenient Checkout Widget.
  • Best Practices: Use clear, concise language that is meaningful to both the customer and merchant. Avoid including sensitive information (such as card numbers or personal data) in this field.

payment.paymentType​

Indicates the payment type, such as SALE or PRE_AUTH. This is determined by the payment request: if authorizeCard is false, the payment is processed as SALE; if authorizeCard is true, it is processed as PRE_AUTH.

payment.authorizeCard​

A flag to indicate if a card should be authorized for an amount, requiring a later capture to complete the transaction.

payment.partialAuthorization​

A flag to allow card issuers to partially authorize a payment if the full amount is not available.

Payment Method Id​

A unique identifier for a saved payment method (card or bank account) used in payment APIs.

Payment Method Type​

Indicates the type of payment method, such as CARD or BANK_ACCOUNT.

Payment Method Channel​

Specifies the allowed channels for payment method entry, such as TERMINAL, TEXT, EMAIL, or WEBFORM.

payment.authRequired​

Indicates whether additional authentication is required for the payment, such as 3D Secure (3DS) authentication for card payments. When set to true, the customer will be prompted to complete an extra verification step (e.g., entering a one-time password or using biometric authentication) as mandated by the card issuer or payment network. This is especially relevant for transactions that require strong customer authentication.

  • When is it used?
    • For 3DS-enabled cards, or when the merchant or payment network requires additional authentication for risk or compliance reasons.
    • The field helps merchants and integrators identify when to expect a redirect or challenge during the payment flow.

For more details, see 3DS Authentication.

payment.paymentDetails​

The paymentDetails object is used to provide additional information required for certain types of payments, especially those involving healthcare and IIAS (Inventory Information Approval System) requirements. This section is particularly relevant for HSA/FSA card payments and other regulated healthcare transactions.

Key fields may include:

  • Healthcare fields: Such as iias, visionAmount, or other identifiers needed for compliance with healthcare payment regulations.
    • IIAS fields: Such as qualifiedAmount, qualifiedAmountDetail, and prescriptionAmount, which are required for substantiating healthcare purchases.

Refer to the IIAS Payments documentation.

payment.metadata​

Metadata provides additional, merchant-defined or system-generated information to enhance payment traceability, reporting, and integration with external systems.

  • About:

    • Metadata is structured as key-value pairs and can be attached at both the transaction and individual payment levels.
    • It enables merchants and integrators to store custom data (such as order IDs, invoice dates, campaign codes, or internal references) alongside payment records for easier reconciliation, analytics, and troubleshooting.
    • CCG also uses metadata for internal tracking, rollback operations, and linking related transactions (e.g., refunds, split payments).

  • Applicability:

    • Supported for all payment types and flows.
    • Especially useful for merchants who need to correlate payments with their own business systems or workflows.
    • Metadata is included in both API requests and responses, subject to system limits.

  • Structure & Examples:

    • Transaction-level metadata may include:
      • checkoutId, merchantId, transactionId, merchantName, ccg_processor, merchantGroupId
      • Rollback and refund-related fields for split tender or multi-step payments
    • Individual payment-level metadata may include:
      • referenceId, ccg_paymentMethodId, merchantTransactionId, ccg_paymentmethodlast4, ccg_paymentmethodNameOnCard, ccg_paymentmethodNickName

  • Validation & Limits:

    • Maximum of 20 metadata entries per payment (API enforced).
    • Each key can be up to 40 characters; each value up to 100 characters.
    • Only string values are supported; avoid sensitive or regulated data (e.g., PHI, card numbers).
    • Keys and values that exceed limits may be truncated or rejected.

payment.paymentSplits​

Represents an array of payment splits for a transaction, enabling split tender payments where the total amount is divided among multiple payment methods (e.g., card + HSA/FSA, or two cards).

  • About:

    • Each entry in the array specifies a payment method and the amount allocated to that split.
    • Used to support scenarios where a customer pays with more than one payment method in a single transaction.
    • The sum of all split amounts must exactly match the total payment amount.

  • Applicability:

    • Required for split tender transactions.
    • Supported for all payment types that allow multiple payment methods.

  • Validation:

    • Maximum of 2 splits per transaction (API enforced).
    • Each split must specify a valid paymentMethodId and a positive amount.
    • The sum of all split amounts must equal the total transaction amount.
    • See Payment Method Validation for details on allowed combinations and restrictions.

  • Example:

    [
      { "paymentMethodId": "card-uuid-1", "amount": 6000 },
      { "paymentMethodId": "hsa-uuid-2", "amount": 4000 }
    ]

For more, see Split Tender Payment Use Case.

payment.status​

Describes the current state of a payment. Typical values include:

  • INITIATED
  • COMPLETED
  • FAILED
  • CANCELED
  • AUTHORIZED
  • PAYMENT_METHOD_FAILED
  • CAPTURE_INITIALIZED
  • CANCEL_INITIALIZED
  • PENDING
  • PROCESSING
info

Refer Payment Life cycle for detailed information

Refund Reason​

Specifies the rationale for issuing a refund. Common reasons are:

  • REQUESTED_BY_CUSTOMER
  • DUPLICATE
  • FRAUDULENT

refund.merchantTransactionId​

A unique identifier assigned to each refund transaction. This ID is used to track and reference refund operations.

payment.paymentCancellationReason​

Defines the reason for payment cancellation. Allowed values:

  • DUPLICATE
  • FRAUDULENT
  • REQUESTED_BY_CUSTOMER
  • ABANDONED

If a cancellation is initiated by CCG as part of a rollback, the reason will be set to CCG_AUTOMATED_CANCEL. The Payment Cancellation Message field will provide additional context. For more information, see the Rollback Process.

Customer Object Fields​

A Customer object is required for:

  • Adding a Payment Method
  • Managing a Wallet
  • Making a Payment using the Customer Wallet
  • Pay and Store

Required fields depend on the merchant's enterprise settings.

🔒 InternalInternal information — not visible in the public (merchant) site.
See Customer Creation for details.

Demographic Information​

  • First Name: The customer's given name.
  • Last Name: The customer's surname.
  • Email: The customer's email address.
  • Phone Number: The customer's phone number, including country code.
  • Date of Birth: The customer's date of birth (YYYY-MM-DD).
  • Zip5: The five-digit ZIP code for the customer's address.

Customer Identifiers​

  • HSID: The HealthSafeId (HSID) for unique identification.
  • EnterpriseId: The enterprise identifier for the customer.
  • Metadata: Key-value pairs for additional customer information (subject to system limits).
🔒 InternalInternal information — not visible in the public (merchant) site.

Learn more about Customer Identifiers here

PaymentMethod Object Fields​

PaymentMethod​

Represents a saved payment method, such as a card or bank account. Includes type, details, nickname, and source provider.

paymentMethodDetails​

Contains specific details about the payment method used for processing payments. The structure depends on the payment method type:

  • Card:

    • Includes card brand (e.g., VISA, MASTERCARD), last four digits of the card, expiration month and year, and the name on the card. Sensitive card data is never returned or stored in plain text; only masked or reference information is provided.
    • Used when paymentMethodType is CARD.
    • nameOnCard and nickName field under paymentMethodDetails object is restricted to add card number as value
    • The nameOnCard and nickName fields under the paymentMethodDetails object must not contain the card number as their value. These fields are restricted to prevent storing sensitive card data.

  • Bank Account:

    • Includes account type (e.g., checking, savings), bank name, last four digits of the account number, masked routing number, and the name on the account. As with cards, sensitive bank account data is masked and not exposed in API responses.
    • Used when paymentMethodType is BANK_ACCOUNT.
    • nameOnAccount and nickName field under paymentMethodDetails object is restricted to add bank account number as value
    • The nameOnAccount and nickName fields under the paymentMethodDetails object must not contain the bank account number as their value. These fields are restricted to prevent storing sensitive bank account data.

Card Category​

A classification for cards, such as MANUFACTURER_CARD, which may include a list of eligible medications.

Medication​

Represents a medication with a label and value, used in card categories.

Common Object Fields​

Represents the consent collected from the customer or agent, including consent text and collection details. For more information, see Payment Consent.

Agent​

Details about an agent acting on behalf of a customer. To know more about agents, see Actors

agent.userId​

The agent's identity. Two identity types are supported:

Identity TypeFormatMax Length
MSIDMicrosoft identity string (e.g., ms1234567890)50 characters
Email / UPNFully-qualified email address or User Principal Name (e.g., agent@example.com)250 characters
Backward Compatibility

Existing integrations that supply an MSID continue to work without any changes. Email / UPN support is additive.

agent.isAccessVerified​

This flag is required for agent sessions when adding a payment method or making a one-time payment. Refer to Access Logic.

Warning Fields​

Warning Code​

Warning codes explain why some payment methods were not returned for a vendor. A payment method search can return both:

  • Successfully retrieved payment methods
  • One or more warnings about methods that could not be retrieved.

These warnings are informational only and do not mean the request failed.

Supported values:

Warning CodeDescription
TIMEOUTThe vendor did not respond within the allowed time.
UNAVAILABLEThe vendor service is currently unavailable.
RATE_LIMITEDThe vendor temporarily rejected the request due to request limits.
UNAUTHORIZEDAuthentication with the vendor failed.
FORBIDDENAccess to the requested vendor resource was denied.
NOT_FOUNDThe requested vendor resource could not be found.
INVALID_REQUESTThe request sent to the vendor was invalid.
MISCONFIGUREDThe vendor is not configured correctly.
FEATURE_DISABLEDThe vendor-hosted payment method feature is disabled.
NO_ACCOUNTS_FOUNDNo payment methods were found for the customer.
UNEXPECTED_ERRORAn unexpected error occurred while retrieving payment methods.