GressPay Integration Reference
Complete guide to integrating GressPay server-to-server checkout, authenticating via scoped API keys, handling cryptographically signed HMAC webhooks, and reconciling payments.
01. Quickstart & Prerequisites
GressPay follows standard RESTful principles. All requests require JSON content and return JSON responses. To start accepting payments, you need an active merchant account and an API Key.
https://your-domain.com/api/v1
gp_live_sk_...
gp_test_sk_...
02. Test vs Live Ledgers
GressPay enforces strict cryptographic and database separation between test and live environments. Test transactions are tagged with ledger_mode = 'test' and will never affect production balances, merchant settlements, or carrier companion queues.
Ledger mode is strictly determined by the authentication secret (gp_live_ vs gp_test_). A buyer or client cannot switch ledger modes on the hosted pay page.
03. Authentication & Required Scopes
Send your secret key in the Authorization header using the Bearer scheme, or via X-GressPay-Key:
Authorization: Bearer gp_live_sk_948192ab3c4d5e... Content-Type: application/json
04. Create Checkout Session
Initiate a payment session from your server. The response returns a payUrl. Redirect your customer to this URL to complete payment:
curl -X POST https://your-domain.com/api/v1/checkout/create \
-H "Authorization: Bearer gp_live_sk_..." \
-H "Content-Type: application/json" \
-d '{
"amount": 2500,
"currency": "BDT",
"email": "[email protected]",
"full_name": "Rahim Ahmed",
"return_url": "https://mystore.com/orders/1042/success",
"webhook_url": "https://mystore.com/api/webhooks/gresspay",
"metadata": { "orderId": "ORD-1042" }
}'05. Server-to-Server Verification
CRITICAL SAFETY RULE: Never fulfill an order or grant access simply because a customer returns to your return_url. Always verify transaction status server-to-server or rely on verified signed webhooks:
curl -X POST https://your-domain.com/api/v1/checkout/verify-payment \
-H "Authorization: Bearer gp_live_sk_..." \
-H "Content-Type: application/json" \
-d '{ "sessionId": "chs_98218a" }'06. Webhooks, Signatures & Idempotency
GressPay delivers HTTP POST webhooks for payment completion events. Each webhook contains an X-GressPay-Signature header calculated as:
Always compute the HMAC on the raw, unparsed request bytes and compare using constant-time comparison (hash_equals in PHP, crypto.timingSafeEqual in Node.js, hmac.compare_digest in Python) to prevent timing side-channel attacks.
07. Runnable Server Integration Examples
// GressPay Node.js Server-Side Integration (Node 18+ / ESM)
// Read secret keys strictly from process.env — NEVER expose in frontend bundles.
import crypto from 'node:crypto';
const API_KEY = process.env.GRESSPAY_API_KEY; // 'gp_live_sk_...'
const BASE_URL = process.env.GRESSPAY_URL || 'https://api.yourdomain.com';
const WEBHOOK_SECRET = process.env.GRESSPAY_WEBHOOK_SECRET;
// 1. Create Checkout Session
export async function createCheckout(amount, currency, orderId, email) {
const res = await fetch(`${BASE_URL}/api/v1/checkout/create`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount,
currency,
email,
return_url: `https://yoursite.com/orders/${orderId}/complete`,
webhook_url: 'https://yoursite.com/api/webhooks/gresspay',
metadata: { orderId },
}),
});
if (!res.ok) {
const err = await res.json().catch(() => ({}));
throw new Error(err.error?.message || `HTTP ${res.status}`);
}
const session = await res.json();
// Redirect buyer to session.payUrl
return session; // { sessionId: 'chs_...', payUrl: 'https://.../pay/chs_...' }
}
// 2. Webhook Handler with Constant-Time Signature Verification
export function verifyWebhook(rawBodyBuffer, signatureHeader) {
const hmac = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(rawBodyBuffer)
.digest('hex');
// Prevent timing attacks using crypto.timingSafeEqual
return crypto.timingSafeEqual(
Buffer.from(hmac, 'utf8'),
Buffer.from(signatureHeader || '', 'utf8')
);
}
// 3. Server-to-Server Payment Status Check
export async function checkPaymentStatus(sessionId) {
const res = await fetch(`${BASE_URL}/api/v1/checkout/verify-payment`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ sessionId }),
});
return res.json();
}08. Error Codes & Troubleshooting
| Error Code | HTTP Status | Meaning & Recommended Action |
|---|---|---|
| UNAUTHORIZED | 401 | Missing or invalid API key. Verify Bearer token format. |
| FORBIDDEN_SCOPE | 403 | API key lacks the required permission scope (e.g. create_payment). |
| DUPLICATE_TXID | 409 | Transaction identifier was already settled. Prevents double-spending. |
| RATE_LIMITED | 429 | Exceeded 60 requests/minute. Implement exponential backoff. |
| METHOD_UNAVAILABLE | 422 | Merchant has not saved receiving wallet details or operator gate is closed. |
09. Rails & Verification Models
SMS Companion Matching
Funds settle directly to your merchant wallet. GressPay Companion APK on your phone parses carrier receipt SMS and matches amount + TrxID within 2-3s.
Merchant Open API
Official server-to-server merchant order creation and checkout redirect. Off-chain crypto settlement with zero chargebacks.
TRON On-Chain Verification
Direct blockchain smart-contract verification on TRON network. Requires 20 block confirmations before settling to merchant ledger.
0% Platform Commission
Initial beta release has zero GressPay platform fees. You pay only standard carrier MFS cash-out or native TRON blockchain gas fees.
10. Production Go-Live Checklist
gp_test_... to gp_live_..../api/v1/checkout/verify-payment before releasing high-value goods.
