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 Model

Before creating payment sessions, partners must be onboarded to the partner-managed customer flow.

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 the partner-managed customer flow. Contact your account manager to enable it 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.

Endpoint: /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