Skip to main content

​
Overview

In the architecture of a payment API, the payment session and payment object are distinct but related concepts that manage the complete lifecycle of a transaction. This separation is particularly important when interacting with hardware terminal devices, where timing and state management are critical. The system provides both a payment_session_id and a payment_id in responses, creating a structured approach that manages:
  • The initial user interaction and preparation phase
  • The subsequent financial transaction execution
  • State transitions and error handling
  • Terminal device coordination
This two-tier approach ensures reliable transaction processing while maintaining clear separation between preparation and execution phases.

​
The Payment Session

​
What is a Payment Session?

A payment session is a temporary and secure context that holds all the necessary information about a potential transaction. Think of it as a digital workspace or preparation area for a specific payment interaction. The payment session acts as an intermediary layer between your application and the terminal hardware, managing the complex coordination required for secure payment processing.

​
Key Characteristics

Payment sessions have a limited lifetime and are designed to handle the preparation phase before actual financial transactions occur.

Data Aggregation

Purpose: Gathers and validates all preliminary transaction details before processing begins.Details Collected:
  • Transaction amount and currency
  • Items being purchased (line items)
  • Terminal device identification
  • Customer reference information
  • Payment method preferences
This validation happens before any interaction with payment networks or terminal hardware.

State Management

Purpose: Tracks the complete lifecycle of the payment preparation process.States Include:
  • ACTIVE - Ready for payment processing
  • COMPLETED - Payment successfully processed
  • FAILED - Error during payment attempt
  • CANCELED - Session terminated before completion
Each state transition is carefully managed to ensure data consistency.

Security

Purpose: Provides a secure boundary for handling sensitive transaction data.Security Features:
  • Isolated data environment
  • Secure session identifier reference
  • Controlled data access patterns
  • Reduced sensitive data transmission
The payment_session_id serves as a secure token for all session operations.

Terminal Abstraction

Purpose: Manages terminal device preparation and coordination.Terminal Operations:
  • Device initialization and configuration
  • Payment method setup
  • Transaction parameter loading
  • Hardware status monitoring
Abstracts the complexity of different terminal types and protocols.

​
Session Identifier

The payment_session_id is the unique identifier for this entire preparatory phase. This identifier serves several critical functions:
  • Reference: Retrieve or update session details as needed
  • Tracking: Monitor session progress and state changes
  • Security: Acts as an authentication token for session operations
  • Audit: Provides traceability for transaction preparation
You can use the payment_session_id to query session status, update transaction details, or cancel the session before payment completion.

​
The Payment Object

​
What is a Payment Object?

A payment object represents the successful completion of a financial transaction. It is the authoritative, immutable record created after the payment system confirms that funds have been successfully captured or transferred. Unlike the payment session which handles preparation, the payment object is created only after a transaction has been successfully processed through the payment network.

​
Key Characteristics

Payment objects are permanent records of completed financial transactions and serve as the legal and audit trail for money movement.

Transaction Record

Purpose: Creates an immutable record of successful financial transactions.Creation Process:
  • Triggered by successful payment processing
  • Generated after payment gateway confirmation
  • Contains complete transaction details
  • Serves as official receipt and audit trail
Transaction Flow:
  1. Customer initiates payment (card tap, QR scan, etc.)
  2. Payment gateway processes the transaction
  3. Upon approval, payment object is created
  4. Funds are captured or authorized
The payment object is not the trigger for the transaction—it’s the result of a successful one.

Financial Operations

Purpose: Enables post-transaction financial operations on completed payments.Available Operations:
  • Voiding: Cancel transactions before settlement
  • Refunds: Return funds after settlement
  • Partial Refunds: Return portion of payment amount
  • Captures: Complete authorized transactions
Settlement Timeline:
  • Pre-settlement: Transactions can be voided
  • Post-settlement: Transactions can be refunded
  • Settlement Window: Typically 24-48 hours after processing
The payment_id is tied to actual money movement, so use it carefully for financial operations.

​
Payment States

Payment objects have specific states that reflect their current status in the payment lifecycle:

SUCCEEDED

The transaction has been successfully processed and funds have been captured or authorized. This is the most common end state for successful payments.

VOIDED

The transaction has been canceled before settlement. Funds are returned to the customer, and no settlement will occur. This can only happen within the void window (typically before end-of-day processing).

​
Key Differences

Understanding the fundamental differences between payment sessions and payment objects is crucial for proper API usage and transaction management.

Payment Session Characteristics

Lifecycle Stage: Preparation and setup phaseCreation Timing: Created before any payment attempt beginsPrimary States:
  • ACTIVE - Ready for payment processing
  • COMPLETED - Successfully transitioned to payment
  • FAILED - Error during preparation
  • CANCELED - Terminated before completion
Financial Impact: No money movement - purely preparatoryPrimary Use Cases:
  • Transaction data collection and validation
  • Terminal device preparation and setup
  • Session state monitoring and management
  • Error handling during preparation phase
Use payment sessions for setup, validation, and terminal coordination before actual payment processing.

Payment Object Characteristics

Lifecycle Stage: Transaction completion and post-processingCreation Timing: Created after successful payment completionPrimary States:
  • SUCCEEDED - Transaction successfully processed
  • VOIDED - Transaction canceled before settlement
  • FAILED - Transaction processing error
Financial Impact: Direct money movement - represents actual financial transactionsPrimary Use Cases:
  • Voiding transactions before settlement
  • Processing refunds after settlement
  • Transaction history and audit trails
  • Financial reconciliation and reporting
Use payment objects for financial operations only. These represent actual money movement.

​
Decision Framework

Choose payment_session_id when you need to:
  • Check preparation status before payment
  • Update transaction details before processing
  • Cancel a session before payment begins
  • Monitor terminal readiness
  • Handle errors during setup phase
Choose payment_id when you need to:
  • Void a transaction before settlement
  • Process refunds after settlement
  • Retrieve transaction history
  • Perform financial reconciliation
  • Generate receipts or invoices

​
Error Handling Scenarios

Common Causes:
  • Invalid terminal ID
  • Insufficient permissions
  • Network connectivity issues
  • Invalid transaction parameters
Recovery: Retry with corrected parameters or contact support for terminal issues.
Common Causes:
  • Device offline or powered off
  • Network connectivity problems
  • Terminal maintenance or updates
  • Hardware malfunction
Recovery: Check terminal status, restart device, or use alternative terminal.
Common Causes:
  • Card declined by issuer
  • Insufficient funds
  • Expired card
  • Network timeout
Recovery: Session remains active for retry attempts or cancellation.