Use Cases & API Examples

RekberPay is designed to be highly flexible, supporting various business models out of the box. Below are common use cases and a complete end-to-end example of how to implement the API in a typical Node.js backend.

Common Use Cases

1. Peer-to-Peer Marketplaces (C2C)

In a marketplace where users buy and sell physical goods (e.g., electronics, fashion), trust is the biggest barrier.

• Flow: Buyer clicks "Checkout". Your platform generates an escrow link with category: "goods".
• SLA: 14 days after the seller marks the item as sent.
• Value: Buyers feel safe paying upfront. Sellers are guaranteed payment once the item is delivered.

2. Freelance & Service Platforms

For platforms connecting clients with freelancers (e.g., design, writing, development).

• Flow: Client accepts a proposal and clicks "Hire". Your platform generates an escrow link with category: "service".
• SLA: 3 days after the freelancer delivers the work.
• Value: Freelancers start working with confidence knowing the funds are securely held in escrow. Clients can review the work before releasing the funds.

3. Digital Goods & Game Assets

For platforms selling accounts, game items, or software licenses.

• Flow: Buyer clicks "Buy". Escrow link generated with category: "digital".
• SLA: 24 hours after delivery.
• Value: High-risk digital transactions become secure. The short SLA ensures sellers get paid quickly while giving buyers enough time to verify the digital asset works.

---

Full API Example (Node.js)

Below is a complete example of a Node.js Express backend integrating RekberPay. It covers creating the escrow and handling the webhook.

Prerequisites

You will need your API Secret. Never expose this on the frontend.

npm install express axios crypto

1. Creating the Escrow

This endpoint is called by your frontend when the user clicks "Checkout".

const express = require('express');
const crypto = require('crypto');
const axios = require('axios');

const app = express();
app.use(express.json());

const REKBERPAY_API_URL = 'https://api.rekberpay.com/api';
const REKBERPAY_SECRET = process.env.REKBERPAY_SECRET;

// Helper to generate the signature
function signPayload(payload, secret) {
    const keys = Object.keys(payload).sort();
    const parts = keys.map(k => `${k}=${payload[k]}`);
    const canonical = parts.join('&');
    return crypto.createHmac('sha256', secret).update(canonical).digest('hex');
}

app.post('/checkout', async (req, res) => {
    try {
        const { orderId, sellerId, item, amount, category } = req.body;

        // 1. Prepare the payload
        const payload = {
            seller: sellerId, // Seller's RekberPay UUID
            item: item,
            category: category, // 'goods', 'service', or 'digital'
            amount: amount,
            ref: `ORDER_${orderId}`, // Your internal Order ID
            expires: Math.floor(Date.now() / 1000) + (24 * 60 * 60), // Expires in 24h
            v: 1
        };

        // 2. Sign the payload
        payload.sig = signPayload(payload, REKBERPAY_SECRET);

        // 3. Call RekberPay API
        const response = await axios.post(`${REKBERPAY_API_URL}/escrows/from-link`, payload, {
            headers: {
                'Content-Type': 'application/json',
                // Always use idempotency keys to prevent duplicate escrows on network retries
                'Idempotency-Key': crypto.randomUUID() 
            }
        });

        // 4. Return the escrow URL to the frontend so the buyer can be redirected
        if (response.data.success) {
            res.json({
                success: true,
                escrow_url: response.data.data.escrow_url
            });
        } else {
            res.status(400).json({ error: 'Failed to create escrow' });
        }
    } catch (error) {
        console.error('Checkout error:', error.response?.data || error.message);
        res.status(500).json({ error: 'Internal Server Error' });
    }
});

2. Handling the Webhook

RekberPay will send a POST request to your webhook URL when the payment is completed or the escrow state changes. You must verify the signature to ensure the request is genuinely from RekberPay.

app.post('/webhooks/rekberpay', async (req, res) => {
    const signatureHeader = req.headers['x-rekberpay-signature'];
    const payloadStr = JSON.stringify(req.body);

    // 1. Verify the signature
    const expectedSignature = crypto
        .createHmac('sha256', REKBERPAY_SECRET)
        .update(payloadStr)
        .digest('hex');

    if (signatureHeader !== expectedSignature) {
        console.error('Invalid signature');
        return res.status(401).send('Unauthorized');
    }

    const event = req.body;

    // 2. Handle the event
    switch (event.event) {
        case 'payment.completed':
            console.log(`Order ${event.ref} has been paid! Amount: ${event.amount}`);
            // TODO: Update your database to mark the order as paid
            // TODO: Notify the seller to start fulfilling the order
            break;

        case 'escrow.sent':
            console.log(`Order ${event.ref} has been marked as sent by the seller.`);
            // TODO: Update order status to 'Shipped'
            break;

        case 'escrow.received':
            console.log(`Order ${event.ref} has been received by the buyer.`);
            // TODO: Update order status to 'Delivered'
            break;

        case 'escrow.released':
            console.log(`Funds for ${event.ref} have been released to the seller!`);
            // TODO: Update order status to 'Completed'
            break;

        case 'escrow.disputed':
            console.log(`Dispute opened for ${event.ref}.`);
            // TODO: Update order status to 'Disputed'
            break;

        default:
            console.log(`Unhandled event type: ${event.event}`);
    }

    // 3. Always respond with 200 OK quickly
    res.status(200).send('Webhook received');
});

app.listen(3000, () => console.log('Server running on port 3000'));

Next steps

• Explore all webhook events in the Webhooks Reference.
• Learn how to test your integration safely in Testing.