Skip to main content

​
Overview

This guide walks you through creating your first offramp transaction.

​
Prerequisites

  • A StablePay partner account
  • Your API key (get it from the Dashboard)
  • A webhook endpoint to receive notifications

​
Step 1: Create a User

First, create a user who will receive the INR payout: 
curl -X POST https://api.stablepay.global/v2/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rahul Kumar",
    "mobile": "+919876543210",
    "email": "rahul@example.com",
    "externalId": "user_123",
    "deviceId": "device-fingerprint-12345"
  }'
Response: 
{
  "success": true,
  "data": {
    "userId": "usr_abc123",
    "depositAddresses": {
      "evm": "0x742d35Cc6634C0532925a3b844Bc9e7595f3A123",
      "solana": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
    },
    "kycStatus": "pending"
  }
}

​
Step 2: Verify Mobile & Email

Before KYC, users must verify their contact information via OTP. Send Mobile OTP: 
curl -X POST https://api.stablepay.global/v2/users/usr_abc123/verify/mobile/send \
  -H "Authorization: Bearer YOUR_API_KEY"
Verify Mobile OTP: 
curl -X POST https://api.stablepay.global/v2/users/usr_abc123/verify/mobile/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"otp": "123456"}'
Send & Verify Email OTP (if email was provided): 
# Send OTP
curl -X POST https://api.stablepay.global/v2/users/usr_abc123/verify/email/send \
  -H "Authorization: Bearer YOUR_API_KEY"

# Verify OTP
curl -X POST https://api.stablepay.global/v2/users/usr_abc123/verify/email/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"otp": "654321"}'
KYC endpoints will return 400 Verification Required if mobile/email is not verified.

​
Step 3: Complete KYC

The user must complete both Basic KYC and Extended KYC before they can receive payouts.

​
KYC Requirements

TypeStepsPurpose
Basic KYCAadhaar (DigiLocker) + PAN + Face + BankIdentity & account verification
Extended KYCProfile + Document + DeclarationRegulatory compliance

​
Quick KYC Flow

1. Submit Profile (Extended KYC) 
curl -X POST https://api.stablepay.global/v2/users/usr_abc123/kyc/profile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dateOfBirth": "1990-05-15",
    "nationality": "Indian",
    "addressLine1": "123 Main Street",
    "city": "Mumbai",
    "state": "Maharashtra",
    "pincode": "400001",
    "deviceId": "device-fingerprint-12345"
  }'
2. Aadhaar via DigiLocker (Basic KYC) 
curl -X POST https://api.stablepay.global/v2/users/usr_abc123/kyc/digilocker/init \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deviceId": "device-fingerprint-12345"}'
Redirect the user to the returned redirectUrl to complete DigiLocker verification. 3. PAN Verification (Basic KYC) 
curl -X POST https://api.stablepay.global/v2/users/usr_abc123/kyc/pan/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "panNumber": "ABCDE1234F",
    "deviceId": "device-fingerprint-12345"
  }'
4. Document Upload (Extended KYC) 
# Get upload URL
curl -X POST https://api.stablepay.global/v2/users/usr_abc123/kyc/document/upload-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "passport",
    "fileName": "passport.pdf",
    "mimeType": "application/pdf",
    "fileSize": 2048576,
    "deviceId": "device-fingerprint-12345"
  }'

# Upload file to returned URL, then confirm
curl -X POST https://api.stablepay.global/v2/users/usr_abc123/kyc/document \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "passport",
    "s3Key": "returned-s3-key",
    "fileName": "passport.pdf",
    "fileSize": 2048576,
    "mimeType": "application/pdf",
    "deviceId": "device-fingerprint-12345"
  }'
5. Declaration (Extended KYC) 
curl -X POST https://api.stablepay.global/v2/users/usr_abc123/kyc/declaration \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "occupation": "salaried",
    "incomeRange": "10l_to_25l",
    "isPep": false,
    "declarationAccepted": true,
    "deviceId": "device-fingerprint-12345"
  }'
If user declares isPep: true (Politically Exposed Person), KYC will be automatically rejected.
6. Face Liveness (Basic KYC) 
# Initialize
curl -X POST https://api.stablepay.global/v2/users/usr_abc123/kyc/face/init \
  -H "Authorization: Bearer YOUR_API_KEY"

# After user completes face capture, verify
curl -X POST https://api.stablepay.global/v2/users/usr_abc123/kyc/face/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "returned-session-id"}'
7. Bank Account Verification (Basic KYC) 
curl -X POST https://api.stablepay.global/v2/users/usr_abc123/kyc/bank/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "1234567890",
    "ifsc": "HDFC0001234",
    "accountHolderName": "Rahul Kumar",
    "deviceId": "device-fingerprint-12345"
  }'
You’ll receive a webhook when KYC is complete: 
{
  "event": "user.kyc_updated",
  "timestamp": "2025-01-05T10:30:00Z",
  "data": {
    "userId": "usr_abc123",
    "kyc": {
      "level": "basic",
      "status": "verified"
    }
  }
}
See the KYC Flow Guide for detailed API documentation.

​
Step 4: Create a Transaction

Once KYC is verified, create a transaction. Each transaction requires a unique idempotency key (UUID) to prevent duplicates: 
curl -X POST https://api.stablepay.global/v2/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "userId": "usr_abc123",
    "amount": "100",
    "asset": "USDC",
    "network": "polygon"
  }'
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"
  }
}

​
Step 5: Deposit Stablecoins

Send stablecoins to the deposit address. Our system detects the deposit automatically. Webhook - Deposit Detected: 
{
  "event": "transaction.deposit_detected",
  "timestamp": "2025-01-05T10:35:00Z",
  "data": {
    "transactionId": "txn_xyz789",
    "deposit": {
      "amount": "100",
      "asset": "USDC",
      "network": "polygon",
      "txHash": "0x123...",
      "confirmations": 1
    }
  }
}

​
Step 6: Automatic Payout

Once the deposit reaches required confirmations (30 for Polygon), we automatically initiate the INR payout: Webhook - Payout Completed: 
{
  "event": "transaction.payout_completed",
  "timestamp": "2025-01-05T10:40:00Z",
  "data": {
    "transactionId": "txn_xyz789",
    "payout": {
      "amount": "8407.75",
      "currency": "INR",
      "status": "completed",
      "utr": "123456789012"
    }
  }
}

​
Complete Flow Diagram

​
Next Steps

KYC Flow

Learn about the KYC verification process

Webhook Setup

Configure your webhook endpoint