Predictpay API Integration & Testing Guide

This guide provides everything a developer needs to integrate their MT5 system with the Predictpay Gateway and test it thoroughly before going live.

1. Authentication

All API requests must be authenticated using a Bearer Token. You can generate your API Token from the Predictpay Admin Dashboard under the "Merchants" section.

Header Format

Authorization: Bearer 1|your_api_token_here
Accept: application/json
Content-Type: application/json

2. API Endpoints

2.1 Create Order

Creates a new payment intent and returns the secure checkout URL for your user.

Endpoint: POST /api/v1/orders/create

Request Body

{
  "client_name": "John Doe",
  "mt5_id": "99887766",
  "amount_usd": 250.00,
  "merchant_ref_id": "YOUR_UNIQUE_ORDER_123"
}

Note: merchant_ref_id must be unique per order to ensure idempotency. If you send the same merchant_ref_id twice, the API will return the existing order safely rather than creating a duplicate.

Success Response (201 Created / 200 OK)

{
  "success": true,
  "order_id": "XP-000001",
  "payment_url": "http://yourdomain.com/checkout/uuid-string",
  "amount_inr": 21000.50,
  "expires_at": "2026-04-21T14:30:00+05:30"
}

2.2 Check Order Status

Allows you to poll or manually check an order's status if needed.

Endpoint: GET /api/v1/orders/{order_id}

Success Response (200 OK)

{
  "success": true,
  "order_id": "XP-000001",
  "status": "pending",
  "amount_usd": 250.00,
  "amount_inr": 21000.50,
  "mt5_id": "99887766",
  "merchant_ref_id": "YOUR_UNIQUE_ORDER_123",
  "payment_url": "http://yourdomain.com/checkout/uuid-string",
  "expires_at": "2026-04-21T14:30:00+05:30"
}

3. The Webhook (Server-to-Server)

Instead of polling, Predictpay pushes real-time updates to your system when an admin approves or rejects the UTR.

Receiving Webhooks

When an admin clicks "Approve & Credit", Predictpay will make a POST request to your configured webhook_url.

Webhook Payload

{
  "event": "order.completed",
  "order_id": "XP-000001",
  "merchant_ref_id": "YOUR_UNIQUE_ORDER_123",
  "mt5_id": "99887766",
  "client_name": "John Doe",
  "amount_usd": 250.00,
  "amount_inr": 21000.50,
  "utr_number": "312345678901",
  "status": "completed",
  "timestamp": "2026-04-21T14:45:00+05:30"
}

Validating Webhooks (Security)

To ensure the webhook is genuinely from Predictpay, we sign the payload using HMAC-SHA256 with your webhook_secret. You must compare the X-Predictpay-Signature header to a hash you generate on your server.

Example PHP Verification

$payload = file_get_contents('php://input');
$signatureHeader = $_SERVER['HTTP_X_PREDICTPAY_SIGNATURE']; // format: sha256=<hash>

$expectedHash = 'sha256=' . hash_hmac('sha256', $payload, 'your_webhook_secret');

if (hash_equals($expectedHash, $signatureHeader)) {
    // Valid! Credit the user's MT5 account
} else {
    // Invalid signature, ignore
}

4. End-to-End Testing Workflow

To safely test the system before going live, follow these exact steps:

Get an API Key: Log into the Admin panel (/admin), go to Merchants, create a Test Merchant, and click "Generate API Key".
Set Webhook URL: For local testing, use a free service like https://webhook.site and enter it in the Merchant settings.
Fire POST Request: Use Postman or cURL to hit POST /api/v1/orders/create with your token.
Checkout Simulation: Open the resulting "payment_url" in an incognito window.
Upload Dummy Data: Fill in a fake UTR (12 digits) and upload a dummy image file. Submit the form.
Admin Verification: Log into the Admin panel as super-admin. You will see the transaction marked Waiting Verification.
Approve: Open the transaction, click "Approve & Credit". View the UTR side-by-side with your test image.
Verify Webhook: Go to your webhook.site (or own server) and confirm you successfully received the signed JSON payload containing "status": "completed".