Developer Documentationv1.0 REST APIFree Beta

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.

API Base URL

https://your-domain.com/api/v1

Live API Key

gp_live_sk_...

Test API Key

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.

Security Rule:

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:

X-GressPay-Signature = hash_hmac('sha256', rawRequestBody, webhookSecret)

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

server.jsRead keys from env vars
// 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 CodeHTTP StatusMeaning & Recommended Action
UNAUTHORIZED401Missing or invalid API key. Verify Bearer token format.
FORBIDDEN_SCOPE403API key lacks the required permission scope (e.g. create_payment).
DUPLICATE_TXID409Transaction identifier was already settled. Prevents double-spending.
RATE_LIMITED429Exceeded 60 requests/minute. Implement exponential backoff.
METHOD_UNAVAILABLE422Merchant has not saved receiving wallet details or operator gate is closed.

09. Rails & Verification Models

bKash & Nagad

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.

Binance Pay

Merchant Open API

Official server-to-server merchant order creation and checkout redirect. Off-chain crypto settlement with zero chargebacks.

USDT TRC-20

TRON On-Chain Verification

Direct blockchain smart-contract verification on TRON network. Requires 20 block confirmations before settling to merchant ledger.

Free Beta Policy

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

Switch all API requests from gp_test_... to gp_live_....
Verify that your receiving bKash/Nagad wallet numbers and USDT TRON address are configured in Dashboard → Payment Rails.
Configure your live HTTPS webhook URL and verify HMAC SHA-256 signatures with constant-time comparison on incoming events.
Ensure your server checks /api/v1/checkout/verify-payment before releasing high-value goods.