@wasel-finance/payment-node

Official Node.js SDK for Wasel Payment System.

دليل عربي مفصّل في payment-pro/docs/gateway/08-sdk-node.ar.md

Installation

npm install @wasel-finance/payment-node

Requires Node.js ≥ 18 (uses the built-in fetch).

Quick start

const Wasel = require('@wasel-finance/payment-node');

const client = new Wasel({
    apiKey: process.env.WASEL_KEY,   // mk_live_... or mk_test_...
    baseUrl: 'https://api.wasel.example.com'
});

const payment = await client.payments.create({
    amount: 5000,
    currency: 'SYP',
    reference: 'order-42',
    callback_url: 'https://my-store.example/orders/42/return'
});

console.log(payment.payment_url);   // redirect the user here

Resources

client.payments

• create(params) — create a hosted payment session.
• retrieve(paymentId) — public payment info (no auth required).
• refund(paymentId, { reason }) — refund a completed payment.
• cancel(paymentId) — cancel a pending payment.

client.paymentRequests (Push-to-Pay)

• create({ target_phone, amount }) — push a payment request to a wallet user. They approve in their Wasel app.

client.webhooks

• verifySignature(rawBody, signatureHeader, secret) — verify the x-wasel-signature HMAC-SHA256 header.
• constructEvent(rawBody, signatureHeader, secret) — verify and return the parsed event.

app.post('/webhooks/wasel', express.raw({type: 'application/json'}), (req, res) => {
    try {
        const event = client.webhooks.constructEvent(
            req.body,
            req.headers['x-wasel-signature'],
            process.env.WASEL_WEBHOOK_SECRET
        );
        // event.event === 'payment.completed' / 'payment.refunded' / ...
        res.json({ received: true });
    } catch (err) {
        res.status(400).send(err.message);
    }
});

client.cards

• create(params) — Coming soon. Throws NotImplementedError. Endpoint returns HTTP 501.

Errors

const { errors } = require('@wasel-finance/payment-node');

try {
    await client.payments.create({ amount: 0 });
} catch (err) {
    if (err instanceof errors.ValidationError) { /* fix input */ }
    if (err instanceof errors.AuthenticationError) { /* bad key */ }
    if (err instanceof errors.RateLimitError) { /* back off */ }
}

Network errors and 5xx responses are automatically retried (3 attempts, jittered backoff).

Idempotency

Pass idempotencyKey to payments.create() to safely retry the same operation:

await client.payments.create({ amount: 100, idempotencyKey: 'order-42' });

Keys are honoured for 24 hours.

License

MIT