AlgoCash API Documentation

This document describes the public API exposed by this project for merchant integrations.

Base URL

Use your deployed domain. Example:

https://authentication.php.dev

All endpoints are POST endpoints and accept application/x-www-form-urlencoded (or multipart form fields).

Authentication

Authentication is form-field based. Every request must include your public API key.

FieldRequiredDescription
keyrequiredYour merchant public API key
merchant_idrequiredYour merchant ID
hashrequiredSHA-512 request signature (see below)

Hash Algorithm (for request_payin.php and request_payout.php)

Concatenate the following fields in order, separated by |, then append your private key:

key|amount|customer_mobile_hash|merchant_id|merchant_tx_id|support_url|return_url|success_url|failure_url|ipn_url|beneficiary_account_number|beneficiary_name|beneficiary_ifsc_code|remark|timestamp|PRIVATE_KEY

Hash using SHA-512 and output as lowercase hex. Fields not applicable to a request may be left empty, but their positions must still be preserved.

PHP example:

function generate_hash($privateKey, $params)
{
        $fields = ['key','amount','customer_mobile_hash','merchant_id','merchant_tx_id',
           'support_url','return_url','success_url','failure_url','ipn_url',
           'beneficiary_account_number','beneficiary_name','beneficiary_ifsc_code',
           'remark','timestamp'];

    $values = array_map(fn($f) => $params[$f] ?? '', $fields);
    $hashString = implode('|', $values) . '|' . $privateKey;
    return strtolower(hash('sha512', $hashString));
}

Reusable helper script: example/generate_hash.php

IP Whitelisting

API calls are accepted only from allowed source IP addresses.

  • A global IP whitelist is enforced server-side.
  • Per-merchant whitelist entries may also apply.

Blocked requests receive HTTP 401 with message Unauthorized IP address.

Standard Response Envelope

All endpoints return JSON in this shape:

{
  "status": "ok|error",
  "message": "",
  "code": 200
}
On errors, status is "error" and message contains a human-readable reason. HTTP status codes mirror the code field.

Request Balance

Returns your current available balance.

POST /request_balance.php

Request Fields

FieldRequiredDescription
keyrequiredMerchant public API key
merchant_idrequiredYour merchant ID
hashrequiredSHA-512 signature — see Overview tab

Success Response

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

cURL Example

curl -X POST "https://authentication.php.dev/request_balance.php" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "merchant_id=2" \
  -d "hash=GENERATED_HASH"

PHP example script: example/balance.php

Maintenance Status

Returns the current maintenance mode state of the service.

POST /request_status.php

Request Fields

FieldRequiredDescription
keyrequiredMerchant public API key
merchant_idrequiredYour merchant ID
hashrequiredSHA-512 signature — see Overview tab

Success Response

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

Field Values

ValueMeaning
0Service is available
1Service is in maintenance mode

cURL Example

curl -X POST "https://authentication.php.dev/request_status.php" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "merchant_id=2" \
  -d "hash=GENERATED_HASH"

PHP example script: example/status.php

Create Pay-in Request

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

POST /request_payin.php

Request Fields

FieldRequiredDescription
keyrequiredMerchant public API key
hashrequiredSHA-512 signature — see Overview tab
amountrequiredPayment amount (integer, 100–75000 for most merchants)
merchant_idrequiredYour merchant ID
merchant_tx_idrequiredUnique transaction ID from your system
support_urlrequiredCustomer-facing support page URL
return_urlrequiredURL to redirect customer after payment attempt
success_urlrequiredURL on successful payment
failure_urlrequiredURL on failed payment
ipn_urlrequiredWebhook URL for IPN callbacks
customer_mobile_hashrequiredSHA-256 hash of the customer mobile number
timestamprequiredUnix timestamp (seconds)
customer_mobileoptionalCustomer mobile number
If any URL field is sent as an empty string, the API falls back to that merchant's configured URL value from the database.

Validation Rules

  • For all merchants except ID 1, amount must be between 100 and 75000.
  • 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://authentication.php.dev/request_payin.php" \
  -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/payin_request.php.

Pay-in Status

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

POST /request_payin_status.php

Request Fields

FieldRequiredDescription
keyrequiredMerchant public API key
merchant_idrequiredYour merchant ID
hashrequiredSHA-512 signature — see Overview tab
merchant_tx_idrequiredYour original transaction ID

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",
    "chargeback_status": 0
  }
}

Response info Fields

FieldDescription
idInternal pay-in record ID
statusTransaction status code
merchant_tx_idYour original transaction ID
request_amountAmount originally requested
fee_amountFee charged
chargeback_statusChargeback state
request_dtRequest creation datetime

Error: Not Found

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

cURL Example

curl -X POST "https://authentication.php.dev/request_payin_status.php" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "merchant_id=2" \
  -d "hash=GENERATED_HASH" \
  -d "merchant_tx_id=TX202604150001"

PHP example script: example/payin_status.php

Create Pay-out Request

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

POST /request_payout.php

Request Fields

FieldRequiredDescription
keyrequiredMerchant public API key
hashrequiredSHA-512 signature — see Overview tab
amountrequiredPay-out amount (integer, 100–75000 for most merchants)
merchant_idrequiredYour merchant ID
merchant_tx_idrequiredUnique transaction ID from your system
ipn_urlrequiredWebhook URL for IPN callbacks
customer_mobile_hashrequiredSHA-256 hash of the customer mobile number
beneficiary_namerequiredBeneficiary account holder name
beneficiary_account_numberrequiredBeneficiary bank account number
beneficiary_ifsc_coderequiredBeneficiary IFSC code
remarkoptionalOptional merchant remark
timestamprequiredUnix timestamp (seconds)

Validation Rules

  • For all merchants except ID 1, amount must be between 100 and 75000.
  • 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://authentication.php.dev/request_payout.php" \
  -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/payout_request.php.

Pay-out Status

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

POST /request_payout_status.php

Request Fields

FieldRequiredDescription
keyrequiredMerchant public API key
merchant_idrequiredYour merchant ID
hashrequiredSHA-512 signature — see Overview tab
merchant_tx_idrequiredYour original transaction ID

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

FieldDescription
idInternal pay-out record ID
statusTransaction status code
merchant_tx_idYour original transaction ID
customerhashCustomer identifier hash stored for this request
amountAmount requested for pay-out
request_dtRequest creation datetime
fee_amountFee charged
beneficiary_nameBeneficiary account holder name
beneficiary_account_numberBeneficiary bank account number
beneficiary_ifsc_codeBeneficiary IFSC code
processed_dtProcessing datetime (if processed)
utrBank UTR/reference number (if available)

Error: Not Found

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

cURL Example

curl -X POST "https://authentication.php.dev/request_payout_status.php" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "merchant_id=2" \
  -d "hash=GENERATED_HASH" \
  -d "merchant_tx_id=TX202604150001"

PHP example script: example/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 request.

Request Headers (sent by server)

HeaderValue
Content-Typeapplication/json
x-signatureEthereum-signed hash for payload verification

Request Body Sent to Your Endpoint

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

Required Response from Your Endpoint

Your endpoint must return HTTP 200 with:

{
  "success": true
}
If success is not true, the delivery attempt is recorded as failed and may be retried.

Verifying the Signature

The x-signature header is an Ethereum signature produced by the payment server's private key. Verify it against the request_hash to confirm the payload is authentic.

Error Reference

HTTP CodeMessageApplies to
401Key not providedAll endpoints
404Invalid API KeyAll endpoints
401Hash not providedAll endpoints
401Invalid HashAll endpoints
401Unauthorized IP addressAll endpoints
400Missing merchant_tx_idrequest_payin_status.php, request_payout_status.php
404Payin request not foundrequest_payin_status.php
404Payout request not foundrequest_payout_status.php
404Merchant not foundrequest_payin.php, request_payout.php
503Under maintenanceAll endpoints

cURL Quick-Reference

Test Authentication

curl -X POST "https://authentication.php.dev/test.php" \
  -d "key=YOUR_PUBLIC_KEY"

Request Balance

curl -X POST "https://authentication.php.dev/request_balance.php" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "merchant_id=2" \
  -d "hash=GENERATED_HASH"

Maintenance Status

curl -X POST "https://authentication.php.dev/request_status.php" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "merchant_id=2" \
  -d "hash=GENERATED_HASH"

Pay-in Status

curl -X POST "https://authentication.php.dev/request_payin_status.php" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "merchant_id=2" \
  -d "hash=GENERATED_HASH" \
  -d "merchant_tx_id=TX202604150001"

Create Pay-out

curl -X POST "https://authentication.php.dev/request_payout.php" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "hash=GENERATED_HASH" \
  -d "amount=500" \
  -d "merchant_id=2" \
  -d "merchant_tx_id=TX202604150001" \
  -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)"

Pay-out Status

curl -X POST "https://authentication.php.dev/request_payout_status.php" \
  -d "key=YOUR_PUBLIC_KEY" \
  -d "merchant_id=2" \
  -d "hash=GENERATED_HASH" \
  -d "merchant_tx_id=TX202604150001"

PHP Example Scripts

  • example/generate_hash.php - shared hash helper
  • example/balance.php - check account balance
  • example/payin_request.php - create pay-in request
  • example/payin_status.php - check pay-in status
  • example/payout_request.php - create pay-out request
  • example/payout_status.php - check pay-out status
  • example/status.php - check maintenance status