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. You must provide essential details about the transaction, including the user's information and banking credentials.

---

Creating a Withdrawal Request

To initiate a withdrawal, send a POST request to: https://paymentinitiationservice-rest.stablemint.io/withdrawal/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, where:

• <TIMESTAMP> is the same value as in the Timestamp header
• <API_SECRET> is your API secret (provided by StableMint)
• <REQUEST_BODY> is the raw JSON request body

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

Request Body

The request body should be a JSON object with the following fields:

{
  // 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:

{
  "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.