Stable Mint Payments

Appearance

Embedded Session ​

An embedded session allows you to integrate the payment flow directly into your website using StableMint's widget. This guide explains how to create an embedded session by making a POST request to the StableMint 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 StableMint's hosted checkout page.

Key Differences ​

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

Creating a session ​

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

https://paymentinitiationservice-rest.stablemint.io/session/embedded

Headers ​

Include the following headers in your request:

http
signature: SHA256 hashed signature of the string "<TIMESTAMP>,<API_SECRET>,<UNIQUE_USER_ID>"
timestamp: <CURRENT UNIX TIMESTAMP>
api_key: <YOUR API KEY>

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

Request Body ​

The request body must include the following required fields:

json
{
  "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:

json
{
  "sessionId": "string", // UUID of the created session
  "expiresAt": "integer", // Unix timestamp when the session expires
  "allowedPaymentMethods": [
    {
      "paymentMethod": "integer", // Payment method identifier
      "countryCodes": [ // Optional - List of supported countries
        {
          "code": "string", // Country code
          "name": "string" // Country name
        }
      ]
    }
  ],
  "savedBanks": [ // Optional - List of user's saved banks
    {
      "country": "string", // Bank's country
      "logo": "string", // Bank's logo URL
      "bankName": "string", // Bank's name
      "bankId": "integer", // Bank's identifier
      "lastUsed": "string", // Last used timestamp
      "validated": "boolean" // Whether the bank is validated
    }
  ],
  "reference": "string" // Unique reference for the session
}

Endpoint ​


POST
/session/embedded

Request Body​

JSON
{
"currency": "string",
"userId": "string",
"userEmail": "string",
"userCountryCode": "string",
"amount": 0,
"idempotencyKey": "string",
"websiteReference": "string",
"userKyc": {
"fullName": "string",
"citizenshipCountryCode": "string",
"residenceAddress": "string",
"dateOfBirth": "string",
"placeOfBirth": "string",
"gender": "string",
"mobilePhone": "string",
"personalIdentificationNumber": "string"
},
"customFields": "string"
}

Responses​

OK
JSON
{
"sessionId": "string",
"expiresAt": 0,
"allowedPaymentMethods": [
{
"paymentMethod": 0,
"countryCodes": [
{
"code": "string",
"name": "string"
}
]
}
],
"savedBanks": [
{
"country": "string",
"logo": "string",
"bankName": "string",
"bankId": 0,
"lastUsed": "string",
"validated": true
}
],
"reference": "string"
}

Webhooks ​

Once a user completes their payment flow, StableMint 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