Authentication

All API requests must be authenticated using API keys.

API Keys

Each merchant can generate one or more API keys from the merchant portal. Each API key has:

• Key: A unique string used to authenticate requests
• Status: Active or Inactive
• IP Restrictions: Optional list of allowed IP addresses
• Last Used: Timestamp and IP of last usage

Required Headers

Every API request must include the API key header:

X-API-Key: your_api_key_here
Content-Type: application/json

Alternative header name (both are supported):

Api-Key: your_api_key_here
Content-Type: application/json

How It Works

1. Request with API Key: Include your API key in the X-API-Key or Api-Key header
2. Validation: Server validates the API key is active and belongs to a merchant
3. IP Check: If IP restrictions are configured, validates request IP is allowed
4. Request Processing: Request is processed with merchant context
5. Usage Tracking: API key's last used timestamp and IP are updated

Example Requests

cURL

curl -X POST "https://dev-crypto-portal.kesspay.io/api/v1/payins" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.50,
    "memo": "Invoice #123",
    "out_trade_no": "ORDER-123"
  }'

JavaScript/Node.js

const axios = require('axios');

const apiKey = 'your_api_key_here';
const baseUrl = 'https://dev-crypto-portal.kesspay.io';

async function createPayin() {
  try {
    const response = await axios.post(
      `${baseUrl}/api/v1/payins`,
      {
        amount: 100.5,
        memo: 'Invoice #123',
        out_trade_no: 'ORDER-123'
      },
      {
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': apiKey
        }
      }
    );

    console.log('Payin created:', response.data);
    return response.data;
  } catch (error) {
    console.error('API Error:', error.response?.data || error.message);
    throw error;
  }
}

PHP

<?php

$apiKey = 'your_api_key_here';
$url = 'https://dev-crypto-portal.kesspay.io/api/v1/payins';
$data = [
    'amount' => 100.50,
    'memo' => 'Invoice #123',
    'out_trade_no' => 'ORDER-123'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: ' . $apiKey,
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $result = json_decode($response, true);
    print_r($result);
} else {
    echo "Error: HTTP {$httpCode}\n";
    echo $response;
}

IP Restrictions

You can restrict API keys to specific IP addresses for added security in the merchant portal.

When IP restrictions are configured:

• Requests from unlisted IPs will receive a 403 Forbidden error
• Leave empty to allow requests from any IP address

Security Best Practices

1. Never expose your API key - Keep it secure on your server
2. Use HTTPS only - All API calls must use HTTPS in production
3. Rotate keys regularly - Change your API keys periodically
4. Use IP restrictions - Limit API key usage to known IP addresses when possible
5. Monitor for unusual activity - Check your audit logs regularly
6. Deactivate unused keys - Disable or delete API keys you're not using

Testing Authentication

Test your authentication by calling the balance endpoint:

curl -X GET "https://dev-crypto-portal.kesspay.io/api/v1/balance" \
  -H "X-API-Key: your_api_key_here"

Expected response:

{
  "data": {
    "balance": "1234.56",
    "currency": "USD"
  }
}

Common Authentication Errors

Status Code	Error Message	Description
401	Unauthenticated. Please provide valid credentials.	API key not provided, invalid, or inactive
403	This API key is not authorized from your IP address.	Request IP is not in the allowed list
429	Too many authentication attempts. Please try again in X seconds.	Too many failed authentication attempts from your IP

Error Response Examples

Missing or Invalid API Key:

{
  "success": false,
  "message": "Unauthenticated. Please provide valid credentials.",
  "errors": null
}

IP Not Allowed:

{
  "success": false,
  "message": "This API key is not authorized from your IP address.",
  "errors": null
}