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.
| Description | Max Length | Valid characters pattern |
|---|---|---|
| Statement Descriptor | 10 | ^(?=.*[a-zA-Z])[a-zA-Z0-9 -.]10$ |
| Statement Descriptor Suffix | 10 | ^(?=.*[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.