Skip to main content
POST
/
v2
/
transactions
Create Transaction
curl --request POST \
  --url https://api.stablepay.global/v2/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "type": "<string>",
  "userId": "<string>",
  "amount": "<string>",
  "asset": "<string>",
  "network": "<string>",
  "partnerReference": "<string>",
  "metadata": {}
}
'
{
  "success": true,
  "data": {
    "transactionId": "txn_xyz789",
    "type": "sell",
    "status": "deposit_pending",
    "depositAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f3A123",
    "depositNetwork": "ethereum",
    "depositAsset": "USDT",
    "expectedAmount": "100",
    "quote": {
      "exchangeRate": 84.50,
      "feePercent": 0.005,
      "feeInr": "42.25",
      "grossInr": "8450.00",
      "netInr": "8407.75"
    },
    "expiresAt": "2025-06-16T10:30:00Z"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.stablepay.global/llms.txt

Use this file to discover all available pages before exploring further.

​
Create Transaction

Creates a new transaction. The type parameter determines the flow. See the Transaction Lifecycle guide for status flows and the Pool Settlement guide for the two-step pool workflow.
Idempotency Required: Include an Idempotency-Key header (UUID) to prevent duplicate transactions. See Idempotency for details.

​
Headers

​
Idempotency-Key
string
required
A unique UUID for each transaction. One key = one transaction.

​
Body Parameters

​
type
string
required
Transaction type: sell, pool_settlement, or buy
​
userId
string
required
The user ID. Must have completed KYC.
​
amount
string
required
Amount in stablecoin units (e.g., “100”)
​
asset
string
required
Stablecoin: USDC or USDT
​
network
string
required
Blockchain: polygon, ethereum, arbitrum, base, tron
​
partnerReference
string
Your internal reference ID
​
metadata
object
Custom key-value metadata

​
Request

curl -X POST https://api.stablepay.global/v2/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "type": "sell",
    "userId": "usr_abc123",
    "amount": "100",
    "asset": "USDT",
    "network": "ethereum",
    "partnerReference": "order_456"
  }'
Only available on accounts with transactionMode: sell or transactionMode: both.

​
Response

{
  "success": true,
  "data": {
    "transactionId": "txn_xyz789",
    "type": "sell",
    "status": "deposit_pending",
    "depositAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f3A123",
    "depositNetwork": "ethereum",
    "depositAsset": "USDT",
    "expectedAmount": "100",
    "quote": {
      "exchangeRate": 84.50,
      "feePercent": 0.005,
      "feeInr": "42.25",
      "grossInr": "8450.00",
      "netInr": "8407.75"
    },
    "expiresAt": "2025-06-16T10:30:00Z"
  }
}

​
Errors

CodeDescriptionApplies To
IDEMPOTENCY_KEY_REQUIREDMissing Idempotency-Key headerAll
INVALID_TYPEInvalid transaction typeAll
USER_NOT_FOUNDUser doesn’t existAll
KYC_INCOMPLETEUser hasn’t completed KYCAll
NO_BANK_ACCOUNTNo verified bank accountAll
AMOUNT_TOO_LOWBelow minimum ($10)All
AMOUNT_TOO_HIGHAbove maximum ($50,000)All
PENDING_TRANSACTION_EXISTSUser has an active transactionsell
POOL_SELL_NOT_ALLOWEDNot enabled or insufficient pool balancepool_settlement
SWEEP_FAILEDFailed to initiate pool wallet sweeppool_settlement
TRANSACTION_TYPE_NOT_ALLOWEDAccount not configured for this transaction typesell, pool_settlement
{
  "success": true,
  "data": {
    "transactionId": "txn_xyz789",
    "type": "sell",
    "status": "deposit_pending",
    "depositAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f3A123",
    "depositNetwork": "ethereum",
    "depositAsset": "USDT",
    "expectedAmount": "100",
    "quote": {
      "exchangeRate": 84.50,
      "feePercent": 0.005,
      "feeInr": "42.25",
      "grossInr": "8450.00",
      "netInr": "8407.75"
    },
    "expiresAt": "2025-06-16T10:30:00Z"
  }
}