Introduction

Welcome to the ptop.me Payment Gateway API. Use these endpoints to create payments, verify signatures, check transaction status, and send payouts to users.

Use the Sandbox environment while integrating. Switch to Live after approval.

Endpoints

Live

Base URL: https://ptop.me/api/payment
Payment Check: https://ptop.me/api/payment-check

Sandbox

Base URL: https://ptop.me/api/test/payment
Payment Check: https://ptop.me/api/test/payment-check

Register / Onboarding

To start, you must be onboarded as a merchant. Provide:

success_url, fail_url
Whitelisted IP
website_url (for referrer check)

After approval, you will receive your website_id, secret_key, and signature.

Create Payment

HTTP Method: POST

Required Parameters

Parameter	Type	Description
website_id	string	Your website identifier.
secret_key	string	Your secret key for authentication.
amount	numeric	Payment amount (min 1 USD).
product	string	Product name.
order_id	string	Unique order identifier.
currency	string	Currency, value: `USD`.
success_url	url	Redirect URL for successful payment.
fail_url	url	Redirect URL for failed/canceled payment.

cURL Example

curl --location --request POST 'https://ptop.me/api/test/payment?website_id=YOUR_ID&secret_key=YOUR_SECRET&amount=60.00&product=Sample&order_id=66510effg2eec&currency=USD&success_url=https://example.com/success&fail_url=https://example.com/fail'

Success Response

{
  "status": "success",
  "Code": 200,
  "payment_url": "https://ptop.me/api/test/payment/23456789"
}

Error Response

{
  "error": "Invalid secret key",
  "http_code": 401
}

PHP Example

 'required',
  'secret_key' => 'required',
  'amount' => '60.00',
  'currency' => 'USD',
  'product' => 'Sample Product',
  'order_id' => '66510effg2eec',
  'success_url' => 'https://example.com/success',
  'fail_url' => 'https://example.com/fail',
];
$queryString = http_build_query($requestData);
$url = $baseUrl . '?' . $queryString;

$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => $url,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => ["Content-Type: application/json","Accept: application/json"],
]);

$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$err = curl_errno($curl);
if ($err) {
  echo 'cURL error: ' . curl_error($curl);
} else {
  if ($httpcode == 200) {
    $responseArray = json_decode($response, true);
    print_r($responseArray);
  } else {
    echo 'Failed. HTTP Code: ' . $httpcode . ' Response: ' . $response;
  }
}
curl_close($curl);?>

Payment Responses

Payment Success

{
  "success": true,
  "transaction_id": 3456789,
  "order_id": 4567890,
  "message": "Payment done",
  "signature": "51e2c053098bb376d049a860e317f36b00d04070be8"
}

Payment Canceled

{
  "success": false,
  "transaction_id": 3456789,
  "order_id": 4567890,
  "message": "Payment cancelled by user / auto canceled",
  "signature": "51e2c053098bb376d049a860e317f36b00d04070be8"
}

Signature Verification (HMAC-SHA256)

Prepare JSON data for the response (e.g., transaction_id, order_id, message).
Use your secret_key.
Generate the signature using HMAC with SHA-256.

 true,
  'transaction_id' => 12345,
  'order_id' => 'ORD-0001',
  'message' => 'Payment done'
];
$secretKey = 'your_secret_key_here';
$signature = hash_hmac('sha256', json_encode($jsonData), $secretKey);
?>

Compare the received signature with your locally generated one to verify authenticity.

Payment Status Check

POST to /payment-check with:

website_id
secret_key
transaction_id (from Create Payment response)

{
  "website_id": "your-website-id",
  "secret_key": "your-secret-key",
  "transaction_id": "67990c6385454"
}

Status Code	Description
0	In Review — The user has not taken any action yet.
1	Paid — The payment was completed successfully.
2	Canceled — The payment was canceled by the user or system.

Merchant Payout API

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

Required Fields

Field	Type	Description
website_id	string	Your merchant website ID.
secret_key	string	Your merchant secret key.
reviverEmail	string (email)	Recipient email (registered user).
amount	number	Amount to transfer (min 0.01).
signature	string	HMAC-SHA256 hash using your `the_signature`.
sendingTrx	string	Unique 6-character idempotency key.

HMAC Signature Guide

Concatenate: website_id|secret_key|reviverEmail|amount
Hash with HMAC-SHA256 using your assigned the_signature

Example Request

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

Successful Response

{
  "status": "success",
  "message": "Payment sent successfully."
}

Error Response

{
  "status": "error",
  "message": "Duplicate request detected."
  // or "Signature mismatch. Untrusted origin."
}

Errors & Response Codes

200 — OK
400 — Bad Request (missing parameter or invalid format)
401 — Unauthorized (check secret_key)
500 — Internal Server Error

Contact Support

Need help or API integration services? Email: api_support@ptop.me