Developers — PPay API Reference

Quickstart (Node.js)

📚

Detailed Documentation Available

This is a quick reference. For comprehensive, interactive product documentation and step-by-step guides, please visit the full PPay documentation.

Create your first payment in 3 lines of code. All requests use HTTPS and return JSON.

quickstart.js

const ppay = require('ppay-node')('sk_test_pk_...');

const intent = await ppay.paymentIntents.create({
  amount: 499900,  // Amount in paisas (₨4,999)
  currency: 'PKR',
  payment_methods: ['card', 'jazzcash', 'easypaisa'],
  sentinel: { enabled: true }
});

console.log(intent.client_secret); // Pass to frontend elements

Authentication

PPay uses API keys to authenticate requests. Your keys are available in the Dashboard. Keep secret keys server-side only.

Key Type	Prefix	Use For
Test Secret	`sk_test_`	Server-side API calls in Sandbox.
Test Publishable	`pk_test_`	Frontend SDK initialisation in Sandbox.
Live Keys	`sk_live_` / `pk_live_`	Currently disabled pending launch.
Webhook Secret	`whsec_`	Verify HMAC signatures on incoming events.

API Reference

POST /v1/payment_intents

Creates a PaymentIntent, the single source of truth for a payment attempt.

Parameter	Description
`amount` req	Integer. Amount in paisas. ₨4,999 = 499900.
`currency` req	String. Must be `PKR`.
`payment_methods` opt	Array of strings: card, jazzcash, easypaisa, raast. Defaults to all active methods.
`sentinel` opt	Object. `{enabled: true}` runs rule scoring.

POST /v1/sentinel/score

Score a transaction synchronously. Returns risk score and decision. Rules engine only (Phase 1).

Parameter	Description
`amount_pkr` req	Integer. Transaction amount in PKR.
`customer_email` req	String. Email (hashed before rule evaluation).
`ip_address` req	String. Customer IP for velocity/geo checks.

Webhooks

PPay sends signed HTTP POST requests to your endpoint. Verify the PPay-Signature header.

webhook_verify.js

const sig = req.headers['ppay-signature'];
const event = ppay.webhooks.constructEvent(
  req.body,
  sig,
  'whsec_test_secret'
);

if (event.type === 'payment.completed') {
  fulfillOrder(event.data.object);
}

Test Credentials

Use these credentials in sandbox mode. Any future expiry date and any CVV works.

4242 4242 4242 4242

Successful Visa payment

Success

4000 0000 0000 0002

Card declined, insufficient funds

Declined

4000 0000 0000 9995

Triggers Sentinel REVIEW decision

Review

0300-0000000

JazzCash, successful wallet payment