Merchant API Reference

Authentication

All API requests must include a Bearer token in the Authorization header. The token is composed of your API key and secret, separated by a colon.

Token Format

API Key & Secret

• pk_ (Public Key) — Your API key. Identifies your merchant account. Safe to include in client-side code if needed.
• sk_ (Secret Key) — Your API secret. Used to authenticate requests. Keep this confidential and never expose it in client-side code.

Both keys are issued automatically when you activate NexusPay. You can view and regenerate them from your tenant dashboard under NexusPay > API Credentials.

Example Request

Create Payment

Creates a new payment request. Returns a payment URL that you can redirect the player to.

Request Body

Request Example

POST /api/v1/payments
Content-Type: application/json
Authorization: Bearer pk_abc123:sk_secret456

{
  "amount": 500,
  "playerUsername": "player123",
  "callbackUrl": "https://your-server.com/webhook",
  "redirectUrl": "https://your-site.com/success",
  "metadata": { "orderId": "ORD-001" }
}

Response

{
  "id": "REQ-20260418-000001",
  "payUrl": "https://agentledgerhub.com/pay/REQ-20260418-000001",
  "amount": 500,
  "status": "pending",
  "createdAt": "2026-04-18T08:00:00.000Z"
}

Redirect the player to payUrl to begin the payment flow.

Check Payment Status

Retrieve the current status and details of a payment request. Both URL formats are supported.

Response

{
  "id": "REQ-20260418-000001",
  "status": "completed",
  "amount": 500,
  "playerUsername": "player123",
  "paidAt": "2026-04-18T08:05:00.000Z",
  "transactionId": "ST-xxx"
}

Webhook Callbacks

When a payment completes, NexusPay sends an HTTP POST request to the callbackUrl you provided when creating the payment.

Webhook Payload

{
  "event": "payment.completed",
  "data": {
    "id": "REQ-20260418-000001",
    "amount": 500,
    "status": "completed",
    "playerUsername": "player123",
    "transactionId": "ST-xxx",
    "paidAt": "2026-04-18T08:05:00.000Z"
  }
}

Signature Verification

Every webhook request includes an X-NexusPay-Signature header containing an HMAC-SHA256 signature of the request body, signed with your secret key (sk_). Always verify this signature before processing the webhook.

Node.js Verification Example

const crypto = require('crypto');

function verifyWebhookSignature(req, secretKey) {
  const signature = req.headers['x-nexuspay-signature'];
  const body = JSON.stringify(req.body);

  const expected = crypto
    .createHmac('sha256', secretKey)
    .update(body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express middleware example
app.post('/webhook', express.json(), (req, res) => {
  if (!verifyWebhookSignature(req, process.env.NEXUSPAY_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, data } = req.body;

  if (event === 'payment.completed') {
    // Process the completed payment
    console.log(`Payment ${data.id} completed for ${data.amount} PHP`);
  }

  res.status(200).json({ received: true });
});

Rate Limits

To protect the platform and ensure fair usage, the API enforces the following rate limits. Requests that exceed limits receive a 429 Too Many Requests response.

Status Values

A payment request moves through these statuses during its lifecycle.