Hosted Session

A hosted session is an initial step to start a payment process using our API. This guide explains how to create a hosted session by making a POST request to the Stable Mint API.

For a general overview of payment sessions and when to use each type, see our Payment Session Overview.

Overview

The hosted session allows you to initiate a payment flow where users are redirected to a checkout page hosted by Stable Mint after generating a valid session URL. This is different from an embedded session, where the payment flow is integrated directly into your website using Stable Mint's widget.

Key Differences

• Hosted Session: Users are redirected to Stable Mint's hosted checkout page
• Embedded Session: Payment flow is embedded within your website using Stable Mint's widget

Session Types

There are two types of hosted sessions:

1. Stable Mint-Managed Customer Session (/session/hosted) - For anonymous users where Stable Mint manages the customer relationship
2. Partner-Managed Customer Session (/session/hosted/partner-managed-customer) - For partners who manage their own customers and user identification

Creating a hosted session

Authentication Headers

All hosted session requests require the following headers:

ApiKey: <YOUR API KEY>
Timestamp: <CURRENT UNIX TIMESTAMP IN SECONDS>
Signature: <BASE64 ENCODED RSA-SHA256 SIGNATURE>

The signature is generated by signing the string <TIMESTAMP>,<API_SECRET>,<REQUEST_BODY> with your private RSA key.

For detailed instructions on generating the signature, refer to our Authentication Page.

Option 1: Stable Mint-Managed Customer Session

Use this option for anonymous users where Stable Mint handles customer management.

Endpoint: POST https://paymentinitiationservice-rest.stablemint.io/session/hosted

Request Body

{
  "userCountryCode": "string", // Required - Location of the user (country alpha-2)
  "currency": "string", // Required - Currency code (e.g., EUR)
  "amount": number, // Required - Payment amount (min 0.1, max 10 in sandbox)
  "successUrl": "string", // Required - URL for successful payment redirect
  "supportUrl": "string", // Required - URL for support page
  "exitUrl": "string", // Required - URL for when user abandons the flow
  "errorUrl": "string", // Required - URL for error redirect
  "idempotencyKey": "string", // Optional - Prevents duplicate requests
  "websiteReference": "string", // Optional - Reference returned in notifications
  "customFields": {}, // Optional - Additional data for notifications
  "blockchainDestinationAddress": "string", // Optional - Final destination wallet address
  "paymentMethod": "string" // Optional - Preferred payment method ("ManualBankTransfer" or "OpenBanking")
}

Response

A successful response will return:

{
  "url": "https://checkout.stablemint.io/sessions/550e8400-e29b-41d4-a716-446655440000?requireAuth=true",
  "expiresAt": 1690123456,
  "reference": "7PKZU6F2J"
}

Response Fields:

• url (string) - The complete hosted checkout URL to redirect users to
• expiresAt (number) - Unix timestamp (seconds) when the session expires
• reference (string) - Unique reference identifier for the session

Option 2: Partner-Managed Customer Session

Use this option when you manage your own customers and user identification.

Endpoint: POST https://paymentinitiationservice-rest.stablemint.io/session/hosted/partner-managed-customer

Request Body

{
  "userId": "string", // Required - Unique identifier for the user
  "userEmail": "string", // Required - User's email address
  "userCountryCode": "string", // Required - User's country code (alpha-2 format)
  "currency": "string", // Required - Currency code (e.g., EUR)
  "amount": number, // Required - Payment amount (min 0.1, max 10 in sandbox)
  "successUrl": "string", // Required - URL for successful payment redirect
  "supportUrl": "string", // Required - URL for support page
  "exitUrl": "string", // Required - URL for when user abandons the flow
  "errorUrl": "string", // Required - URL for error redirect
  "idempotencyKey": "string", // Optional - Prevents duplicate requests
  "websiteReference": "string", // Optional - Reference returned in notifications
  "customFields": {}, // Optional - Additional data for notifications
  "userKyc": {
    "fullName": "string", // Optional - User's full name
    "citizenshipCountryCode": "string", // Optional - Citizenship country code
    "residenceAddress": "string", // Optional - Residential address
    "dateOfBirth": "string", // Optional - Format: YYYY-MM-DD
    "placeOfBirth": "string", // Optional - Place of birth
    "gender": "string", // Optional - Gender
    "mobilePhone": "string", // Optional - Mobile phone number
    "personalIdentificationNumber": "string" // Optional - ID number
  }
}

Response

A successful response will return:

{
  "url": "https://payments.stablemint.io/partner-sessions/550e8400-e29b-41d4-a716-446655440000",
  "expiresAt": 1690123456,
  "reference": "ref_partner_session_xyz789"
}

Response Fields:

• url (string) - The complete hosted checkout URL to redirect users to
• expiresAt (number) - Unix timestamp (seconds) when the session expires
• reference (string) - Unique reference identifier for the session

Webhooks

Once a user completes their payment flow, Stable Mint will send a webhook to the URL specified in the dashboard. The webhook contains information about the transaction and can be used for further processing or verification of the payment.

To know more about webhooks, refer to our Webhooks Page.

Best Practices

1. Always validate the session URL before redirecting users
2. Implement proper error handling for expired sessions
3. Store the session reference for future reference
4. Monitor webhook notifications for payment status updates
5. Implement proper timeout handling for abandoned sessions