Embedded Session

An embedded session allows you to integrate the payment flow directly into your website using Stable Mint's widget. This guide explains how to create an embedded 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 embedded session enables you to provide a seamless payment experience by embedding the payment flow directly within your website. This is different from a hosted session, where users are redirected to Stable Mint's hosted checkout page.

Key Differences

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

Creating a session

To create an embedded session, send a POST request to:

https://paymentinitiationservice-rest.stablemint.io/session/embedded/partner-managed-customer

Headers

Include the following headers in your request:

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.

Request Body

The request body must include the following required fields:

{
  "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, // Optional - Payment amount
  "idempotencyKey": "string", // Optional - Prevents duplicate requests
  "websiteReference": "string", // Optional - Reference returned in 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
  },
  "customFields": {} // Optional - Additional data for notifications
}

Response

A successful response will include:

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "expiresAt": 1690123456,
  "allowedPaymentMethods": [
    {
      "paymentMethod": "OpenBanking",
      "countryCodes": ["GB", "IE", "DE", "FR"]
    },
    {
      "paymentMethod": "ManualBankTransfer",
      "countryCodes": null
    }
  ],
  "savedBanks": [
    {
      "country": "GB",
      "logo": "https://cdn.bank.com/logo.png",
      "bankName": "Example Bank",
      "bankId": 12345,
      "lastUsed": "2023-07-15T10:30:00Z",
      "validated": true
    }
  ],
  "reference": "ref_embedded_abc123def456"
}

Response Fields:

• sessionId (string) - UUID of the created embedded session
• expiresAt (number) - Unix timestamp (seconds) when the session expires
• allowedPaymentMethods (array) - List of available payment methods for this session
  • paymentMethod (string) - Payment method type ("OpenBanking", "ManualBankTransfer")
  • countryCodes (array|null) - List of supported country codes, or null if all countries are supported
• savedBanks (array|null) - List of customer's previously saved banks (only for partner-managed customers)
  • country (string) - Country code where the bank operates
  • logo (string) - URL to the bank's logo image
  • bankName (string) - Display name of the bank
  • bankId (number) - Unique identifier for the bank
  • lastUsed (string) - ISO 8601 timestamp of when the bank was last used
  • validated (boolean) - Whether the bank account has been validated
• 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. Implement proper error handling for the embedded widget
2. Handle session expiration gracefully
3. Store the session reference and ID for future reference
4. Monitor webhook notifications for payment status updates
5. Implement proper loading states while the widget initializes
6. Ensure your website's CSP (Content Security Policy) allows the widget to load
7. Test the integration thoroughly in sandbox environment before going live