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 '
{
  "userId": "<string>",
  "amount": "<string>",
  "asset": "<string>",
  "network": "<string>",
  "partnerReference": "<string>"
}
'

​
Create Transaction

Creates a new transaction for a user to deposit stablecoins.
Idempotency Required: This endpoint requires an Idempotency-Key header to prevent duplicate transactions.

​
Headers

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

​
Body Parameters

​
userId
string
required
The user ID
​
amount
string
required
Amount in USD (e.g., “100”)
​
asset
string
required
Stablecoin: USDC or USDT
​
network
string
required
Blockchain: polygon, ethereum, arbitrum, base, solana
​
partnerReference
string
Your internal transaction reference

​
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 '{
    "userId": "usr_abc123",
    "amount": "100",
    "asset": "USDC",
    "network": "polygon",
    "partnerReference": "order_456"
  }'
Generate a new UUID for each transaction request.

​
Response

{
  "success": true,
  "data": {
    "transactionId": "txn_xyz789",
    "depositAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f3A123",
    "depositNetwork": "polygon",
    "depositAsset": "USDC",
    "expectedAmount": "100",
    "quote": {
      "exchangeRate": 84.50,
      "grossInr": "8450.00",
      "netInr": "8407.75"
    },
    "expiresAt": "2025-01-06T10:30:00Z"
  }
}

​
Errors

CodeDescription
IDEMPOTENCY_KEY_REQUIREDMissing Idempotency-Key header
USER_NOT_FOUNDUser doesn’t exist
KYC_INCOMPLETEUser hasn’t completed KYC
NO_BANK_ACCOUNTNo verified bank account
PENDING_TRANSACTION_EXISTSUser has an active transaction
AMOUNT_TOO_LOWBelow minimum ($10)
AMOUNT_TOO_HIGHAbove maximum ($10,000)

​
Idempotency Behavior

We follow the Stripe/Circle pattern for idempotency. If you send the same idempotency key again, you’ll receive the cached response from the original request. This allows safe retries without creating duplicate transactions.
ScenarioResponse
New unique key201 - Transaction created
Same key (retry)200 - Cached response returned

​
Detecting Replayed Responses

When a response is replayed from cache, the response includes:
  • Header: Idempotent-Replayed: true
  • Body field: "idempotentReplayed": true
200
{
  "success": true,
  "data": {
    "transactionId": "45c25be8-d508-4031-863f-bf0f02ddf285",
    "depositAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f3A123",
    "status": "pending_deposit",
    ...
  },
  "idempotentReplayed": true
}

​
Best Practices

  1. Generate a UUID v4 for each unique transaction
  2. Reuse the same key when retrying a failed request
  3. Check idempotentReplayed to know if response is from cache
  4. Keys expire after 24 hours - after that, the same key creates a new transaction