Skip to main content
POST
https://api.stablepay.global
/
v2
/
users
/
{userId}
/
kyc
/
document
/
upload-url
curl -X POST "https://api.stablepay.global/v2/users/{userId}/kyc/document/upload-url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "passport",
    "fileName": "passport_scan.pdf",
    "mimeType": "application/pdf",
    "fileSize": 2048576,
    "deviceId": "device_abc123"
  }'

{
  "success": true,
  "data": {
    "uploadUrl": "https://stablepay-kyc-documents.s3.ap-south-1.amazonaws.com/kyc/user_123/passport/abc-def-ghi.pdf?X-Amz-Algorithm=...",
    "s3Key": "kyc/user_123/passport/abc-def-ghi.pdf",
    "expiresIn": 300,
    "method": "PUT",
    "headers": {
      "Content-Type": "application/pdf"
    }
  }
}

​
Overview

This endpoint generates a presigned URL for securely uploading identity documents to AWS S3. The upload process has two steps:
  1. Get upload URL (this endpoint) - Get a presigned S3 URL
  2. Confirm upload - After uploading to S3, confirm the upload via POST /kyc/document

​
Supported Document Types

Document TypeValue
Passportpassport
Driving Licensedriving_license
Aadhaar Cardaadhaar
Voter IDvoter_id

​
Supported File Types

  • JPEG (image/jpeg)
  • PNG (image/png)
  • WebP (image/webp)
  • PDF (application/pdf)
Maximum file size: 10 MB

​
Request Body

​
documentType
string
required
Type of document: passport, driving_license, aadhaar, or voter_id
​
fileName
string
required
Original file name with extension
​
mimeType
string
required
File MIME type: image/jpeg, image/png, image/webp, or application/pdf
​
fileSize
number
required
File size in bytes (max 10485760 = 10 MB)
​
deviceId
string
required
Unique device identifier for FIU compliance

​
Response

​
success
boolean
Whether the URL was generated successfully
​
data
object
curl -X POST "https://api.stablepay.global/v2/users/{userId}/kyc/document/upload-url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "passport",
    "fileName": "passport_scan.pdf",
    "mimeType": "application/pdf",
    "fileSize": 2048576,
    "deviceId": "device_abc123"
  }'

{
  "success": true,
  "data": {
    "uploadUrl": "https://stablepay-kyc-documents.s3.ap-south-1.amazonaws.com/kyc/user_123/passport/abc-def-ghi.pdf?X-Amz-Algorithm=...",
    "s3Key": "kyc/user_123/passport/abc-def-ghi.pdf",
    "expiresIn": 300,
    "method": "PUT",
    "headers": {
      "Content-Type": "application/pdf"
    }
  }
}

​
Upload to S3

After receiving the presigned URL, upload the file directly to S3: 
curl -X PUT "${uploadUrl}" \
  -H "Content-Type: application/pdf" \
  --data-binary "@passport_scan.pdf"
The presigned URL expires in 5 minutes. Complete the upload promptly.

​
Confirm Upload

After successfully uploading to S3, confirm the upload: 
curl -X POST "https://api.stablepay.global/v2/users/{userId}/kyc/document" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "passport",
    "s3Key": "kyc/user_123/passport/abc-def-ghi.pdf",
    "fileName": "passport_scan.pdf",
    "fileSize": 2048576,
    "mimeType": "application/pdf",
    "deviceId": "device_abc123"
  }'