Stable Mint Payments

Appearance

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 StableMint 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 StableMint after generating a valid session URL. This is different from an embedded session, where the payment flow is integrated directly into your website using StableMint's widget.

Key Differences ​

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

Creating a session URL ​

To create a hosted session, send a POST request to:

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

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, // 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
  }
}

Endpoint ​


POST
/session/hosted

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",
"successUrl": "string",
"supportUrl": "string",
"exitUrl": "string",
"errorUrl": "string"
}

Responses​

OK
JSON
{
"url": "string",
"expiresAt": 0,
"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. 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