Payment Gateway Integration

How it works

Your gateway uses HMAC-SHA256 signatures to verify every incoming payment request. The external site signs the link before sending the customer — the gateway checks the signature before allowing payment. After completion, the customer is redirected back with a signed response you can verify.

Get your secret key

Contact the gateway operator to receive your HMAC secret key — a long random string shared only between you and the gateway. Keep it server-side only. Never put it in frontend code, git, or environment files that ship to the browser.

You will also receive:

Understand the signed URL

A valid payment link looks like this:

Generate a signed link on your server

This code runs on your server when you render the checkout button. Never run it in the browser.

Node.js / Next.js

const crypto = require("crypto");

const GATEWAY_SECRET = process.env.GATEWAY_HMAC_SECRET; // from your .env
const GATEWAY_ORIGIN = "https://pay.example.com";
const PRODUCT_ID    = "42";
const REF_CODE      = "MYSHOP";

function buildSignedUrl(returnUrl) {
  const params = {
    productId:  PRODUCT_ID,
    ref:        REF_CODE,
    return_url: returnUrl,
    nonce:      crypto.randomBytes(8).toString("hex"),
    expires:    (Date.now() + 10 * 60 * 1000).toString(), // 10 minutes
  };

  // Sign: sort keys alphabetically, join as key=value&key=value, then HMAC
  const message = Object.keys(params)
    .sort()
    .map((k) => `${k}=${params[k]}`)
    .join("&");

  params.sig = crypto
    .createHmac("sha256", GATEWAY_SECRET)
    .update(message)
    .digest("hex");

  const query = new URLSearchParams(params).toString();
  return `${GATEWAY_ORIGIN}/pay/${PRODUCT_ID}?${query}`;
}

// Usage — call when rendering your checkout page:
const payUrl = buildSignedUrl("https://myshop.com/order/confirm");
// Embed payUrl in your checkout button hrefNode.js

PHP

<?php
function buildSignedUrl($returnUrl) {
    $secret    = getenv('GATEWAY_HMAC_SECRET');
    $origin    = 'https://pay.example.com';
    $productId = '42';
    $ref       = 'MYSHOP';

    $params = [
        'productId'  => $productId,
        'ref'        => $ref,
        'return_url' => $returnUrl,
        'nonce'      => bin2hex(random_bytes(8)),
        'expires'    => strval(intval(microtime(true) * 1000) + 600000),
    ];

    // Sort keys alphabetically, build key=value string, sign
    ksort($params);
    $message = implode('&', array_map(
        fn($k, $v) => "$k=$v",
        array_keys($params),
        array_values($params)
    ));
    $params['sig'] = hash_hmac('sha256', $message, $secret);

    return $origin . '/pay/' . $productId . '?' . http_build_query($params);
}

// Usage:
$payUrl = buildSignedUrl('https://myshop.com/order/confirm');
?>
<a href="<?= htmlspecialchars($payUrl) ?>">Pay with Crypto</a>PHP

Python

import hmac, hashlib, os, secrets, time
from urllib.parse import urlencode

def build_signed_url(return_url):
    secret     = os.environ["GATEWAY_HMAC_SECRET"].encode()
    origin     = "https://pay.example.com"
    product_id = "42"

    params = {
        "productId":  product_id,
        "ref":        "MYSHOP",
        "return_url": return_url,
        "nonce":      secrets.token_hex(8),
        "expires":    str(int(time.time() * 1000) + 600_000),
    }

    # Sort keys alphabetically, build message, sign
    message = "&".join(f"{k}={params[k]}" for k in sorted(params))
    params["sig"] = hmac.new(secret, message.encode(), hashlib.sha256).hexdigest()

    return f"{origin}/pay/{product_id}?{urlencode(params)}"

# Usage:
pay_url = build_signed_url("https://myshop.com/order/confirm")
Python

Handle the redirect back

After payment, the customer is redirected to your return_url with these query params appended:

Example confirmation page (Node.js)

// pages/order/confirm.js (Next.js API route or page)
export default function ConfirmPage({ query }) {
  const { status, tx, ref } = query;

  if (status === "success" && tx) {
    // 1. Verify tx on-chain (recommended)
    //    GET https://api.etherscan.io/api?module=transaction&action=gettxreceiptstatus&txhash={tx}
    //    Check status === "1" (success) and to === your contract address

    // 2. Then mark the order as paid in your database
    markOrderPaid({ ref, tx });
  }
}Node.js

Verify with Etherscan API

// Check a transaction was successful on-chain
const res = await fetch(
  `https://api.etherscan.io/api?module=transaction&action=gettxreceiptstatus` +
  `&txhash=${tx}&apikey=${YOUR_ETHERSCAN_KEY}`
);
const { result } = await res.json();

if (result.status === "1") {
  // Transaction succeeded on-chain — safe to fulfil the order
} else {
  // Transaction failed or not found — do not fulfil
}Node.js

What this protects against

Integration checklist

Signing algorithm — quick reference