This documentation explains the authentication mechanism used in auth.php, located at:

api/v1/utils/auth.php

✅ Purpose

To verify and authorize API access using merchant credentials, domain validation, and IP whitelisting.

🧪 Required HTTP Headers

Header Name	Description	Required
API-USERNAME	Your unique API username	✅
API-PASSWORD	Your API password	✅
API-APP-KEY	Application key for the integration	✅
API-SECRET-KEY	Secret key to authenticate the request	✅

🗃️ Database Tables Used

• merchant_api_credentials: Contains the API credentials and linked via merchant_id.
• merchant: Contains active_domain, whitelist_ip, and status.

🔐 Authentication Flow

1. Read and normalize headers
2. Validate API credentials
3. Validate merchant account status, domain, and IP
4. Compare normalized domains
5. Check IP against whitelist
6. Return success or 401 Unauthorized

🔍 Example Header Request (cURL)

curl -X POST https://pickbo.com/api/v1/initiate-payment.php \
  -H "API-USERNAME: merchant_user" \
  -H "API-PASSWORD: merchant_pass" \
  -H "API-APP-KEY: app_123" \
  -H "API-SECRET-KEY: secret_456" \
  -d '{ "amount": 100, "callback_url": "https://merchant.com/callback" }'

🔐 Unauthorized Responses

{
  "status": "error",
  "message": "Unauthorized IP address."
}

• Missing API credentials in headers.
• Invalid API credentials.
• Merchant is inactive.
• Merchant is banned.
• Merchant not found.
• Unauthorized domain access.
• Unauthorized IP address.

🧼 Normalization Function

function normalizeDomain($domain) {
  if (!$domain) return null;
  $domain = strtolower(trim($domain));
  $domain = preg_replace('/^www\./', '', $domain);
  $domain = preg_replace('/^https?:\/\//', '', $domain);
  $domain = rtrim($domain, '/');
  return $domain;
}

🔐 Unauthorized Helper Function

function unauthorized($message) {
  http_response_code(401);
  echo json_encode([
    "status" => "error",
    "message" => $message
  ]);
  exit;
}

🧪 Developer Notes

• Test with Postman or Insomnia.
• Ensure active_domain and whitelist_ip are properly set.
• Do not expose credentials in frontend code.

📌 Endpoint

POST https://pickbo.com/api/v1/initiate-payment.php

🔐 Authentication

Header Name	Type	Required	Description
API-USERNAME	string	✅	Your assigned API Username
API-KEY	string	✅	Your assigned API Key (secret)
Content-Type	string	✅	Must be application/json

📥 Request Body

Required Fields:

Field	Type	Description
amount	float	Total payment amount
currency	string	Currency code (e.g., BDT)
customer_name	string	Customer's name
customer_email	string	Customer's email
customer_mobile	string	Customer's mobile number
callback_url	string	Your callback URL (must be HTTPS)

📦 Example Request

{
  "amount": 250.00,
  "currency": "BDT",
  "customer_name": "Tanvir Ahmed",
  "customer_email": "tanvir@example.com",
  "customer_mobile": "01712345678",
  "callback_url": "https://yourdomain.com/checkout/callback"
}

✅ Success Response

{
  "status": "success",
  "message": "Payment initiated successfully.",
  "payment_id": "123",
  "invoice_id": "INV-1722946334128",
  "redirect_url": "https://payment.pickbo.com/checkout/INV-1722946334128"
}

❌ Error Responses

{
  "status": "error",
  "message": "API-USERNAME header missing."
}

🔁 Next Step: Callback Handling

Pickbo will redirect to your callback_url with invoice, status, and paymentID as query parameters.

📌 API Endpoint

POST https://pickbo.com/api/v1/execute-payment.php

🔐 Authentication

Send API-USERNAME and API-KEY in the headers.

📥 Request Payload

Field	Type	Description
invoice_id	string	Invoice ID from Pickbo
payment_id	string	Payment ID from gateway
status	string	One of: success, failed, cancel

💡 Sample Callback Handling (PHP)

// payment-status.php
$status     = $_GET['status'] ?? 'unknown';
$invoice    = $_GET['invoice'] ?? '';
$payment_id = $_GET['paymentID'] ?? '';

if ($status === 'success') {
  echo "✅ Payment Successful! Invoice: $invoice";
} else {
  echo "❌ Payment Failed or Cancelled. Invoice: $invoice";
}

📞 Support

• Email: support@pickbo.com
• Website: https://pickbo.com