Skip to main content
Version: v1

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
    A required header for non-production environments. Accepts values: "dev", "stage", or "test". Used to specify the environment for the request.
  • X-source
    A header to specify the Source System Identifier. Must be a string up to 50 characters.
  • Merchant Id
    Merchant Id is a unique identifier for a merchant system, created during onboarding and used in API requests.

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.
  • Agent
    Information about the agent acting on behalf of the customer in the session.
  • Consent
    Consent information collected during 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.

Payment Object Fields​

Statement Descriptors​

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.

DescriptionMax LengthValid characters pattern
Statement Descriptor10^(?=.*[a-zA-Z])[a-zA-Z0-9 -.]10$
Statement Descriptor Suffix10^(?=.*[a-zA-Z])[a-zA-Z0-9 -.]10$
  • MerchantTransactionId
    A unique identifier for each payment or transaction. If a payment fails, a new merchantTransactionId is required for a retry.
  • Payment Amount
    The amount to be paid, specified in cents (integer, minimum 1, maximum 100000000).
  • Payment Description
    A short description to help users identify the payment, up to 100 characters.
  • Payment Type
    Indicates the type of payment, such as SALE or PRE_AUTH. This field is deprecated.
  • Authorize Card
    A flag to indicate if a card should be authorized for an amount, requiring a later capture to complete the transaction.
  • Partial Authorization
    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.
  • Statement Descriptor Suffix
    A dynamic suffix for the statement descriptor, must contain at least one letter and follow the specified pattern.
  • Metadata (Payment)
    Key-value pairs for additional information about a payment, order, or customer, with limits on entry count and length.
  • Status
    Indicates the current state of a payment or refund, such as INITIATED, COMPLETED, FAILED, etc.
  • Refund Reason
    Specifies the reason for a refund, such as REQUESTED_BY_CUSTOMER, DUPLICATE, or FRAUDULENT.
  • Payment Cancellation Reason
    Specifies the reason for payment cancellation, such as DUPLICATE, FRAUDULENT, REQUESTED_BY_CUSTOMER, or ABANDONED.

Customer Object Fields​

  • Customer First Name
    The first name of the customer making the payment.
  • Customer Last Name
    The last name of the customer making the payment.
  • Customer Email
    The email address of the customer making the payment.
  • Customer Phone Number
    The phone number of the customer, including country code and number.
  • Customer Date of Birth
    The date of birth of the customer, in YYYY-MM-DD format.
  • Customer Zip5
    The 5-digit ZIP code of the customer.
  • Customer HSID
    The HealthSafeId of the customer, used for identification.
  • Customer EnterpriseId
    The enterprise identifier of the customer, used for identification.
  • Metadata (Customer)
    Key-value pairs for additional information about a customer, with limits on entry count and length.
  • Agent
    Represents an agent acting on behalf of a customer, with required fields like firstName, lastName, and userId.
  • Consent
    Represents the consent collected from the customer or agent, including consent text and collection details.

PaymentMethod Object Fields​

  • PaymentMethod
    Represents a saved payment method, such as a card or bank account, including its type, details, nickname, and source provider.
  • paymentMethodDetails
    Contains the details of the payment method, such as card or bank account information, used for processing payments.
  • Card Category
    A classification for cards, such as MANUFACTURER_CARD, which can include a list of medications.
  • Medication
    Represents a medication with a label and value, used in card categories.