PureitPay API Documentation
Integrate seamless multi-channel payment checkout into your web or mobile applications. Explore endpoints, authentication, webhooks, and request examples.
Overview & Base Architecture
The PureitPay API allows merchants to programmatically generate payment URLs, query invoice statuses, handle instant callbacks, and receive real-time signed webhook events.
Key API Principles
REST & JSON
All API requests accept JSON payloads and return structured JSON responses.
API Key Auth
Authenticate requests using `API-KEY` header or standard `Bearer` authorization token.
Signed Webhooks
Webhooks include HMAC-SHA256 signature headers for tamper-proof server verification.
Authentication
Authenticate every API request using your unique Merchant API Key. Obtain your API Key from the Merchant Dashboard under Settings -> API Credentials.
Header Format
/api/checkout-v1
Creates a payment session and returns a checkout URL where customer completes payment.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| full_name | string | Yes | Customer full name. |
| string | Yes | Customer valid email address. | |
| amount | number | Yes | Payment amount (in BDT/currency unit). |
| invoice_id | string | Optional | Merchant unique order ID (auto-generated if empty). |
| metadata | object | Yes | Key-value JSON object for custom metadata. |
| redirect_url | string | Yes | URL to redirect customer after payment completion. |
| cancel_url | string | Yes | URL to redirect customer if payment is canceled. |
| webhook_url | string | Optional | URL to receive real-time HTTP POST notifications. |
curl -X POST https://www.pureitpay.com/api/checkout-v1 \
-H "API-KEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"full_name": "John Doe",
"email": "john@example.com",
"amount": 1250.00,
"invoice_id": "INV-10023",
"metadata": { "order_id": "98765" },
"redirect_url": "https://merchant.com/callback",
"cancel_url": "https://merchant.com/cancel",
"webhook_url": "https://merchant.com/webhook"
}'
<?php
$response = Http::withHeaders([
'API-KEY' => 'your_api_key_here',
'Content-Type' => 'application/json',
])->post('https://www.pureitpay.com/api/checkout-v1', [
'full_name' => 'John Doe',
'email' => 'john@example.com',
'amount' => 1250.00,
'invoice_id' => 'INV-10023',
'metadata' => ['order_id' => '98765'],
'redirect_url' => 'https://merchant.com/callback',
'cancel_url' => 'https://merchant.com/cancel',
'webhook_url' => 'https://merchant.com/webhook',
]);
const response = await fetch('https://www.pureitpay.com/api/checkout-v1', {
method: 'POST',
headers: {
'API-KEY': 'your_api_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
full_name: 'John Doe',
email: 'john@example.com',
amount: 1250.00,
invoice_id: 'INV-10023',
metadata: { order_id: '98765' },
redirect_url: 'https://merchant.com/callback',
cancel_url: 'https://merchant.com/cancel',
webhook_url: 'https://merchant.com/webhook'
})
});
Sample Response (201 Created)
{
"status": "true",
"success": true,
"message": "Payment URL generated successfully",
"payment_url": "https://www.pureitpay.com/payment/8f3a92...",
"payment_id": "8f3a92...",
"invoice_id": "INV-10023"
}
/api/verify-payment
Called by merchant servers upon user redirection to verify payment completion and consume the single-use session verification token (`validate_session = 1`).
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| invoice_id | string | Yes | Merchant invoice ID or PureitPay payment order invoice reference. |
curl -X POST https://www.pureitpay.com/api/verify-payment \
-H "API-KEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"invoice_id": "INV-10023"
}'
<?php
$response = Http::withHeaders([
'API-KEY' => 'your_api_key_here',
'Content-Type' => 'application/json',
])->post('https://www.pureitpay.com/api/verify-payment', [
'invoice_id' => 'INV-10023',
]);
const response = await fetch('https://www.pureitpay.com/api/verify-payment', {
method: 'POST',
headers: {
'API-KEY': 'your_api_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
invoice_id: 'INV-10023'
})
});
Sample Response (200 OK)
{
"status": "completed",
"success": true,
"full_name": "John Doe",
"email": "john@example.com",
"amount": 1250.00,
"charged_amount": 1250.00,
"fee": 25.00,
"invoice_id": "INV-10023",
"payment_id": "8f3a92...",
"metadata": {
"order_id": "98765"
},
"payment_method": "bKash",
"payment_method_name": "bKash Personal",
"sender_number": "01700000000",
"transaction_id": "TRX99887766",
"date": "2026-07-26 15:00:00"
}
/api/query-payment
Queries current status and full payment breakdown of any order by invoice_id without consuming single-use session verification flags.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| invoice_id | string | Yes | Merchant invoice ID or PureitPay payment order invoice reference. |
curl -X POST https://www.pureitpay.com/api/query-payment \
-H "API-KEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"invoice_id": "INV-10023"
}'
<?php
$response = Http::withHeaders([
'API-KEY' => 'your_api_key_here',
'Content-Type' => 'application/json',
])->post('https://www.pureitpay.com/api/query-payment', [
'invoice_id' => 'INV-10023',
]);
const response = await fetch('https://www.pureitpay.com/api/query-payment', {
method: 'POST',
headers: {
'API-KEY': 'your_api_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
invoice_id: 'INV-10023'
})
});
Sample Response (200 OK)
{
"status": "pending",
"success": false,
"full_name": "John Doe",
"email": "john@example.com",
"amount": 1250.00,
"charged_amount": 1250.00,
"fee": 25.00,
"invoice_id": "INV-10023",
"payment_id": "8f3a92...",
"metadata": {
"order_id": "98765"
},
"payment_method": "Nagad",
"payment_method_name": "Nagad Personal",
"sender_number": "01800000000",
"transaction_id": "TRX11223344",
"date": "2026-07-26 15:10:00"
}
Webhooks & HMAC Signature Security
PureitPay sends HTTP POST JSON webhooks whenever payment statuses update. Webhooks include `X-PureitPay-Signature` computed using your API Secret.
Sample Webhook Event Payload
{
"event": "payment.updated",
"status": "completed",
"invoice_id": "INV-10023",
"payment_id": "8f3a92...",
"amount": 1250.00,
"charged_amount": 1250.00,
"fee": 25.00,
"currency": "BDT",
"customer": {
"full_name": "John Doe",
"email": "john@example.com",
"sender_number": "01700000000"
},
"payment_method": "bKash",
"method_type": "MobileBanking",
"transaction_id": "TRX99887766",
"metadata": {
"order_id": "98765"
},
"date": "2026-07-26 15:00:00",
"timestamp": "2026-07-26T15:00:00+06:00"
}
HMAC Signature Verification Code
// PHP Webhook Verification Example
$payload = file_get_contents('php://input');
$signatureHeader = $_SERVER['HTTP_X_PUREITPAY_SIGNATURE'] ?? '';
$computedSignature = hash_hmac('sha256', $payload, $merchantApiSecret);
if (hash_equals($computedSignature, $signatureHeader)) {
// Valid webhook from PureitPay!
}