Stixramp - KYC API Documentation

Stixramp KYC API allows merchants to manage client identity verification through our KYC (Know Your Customer) system. This API provides endpoints for client sign-up and KYC status monitoring.

Introduction

The KYC API is designed to help merchants integrate identity verification into their applications. Clients can complete their KYC verification through a seamless redirect flow, and merchants can monitor the verification status in real-time.

How It Works

Sign Up: Merchant calls the sign-up endpoint with client's email
Redirect: Client is redirected to KYC verification page (via internal URL)
Verification: Client completes KYC verification process
Status Check: Merchant checks KYC status and card limits

⚠️ Important Notes

All endpoints require API key authentication via X-API-KEY header
API keys are managed through the admin panel
Domain whitelisting is enforced for security
KYC redirect URLs use internal routing for security
Redirect URLs expire after 10 minutes

Authentication

All KYC API endpoints require authentication using an API key provided in the request header.

Request Headers

Header	Type	Required	Description
`X-API-KEY`	string	Required	Your partner API key (obtained from admin panel)
`Content-Type`	string	Required	Must be `application/json`

API Key Setup

API keys are created and managed in the admin panel
Each API key has a whitelist of allowed domains (CORS protection)
API keys track request statistics (usage monitoring)
Invalid or inactive API keys will return 401 Unauthorized

Endpoint URL

POST https://widget.stixramp.com/api/kyc/signup

Creates a new client account and returns a KYC redirect URL. The client will be automatically signed up with the provided email address, and a secure KYC verification URL will be generated.

Request Body (JSON)

Parameter	Type	Required	Description
`email`	string	Required	Client's email address (must be valid email format)

Example Request

cURL Example

curl -X POST 'https://widget.stixramp.com/api/kyc/signup' \
  -H 'X-API-KEY: sk_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "client@example.com"
  }'

Example Response

Success Response

200 OK

{ "success": true, "message": "User successfully signed up", "kyc_url": "https://widget.stixramp.com/api/kyc/redirect?token=a1b2c3d4e5f6..." }

Next Steps

Redirect your client to the kyc_url returned in the response
The URL is an internal redirect that will automatically route to the KYC verification page
The redirect token expires after 10 minutes (single-use)
After KYC completion, client will be redirected to our success/failure pages (/redirect/kyc/success or /redirect/kyc/failed)

⚠️ Important

The kyc_url uses internal routing for security and privacy
If KYC access token generation fails, kyc_url will not be included in response
Client data (email, UUID, bearer token) is automatically stored in our database
If email already exists, the existing account will be used

POSTGet KYC Status

Endpoint URL

POST https://widget.stixramp.com/api/kyc/status

Retrieves the KYC verification status and card limits for a client. This endpoint returns the current KYC status (complete, incomplete, failed, etc.) along with EUR card limits.

Request Body (JSON)

Parameter	Type	Required	Description
`email`	string	Required	Client's email address (must match the email used in sign-up)

Example Request

cURL Example

curl -X POST 'https://widget.stixramp.com/api/kyc/status' \
  -H 'X-API-KEY: sk_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "client@example.com"
  }'

Example Response

Success Response

200 OK

{ "success": true, "email": "client@example.com", "kyc": { "status": "complete", "complete": true, "message": "KYC procedures are successfully complete." }, "card_limits": { "day": { "total": "30000.00", "remain": "25000.00" }, "month": { "total": "50000.00", "remain": "40000.00" }, "min": "10.00", "max": "15000.00" } }

Response Fields

kyc.status: Current KYC status (see KYC Statuses section)
kyc.complete: Boolean indicating if KYC is complete
kyc.message: Human-readable message explaining the status
card_limits: EUR card limits (null if not available)
card_limits.day: Daily limits (total and remaining)
card_limits.month: Monthly limits (total and remaining)
card_limits.min/max: Minimum and maximum transaction amounts

KYC Levels and Payment Limits

Our KYC system uses a tiered verification system with different verification levels. Each level unlocks specific payment limits for card transactions.

KYC Level 1

KYC Level 1 is the basic verification level that requires:

Identity Document: Government-issued ID card (passport, national ID, or driver's license)
Selfie Verification: Live selfie photo matching the identity document

✅ Payment Limits After KYC Level 1

Once a client completes KYC Level 1 verification, they can use card payment with the following limits:

Daily Limit: 30,000 EUR per day
Monthly Limit: 50,000 EUR per month
No Additional Verification Required: These limits apply without any additional verification steps

Payment Limits Example

The card_limits field in the status response shows the current limits for EUR transactions:

Limit Type	Maximum Amount (EUR)	Description
`day.total`	30,000 EUR	Maximum amount that can be processed in a single day
`day.remain`	Variable	Remaining daily limit (decreases with each transaction)
`month.total`	50,000 EUR	Maximum amount that can be processed in a single month
`month.remain`	Variable	Remaining monthly limit (decreases with each transaction)
`min`	10.00 EUR	Minimum transaction amount
`max`	15,000 EUR	Maximum amount per single transaction

📋 Important Notes

Limits apply only to card payments
Limits are reset daily (at 00:00 UTC) and monthly (on the 1st of each month)
If a client exceeds their daily/monthly limit, they will need to wait until the limit resets
KYC Level 1 must be complete before these limits apply
Limits are tracked automatically based on completed transactions

KYC Statuses

The KYC status field can have the following values, each with a specific meaning and required action:

Status	Description	Message	Action Required
`complete`	KYC verification is complete	"KYC procedures are successfully complete."	✅ Client can proceed with transactions
`incomplete`	Not enough documents provided	"Not enough documents have been provided; SumSub hasn't started the verification."	⚠️ Client needs to provide more documents
`failed_attempt`	First verification attempt failed	"The first attempt to pass the verification failed. Try again."	⚠️ Client can retry verification
`failed`	Verification permanently failed	"The verification failed. Contact Support."	❌ Contact Support
`under_review`	Documents are being verified	"SumSub is verifying the documents. Appears only after the user has finished uploading and submitting all required documents and the verification process has started on SumSub's side."	⏳ Wait for verification to complete
`unknown`	Status could not be determined	"KYC status unknown."	⚠️ Retry status check or redirect to KYC

✅ Status: complete

When KYC status is complete, the client has successfully passed identity verification and can proceed with transactions. The complete field will be true.

⚠️ Status: failed

When KYC status is failed, the verification has permanently failed. The merchant should contact Support as the client cannot retry on their own. The complete field will be false.

Error Handling

Status Code	Error Type	Description	Solution
200	Success	Request processed successfully	-
400	Bad Request	Missing or invalid parameters	Check request body parameters
401	Unauthorized	Invalid or missing API key	Check X-API-KEY header
403	Forbidden	Domain not authorized or API key inactive	Check domain whitelist in admin panel
404	Not Found	Client not found (status endpoint)	Client must sign up first
500	Server Error	Internal server error	Contact support or try again later

Error Response Examples

Missing API Key

401 Unauthorized

{ "error": "API Key Required", "message": "No API key provided in X-API-KEY header." }

Invalid API Key

401 Unauthorized

{ "error": "Invalid API Key", "message": "The API key provided is invalid or inactive." }

Unauthorized Domain

403 Forbidden

{ "error": "Access Denied", "message": "Your domain is not authorized to use this service." }

Client Not Found

404 Not Found

{ "error": "client_not_found", "message": "Client not found. Please sign up first." }

Integration Example (PHP)

// Step 1: Sign up client
$signupResponse = makeApiRequest('POST', 'https://widget.stixramp.com/api/kyc/signup', [
    'X-API-KEY' => 'sk_your_api_key',
    'Content-Type' => 'application/json'
], [
    'email' => 'client@example.com'
]);

if ($signupResponse['success'] && isset($signupResponse['kyc_url'])) {
    // Step 2: Redirect client to KYC verification
    header('Location: ' . $signupResponse['kyc_url']);
    exit;
}

// Step 3: Later, check KYC status
$statusResponse = makeApiRequest('POST', 'https://widget.stixramp.com/api/kyc/status', [
    'X-API-KEY' => 'sk_your_api_key',
    'Content-Type' => 'application/json'
], [
    'email' => 'client@example.com'
]);

if ($statusResponse['success']) {
    $kycStatus = $statusResponse['kyc']['status'];
    $isComplete = $statusResponse['kyc']['complete'];
    $message = $statusResponse['kyc']['message'];
    
    if ($isComplete) {
        // Client can proceed with transactions
        echo "KYC Complete: " . $message;
    } else {
        // Show status message to client
        echo "KYC Status: " . $message;
    }
}

Stixramp - KYC API Documentation

Introduction

How It Works

⚠️ Important Notes

Authentication

Request Headers

API Key Setup

POSTSign Up Client

Request Body (JSON)

Next Steps

⚠️ Important

POSTGet KYC Status

Request Body (JSON)

Response Fields

KYC Levels and Payment Limits

KYC Level 1

✅ Payment Limits After KYC Level 1

Payment Limits Example

📋 Important Notes

KYC Statuses

✅ Status: complete

⚠️ Status: failed

Error Handling

Integration Example (PHP)