Ptop Payment Gateway API

1. Executive Summary (API v3)

Ptop API v3 provides enterprise-grade payment processing capabilities including transaction creation, webhook-based confirmation, HMAC signature verification, transaction status queries, and secure merchant wallet payouts. This version introduces strict separation between server-to-server notifications and customer redirection to ensure reliability and integrity.

2. API Base URLs

3. Transaction Creation

Example Request

{
 "website_id": "your-id",
 "secret_key": "your-secret",
 "amount": 100.00,
 "currency": "USD",
 "product": "Premium Plan",
 "order_id": "ORD-1001",
 "webhook_url": "https://merchant.com/webhook",
 "success_url": "https://merchant.com/success",
 "fail_url": "https://merchant.com/fail"
}

Example Response

{
 "success": true,
 "transaction_id": "a93kd82hda",
 "payment_url": "https://ptop.me/api/v3/payment/a93kd82hda"
}

Response Code Matrix

4. Webhook Delivery Specification

Ptop sends server-to-server POST requests to webhook_url upon transaction update. Your server must return HTTP 200 OK within 10 seconds.

Retry Policy

If no 200 OK is received, Ptop retries delivery up to 3 times with exponential backoff.

Success Payload

{
 "success": true,
 "transaction_id": "a93kd82hda",
 "order_id": "ORD-1001",
 "message": "Payment done",
 "signature": "HMAC_SIGNATURE"
}

5. Signature Verification (HMAC-SHA256)

You MUST hash the RAW request body exactly as received using your the_signature key.

$rawBody = file_get_contents('php://input');
$calculatedSignature = hash_hmac('sha256', $rawBody, $the_signature);

if (!hash_equals($calculatedSignature, $_POST['signature'])) {
 http_response_code(403);
 exit('Invalid signature');
}

6. Payment Status Check

POST https://ptop.me/api/v3/payment-check

Request

{
 "website_id": "your-id",
 "secret_key": "your-secret",
 "transaction_id": "a93kd82hda"
}

Response

{
 "status": 1,
 "amount": 100.00
}

7. Merchant Payout API

POST https://ptop.me/api/api-payout

Data Concatenation (Exact String to Hash)

website_id|secret_key|reviverEmail|amount

Signature Generation

$signature = hash_hmac('sha256', $data, $the_signature);

Example Request

{
 "website_id": "w123456",
 "secret_key": "secxyz890",
 "reviverEmail": "client@email.com",
 "amount": 50.00,
 "signature": "generated_signature",
 "sendingTrx": "A1X9T3"
}

8. Security & Compliance

• HTTPS is mandatory for all endpoints.
• IP whitelisting is recommended.
• All webhooks are signed using HMAC-SHA256.
• Idempotency enforced via sendingTrx.
• Secret keys must never be exposed client-side.

9. Enterprise Support

api_support@ptop.me