Authentication API Documentation

Request Balance

Returns your current available balance.

Request Fields

Success Response

{
  "status": "ok",
  "message": "",
  "code": 200,
  "balance": 100
}

cURL Example

curl -X POST "https://api.algorithmic.cash/request_balance" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "merchant_id=2" \
  -d "hash=GENERATED_HASH"

PHP example script: example/request_balance.php

Maintenance Status

Returns the current maintenance mode state of the service.

Request Fields

Success Response

{
  "status": "ok",
  "message": "",
  "code": 200,
  "maintenance_mode": 0
}

Field Values

cURL Example

curl -X POST "https://api.algorithmic.cash/request_status" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "merchant_id=2" \
  -d "hash=GENERATED_HASH"

PHP example script: example/request_status.php

Create Pay-in Request

Creates a pay-in request and returns a hosted redirect URL for the customer.

Request Fields

Validation Rules

• For all merchants except ID 1, amount must be between 100 and 50000.
• Amount must be a whole number (non-fractional blockchain values only).
• Returns HTTP 503 when the service is in maintenance mode.

Success Response

{
  "status": "ok",
  "payin_id": 12345,
  "redirect_url": "https://pay.tradingbot.website/loading.html?id=<payin_id_hash>"
}

Redirect the customer's browser to redirect_url to complete payment.

Business Validation Errors

Invalid amount:

{
  "status": "error",
  "code": 1,
  "message": "Invalid amount",
  "redirect_url": "https://pay.tradingbot.website/invalid_request.html"
}

cURL Example

curl -X POST "https://api.algorithmic.cash/request_payin" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "hash=GENERATED_HASH" \
  -d "amount=500" \
  -d "merchant_id=2" \
  -d "merchant_tx_id=TX$(date +%Y%m%d%H%M%S)" \
  -d "customer_mobile_hash=SHA256_CUSTOMER_MOBILE" \
  -d "success_url=https://merchant.example/success" \
  -d "failure_url=https://merchant.example/failure" \
  -d "return_url=https://merchant.example/return" \
  -d "support_url=https://merchant.example/support" \
  -d "ipn_url=https://merchant.example/ipn" \
  -d "timestamp=$(date +%s)"

For a complete signed request script see example/request_payin.php.

Pay-in Status

Fetch the status and details of a pay-in request using your own transaction ID.

Request Fields

Success Response

{
  "status": "ok",
  "message": "",
  "code": 200,
  "info": {
    "id": 12345,
    "status": 0,
    "merchant_tx_id": "TX202604150001",
    "request_amount": "100",
    "request_dt": "2026-04-15 10:25:10",
    "fee_amount": "0",
    "utr": "X1234567890",
    "chargeback_status": 0
  }
}

Response info Fields

Error: Not Found

{
  "status": "error",
  "message": "Payin request not found",
  "code": 404
}

cURL Example

curl -X POST "https://api.algorithmic.cash/request_payin_status" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "merchant_id=2" \
  -d "hash=GENERATED_HASH" \
  -d "merchant_tx_id=TX202604150001"

PHP example script: example/request_payin_status.php

Create Pay-out Request

Creates a pay-out request for a customer withdrawal and returns the internal pay-out ID.

Request Fields

Validation Rules

• For all merchants except ID 1, amount must be between 500 and 10000.
• Amount must be a whole number (non-fractional blockchain values only).
• Returns HTTP 503 when the service is in maintenance mode.

Success Response

{
  "status": "ok",
  "payout_id": 12345
}

Business Validation Errors

Invalid amount:

{
  "status": "error",
  "code": 1,
  "message": "Invalid amount"
}

Invalid beneficiary details:

{
  "status": "error",
  "code": 2,
      "message": "Invalid Beneficiary account details"
}

cURL Example

curl -X POST "https://api.algorithmic.cash/request_payout" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "hash=GENERATED_HASH" \
  -d "amount=500" \
  -d "merchant_id=2" \
  -d "merchant_tx_id=TX$(date +%Y%m%d%H%M%S)" \
  -d "customer_mobile_hash=SHA256_CUSTOMER_MOBILE" \
  -d "ipn_url=https://merchant.example/ipn" \
  -d "beneficiary_name=John Doe" \
  -d "beneficiary_account_number=1234567890" \
  -d "beneficiary_ifsc_code=IFSC0001" \
  -d "remark=Withdrawal" \
  -d "timestamp=$(date +%s)"

For a complete signed request script see example/request_payout.php.

Pay-out Status

Fetch the status and details of a pay-out request using your own transaction ID.

Request Fields

Success Response

{
  "status": "ok",
  "message": "",
  "code": 200,
  "info": {
    "id": 12345,
    "status": 0,
    "merchant_tx_id": "TX202604150001",
    "customerhash": "9fdac6...",
    "amount": "500",
    "request_dt": "2026-04-15 10:25:10",
    "fee_amount": "0",
    "beneficiary_name": "John Doe",
    "beneficiary_account_number": "1234567890",
    "beneficiary_ifsc_code": "IFSC0001",
    "processed_dt": null,
    "utr": null
  }
}

Response info Fields

Error: Not Found

{
  "status": "error",
  "message": "Payout request not found",
  "code": 404
}

cURL Example

curl -X POST "https://api.algorithmic.cash/request_payout_status" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "merchant_id=2" \
  -d "hash=GENERATED_HASH" \
  -d "merchant_tx_id=TX202604150001"

PHP example script: example/request_payout_status.php

IPN Callback (Merchant Webhook)

When a transaction event occurs the system automatically POSTs a JSON notification to the ipn_url you provided in the pay-in or pay-out request. The IPN covers both payin and payout transaction types.

IP Whitelist

All IPN callbacks originate from a fixed server IP. Your endpoint should reject requests from any other source with a 401 UNAUTHORIZED response.

Request Headers (sent by server)

Request Body Sent to Your Endpoint

{
  "merchant_id": 2,
  "tx_type": "payin",
  "ipn_url": "https://merchant.example/ipn",
  "merchant_tx_id": "TX202604150001",
  "reference_no": 12345,
  "status": 1,
  "timestamp": 1776176293
}

Pay-in Status Values

Payout Status Values

Required Response from Your Endpoint

Your endpoint must return HTTP 200 with:

{
  "success": 1
}

Verifying the Signature

The x-signature header is a lowercase SHA-512 hex digest. To verify it, reconstruct the hash from the IPN payload using the same generate_hash helper and compare it with hash_equals.

Hash construction (matches generate_hash.php):

1. Extract the following fields from the JSON payload in order:
   key, customer_mobile_hash, merchant_id, merchant_tx_id, support_url, return_url, success_url, failure_url, ipn_url, tx_type, amount, reference_no, status, fee_amount, rolling_reserve_amount, rolling_reserve_release_dt, beneficiary_account_number, beneficiary_name, beneficiary_ifsc_code, remark, timestamp
2. Join the values with |, then append | and your private key (used as the salt).
3. Compute strtolower(hash('sha512', $hashString)).
4. Compare the result to the x-signature header using a timing-safe comparison.

// PHP example
require_once 'generate_hash.php';

$json       = file_get_contents('php://input');
$headers    = getallheaders();
$signature  = $headers['x-signature'] ?? null;
$params_arr = json_decode($json, true);

// Verify IP
if ($_SERVER['REMOTE_ADDR'] !== '94.237.42.85') {
    die("UNAUTHORIZED");
}

// Verify signature
$msg_hash    = generate_hash($privateKey, $params_arr);
$is_verified = hash_equals($msg_hash, $signature);

if (!$is_verified) {
    echo "Invalid signature";
    exit(1);
}

// Handle by tx_type
$params  = json_decode($json);
$tx_type = $params->tx_type;

switch ($tx_type) {
    case 'payin':
        switch ($params->status) {
            case -3: /* Chargeback */ break;
            case -2: /* No Trader */  break;
            case -1: /* Invalid request */ break;
            case  1: /* Success */    break;
            case  2: /* Settled */    break;
        }
        break;
    case 'payout':
        switch ($params->status) {
            case -3: /* Refunded */ break;
            case -2: /* Rejected */ break;
            case -1: /* Invalid */  break;
            case  1: /* Success */  break;
        }
        break;
}

header('Content-Type: application/json');
echo json_encode(['success' => 1]);

Error Reference

PHP Example Scripts

• example/generate_hash.php - shared hash helper
• example/request_balance.php - check account balance
• example/request_payin.php - create pay-in request
• example/request_payin_status.php - check pay-in status
• example/request_payout.php - create pay-out request
• example/request_payout_status.php - check pay-out status
• example/request_status.php - check maintenance status