Payment Session

A payment session is a mandatory channel that enables end-users to complete a payment flow. Every payment transaction is associated with exactly one session, which serves as the foundation for the entire payment process.

Overview

Payment sessions are the core building blocks of Stable Mint's payment infrastructure. They provide a secure and controlled environment for processing payments, ensuring that each transaction is properly tracked, authenticated, and completed.

Customer Management Models

Before creating payment sessions, partners must be onboarded to use one of two customer management flows:

Stable Mint-Managed Customers

In this model, Stable Mint owns and manages the customer relationship. This is ideal for partners who want a simplified integration without managing customer data.

Characteristics:

• Stable Mint handles all customer KYC/AML requirements
• Customer data is stored and managed by Stable Mint
• Partners don't need to manage user identities
• Simplified integration with minimal data requirements
• Available for hosted sessions only (/session/hosted)

Best for:

• Anonymous or one-time transactions
• Partners who don't want to manage customer data
• Quick marketplace integrations
• When customer relationship isn't critical to your business

Partner-Managed Customers

In this model, the partner owns and manages their customer relationships. Partners maintain control over their customer data while leveraging Stable Mint's payment infrastructure.

Characteristics:

• Partner retains ownership of customer relationships
• Partner provides customer identification (userId, email, country)
• Partner can optionally provide KYC data
• Customer data is linked to the partner's account
• Available for both hosted and embedded sessions

Best for:

• Businesses with existing customer bases
• When maintaining customer relationships is important
• Recurring payment scenarios
• When you need to track customer payment history

Important: Partners must be specifically onboarded and configured to use either Stable Mint-managed or partner-managed customer flows. Contact your account manager to enable the appropriate flow for your use case.

Types of Sessions

Stable Mint offers two types of payment sessions, each designed for different integration scenarios:

Hosted Session

A hosted session redirects users to Stable Mint's hosted checkout page. This is the simplest integration method and requires minimal development effort.

Available variants:

• Stable Mint-Managed: /session/hosted - For anonymous users
• Partner-Managed: /session/hosted/partner-managed-customer - For identified customers

Best for:

• Quick integration
• Standard checkout flows
• When you want to maintain a consistent checkout experience
• When you don't need to customize the checkout UI

Learn more about Hosted Sessions →

Embedded Session

An embedded session integrates the payment flow directly into your website using Stable Mint's widget. This provides a seamless experience for your users without leaving your website.

Available variants:

• Partner-Managed only: /session/embedded/partner-managed-customer - Requires customer identification

Best for:

• Custom checkout experiences
• Single-page applications
• When you want to maintain your website's look and feel
• When you need more control over the payment flow

Learn more about Embedded Sessions →

Key Features

Both session types provide:

1. Security

   • Encrypted communication
   • Session-based authentication
   • Fraud prevention measures

2. Flexibility

   • Support for multiple payment methods
   • Customizable user experience
   • Webhook notifications

3. Reliability

   • Idempotent requests
   • Error handling
   • Session expiration management

Implementation Considerations

When choosing between session types, consider:

1. Technical Requirements

   • Hosted sessions require redirect handling
   • Embedded sessions require widget integration
   • Both require proper error handling

2. User Experience

   • Hosted sessions provide a consistent experience
   • Embedded sessions offer more customization
   • Both support mobile and desktop devices

3. Development Effort

   • Hosted sessions are quicker to implement
   • Embedded sessions require more integration work
   • Both require proper testing

4. Maintenance

   • Both types require monitoring
   • Both need proper error handling
   • Both should implement webhook processing

Best Practices

1. Session Management

   • Always validate session status
   • Handle session expiration
   • Implement proper error handling

2. Security

   • Use HTTPS for all communications
   • Implement proper authentication
   • Follow security best practices

3. User Experience

   • Provide clear error messages
   • Implement proper loading states
   • Handle edge cases gracefully

4. Testing

   • Test in sandbox environment
   • Verify all payment flows
   • Test error scenarios

Getting Started

To implement payment sessions:

1. Choose the appropriate session type based on your needs
2. Follow the specific implementation guide for your chosen type
3. Implement proper error handling and webhook processing
4. Test thoroughly in the sandbox environment
5. Monitor and maintain your implementation

For detailed implementation guides, refer to:

• Hosted Session Documentation
• Embedded Session Documentation