Stable Mint Payments

Appearance

Withdrawal Process ​

A withdrawal allows you to transfer funds from a user's account back to their specified bank account. This guide explains how to initiate a withdrawal by making a POST request to the Stable Mint API.

Overview ​

The withdrawal process enables you to send funds directly to a user's bank account after generating a valid withdrawal reference. There are two types of withdrawal flows available:

Withdrawal Types ​

  1. Stable Mint-Managed Customer Withdrawal (/withdrawal/hosted) - For users where Stable Mint manages the customer relationship and provides a hosted withdrawal interface
  2. Partner-Managed Customer Withdrawal (/withdrawal/partner-managed-customer) - For partners who manage their own customers and handle the complete withdrawal flow

Creating a Withdrawal Request ​

Authentication Headers ​

All withdrawal requests require the following headers:

http
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 Withdrawal ​

Use this option when Stable Mint handles the customer relationship and provides a hosted withdrawal interface for users to complete their banking details.

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

Request Body ​

json
{
  "userUniqueId": "string", // Required - Unique identifier for the user
  "amount": number, // Required - Withdrawal amount
  "currency": "string", // Required - Currency code (e.g., EUR, USD)
  "withdrawalReason": "string", // Required - "CashOut" or "Refund"
  "idempotencyKey": "string", // Optional - Prevents duplicate requests
  "websiteReference": "string", // Optional - Reference returned in notifications
  "customFields": {}, // Optional - Additional data for notifications
  "blockchainOriginAddress": "string", // Optional - Origin wallet address
  "successUrl": "string", // Optional - URL for successful withdrawal redirect
  "supportUrl": "string", // Optional - URL for support page
  "exitUrl": "string", // Optional - URL for when user abandons the flow
  "errorUrl": "string" // Optional - URL for error redirect
}

Required Fields:

  • userUniqueId - Unique identifier for the user
  • amount - Withdrawal amount
  • currency - Currency code (e.g., EUR, USD)
  • withdrawalReason - Reason for withdrawal: CashOut or Refund

Optional Fields:

  • idempotencyKey - Unique key to prevent duplicate requests
  • websiteReference - Your internal reference
  • customFields - Additional JSON data
  • blockchainOriginAddress - Origin wallet address for blockchain tracking
  • successUrl - URL to redirect after successful withdrawal
  • supportUrl - URL for support page
  • exitUrl - URL when user abandons the flow
  • errorUrl - URL to redirect on error

Response ​

A successful response will return:

json
{
  "url": "https://checkout.stablemint.io/withdrawal/550e8400-e29b-41d4-a716-446655440000",
  "reference": "WIV6VHU4I"
}

Response Fields:

  • url (string) - The hosted withdrawal URL to redirect users to
  • reference (string) - Unique reference identifier for the withdrawal request

Blockchain Signature Callback ​

After a user completes the withdrawal flow through the hosted interface, Stable Mint will send a callback to your configured webhook endpoint with blockchain transaction data that requires your signature to complete the withdrawal process on-chain.

Callback Payload ​

The callback will be sent as a POST request to your webhook URL with the following JSON payload:

json
{
  "amount": 100.50,
  "calldata": "0x...",
  "contractAddress": "0x..."
}

Payload Fields:

  • amount - The withdrawal amount
  • calldata - The encoded transaction data that needs to be signed and published on-chain
  • contractAddress - The smart contract address where the transaction should be executed

For information about response requirements and retry mechanisms, refer to our Webhooks Page.

Processing the Callback ​

To complete the withdrawal process:

  1. Receive the callback POST request at your configured webhook endpoint
  2. Extract the calldata and contractAddress from the payload
  3. Sign the transaction using your authorized wallet/signer
  4. Publish the signed transaction to the blockchain at the specified contractAddress
  5. Respond with a 2xx status code to acknowledge receipt

Important

The withdrawal will only be completed once the transaction is successfully signed and published on-chain. Ensure your system has proper error handling and monitoring for this process.

Option 2: Partner-Managed Customer Withdrawal ​

Use this option when you manage your own customers and handle the complete withdrawal flow.

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

Request Body ​

json
{
  // User details
  "userId": "user_123456",
  "userEmail": "[email protected]",
  "userCountryCode": "US",
  "userIp": "192.168.1.1",

  // Payment details
  "remittanceInformation": "Withdrawal for order #12345",
  "amount": 100.50,
  "currency": "USD",
  "withdrawalReason": "CashOut", // 'CashOut' | 'Refund'

  // Creditor bank details
  "creditorAccount": "US12345678901234567890",
  "creditorBic": "CHASUS33", // Optional
  "creditorCountryCode": "US",
  "creditorName": "John Doe",
  "creditorAddress": "123 Main St, New York, NY 10001", // Optional

  // Optional fields
  "idempotencyKey": "unique-key-123", // Optional - prevents duplicate withdrawals
  "websiteReference": "order-12345", // Optional - your internal reference
  "customFields": { // Optional - any additional JSON data
    "orderId": "12345",
    "customData": "value"
  },
  "userKyc": { // Optional - user KYC information
    "fullName": "John Doe",
    "residenceAddress": "123 Main St, New York, NY 10001",
    "citizenshipCountryCode": "US",
    "dateOfBirth": "1990-01-01",
    "gender": "M",
    "mobilePhone": "+1234567890",
    "personalIdentificationNumber": "123456789",
    "placeOfBirth": "New York"
  }
}

Required Fields:

  • userId - Your unique identifier for the user
  • userEmail - User's email address
  • userCountryCode - User's country code (ISO 3166-1 alpha-2)
  • userIp - User's IP address
  • remittanceInformation - Description of the withdrawal
  • amount - Withdrawal amount
  • currency - Currency code (e.g., USD, EUR)
  • withdrawalReason - Reason for withdrawal: CashOut or Refund
  • creditorAccount - Bank account number or IBAN
  • creditorCountryCode - Creditor's country code
  • creditorName - Name of the account holder

Optional Fields:

  • creditorBic - Bank's BIC/SWIFT code
  • creditorAddress - Creditor's address
  • idempotencyKey - Unique key to prevent duplicate requests
  • websiteReference - Your internal reference
  • customFields - Additional JSON data
  • userKyc - User's KYC information (all subfields are optional)

Response ​

A successful withdrawal initiation will return:

json
{
  "reference": "WIV6VHU4I"
}

Response Fields:

  • reference (string) - Unique reference identifier for the withdrawal request

This reference can be used to track the withdrawal status and will be included in webhook notifications.

Webhooks ​

Once a withdrawal is initiated, Stable Mint will send webhooks to the URL specified in your dashboard. Webhooks contain detailed information about the transaction, including its status and any relevant reference numbers.

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

Copyright © 2025 Stable mint Ltd. All rights reserved.