Convenient Checkout API (v2)

• Applicability:
  • Session flows that create a payment transaction during session processing such as PAYMENT and PAYMENT_WITH_WALLET.

• Applicability:
  • Session modes that require customer context (for example, PAYMENT_WITH_WALLET).
• For session flows that support both customer and guest contexts, the presence of the customer object indicates a customer-scoped session, while its absence (or null value) indicates a guest session.

• Must be unique per merchant.
• Allows the merchant to retry the same payment request using the same merchantTransactionId up to 4 times (5 total attempts including the initial one).
• After 4 retries (5th attempt), a new merchantTransactionId must be used.

• Constraints:
  • Key length: 1-40 characters
  • Value length: 1-100 characters
• Non-PII recommendation: Avoid storing sensitive personal information (SSN, DOB, full card numbers).

• Applicability: Only applicable for CARD payment methods. Ignored for BANK_ACCOUNT payment method.
• Required: Yes, for CARD payment methods involving FSA/HSA cards.

• Applicability: CARD payment method only. Ignored for BANK_ACCOUNT payment types.
• Constraint: When authorizeCard is true, partialAuthorization should also be true — the two flags are complementary and should not be used in isolation.

When true — two-step flow (authorize, then capture):

• Funds are held (authorized) but not immediately charged (captured)
• Payment status transitions to AUTHORIZED and awaits explicit capture
• A subsequent POST /payments/{paymentId}/capture call is required to complete the charge
• Authorization holds expire after 7 days; the payment must be re-authorized after expiry
• Typical use cases: hotel/rental pre-authorization holds, split-tender with deferred capture, payment verification

When false — one-step flow (authorize + capture):

• Authorization and capture occur simultaneously in a single operation
• The customer's card is charged immediately
• Payment status transitions to COMPLETED on success

• Applicability: CARD payment method only. Ignored for BANK_ACCOUNT payment types.
• Constraint: Should be set to true when authorizeCard is true.

When true:

• The card issuer may approve a lesser amount than requested
• Payment succeeds with the authorized (partial) amount; status transitions to COMPLETED or AUTHORIZED
• The merchant is responsible for handling the remaining balance (e.g., charging a second payment method)
• Particularly important for healthcare cards (FSA/HSA) where the eligible amount may be less than the total

When false:

• The full requested amount must be authorized or the payment is declined
• No partial approvals are accepted from the card issuer

• Applicability: Required when payment method type is BANK_ACCOUNT. Null allowed for CARD-only payments.
• Constraint: When consent type is PPD, the agent field at the payment level is required.
• Consent records are immutable once created and should be retained for compliance purposes.

Customer Identification:

• At least one customer identifier must be provided for customer lookup:
  • enterpriseIdentifier
  • hsid
  • metadata
• Lookup Priority: When multiple identifiers are provided, below is the lookup priority order:
  • enterpriseIdentifier (highest priority)
  • hsid
  • metadata (lowest priority)
• Fallback Behavior:
  • If enterpriseIdentifier lookup fails → falls back to hsid
  • If hsid lookup fails → falls back to metadata
  • If metadata lookup fails → customer lookup fails

• Required: Yes, if the payment is being cancelled.
• Value must be one of the following:
  • DUPLICATE: Cancellation due to duplicate payment
  • FRAUDULENT: Cancellation due to suspected fraud
  • REQUESTED_BY_CUSTOMER: Cancellation requested by customer
  • ABANDONED: Cancellation due to abandoned payment (e.g. customer did not complete 3DS authentication)

• Required: No. When omitted or null, the full authorized amount is captured.
• Must be between 1 and 99,999,999 cents (i.e. up to $999,999.99).
• Must not have a fractional component — integer cents only.

• Required: Yes, for linked refund
• Payment must exist and have status COMPLETED.
• Provide either paymentId or refundAllocations[0].paymentMethodId.
  • The request must not include both fields.
  • Exactly one of the two fields is required.

• When provided, the value must be one of the allowed values below:
  • REQUESTED_BY_CUSTOMER: Customer requested the refund
  • DUPLICATE: Customer was charged multiple times for the same product/service
  • FRAUDULENT: Payment was found to be fraudulent

• Constraints:
  • Key length: 1-40 characters
  • Value length: 1-100 characters
• Non-PII recommendation: Avoid storing sensitive personal information (SSN, DOB, full card numbers).

• Required: Yes, for partial linked and un-linked refunds.
• Constraints:
  • Max items: 2 for linked refunds
  • Max items: 1 for un-linked refunds.
• When not provided, linked refunds will be processed as full refunds.

Applicability:

• TEXT_TO_ADD: Delivers via SMS.

  • Session purpose:
    • PAYMENT_METHOD_ENTRY.
  • Use when the customer needs to add a payment method via text.

• EMAIL_TO_ADD: Delivers via email.

  • Session purpose:
    • PAYMENT_METHOD_ENTRY.
  • Use when the customer needs to add a payment method via email.

• TEXT_TO_PAY: Delivers via SMS.

  • Session purpose:
    • PAYMENT.
  • Use when the customer is ready to make a payment via text.

• EMAIL_TO_PAY: Delivers via email.

  • Session purpose:
    • PAYMENT.
  • Use when the customer is ready to make a payment via email.