Callbacks & Verification

The callback flow

After a payment, Reeple redirects the checkout iframe to your callbackUrl with query parameters indicating the outcome (e.g. ?status=success&reference=reeple_xxx). The SDK detects this same-origin navigation, reads the query params, and fires onSuccess(data) — then closes the modal automatically.

onSuccess is a convenience for updating your UI immediately. It fires from data read out of the browser URL, which a malicious user could tamper with. Always verify the transaction server-side before marking an order as paid.

`ReepleSuccessData` shape

interface ReepleSuccessData {
  amount: number; // decimal in the currency's standard unit, e.g. 50 for ₦50
  currency: string;
  reference: string;
  status: string;
  message: string;
  statusCode?: number;
  success?: boolean;
  // ...plus any additional query params Reeple appends to your callbackUrl
}

Verifying on your server

Your server-side handler at callbackUrl should:

Read the query params

e.g. ?status=success&reference=reeple_xxx

Verify the transaction

Call the verify endpoint server-to-server, using the reference — never trust the browser params alone.

Update your order/database

Mark the order paid only after the server-side verification succeeds.

Return a response

The SDK closes the modal automatically once the callback URL is reached; your onSuccess callback handles the client-side redirect.

// Example Express.js callback handler
app.get('/payment/callback', async (req, res) => {
  const { reference } = req.query;

  const verifyRes = await fetch(
    `https://api-v3.reeple.ai/s2s/payments/verify/${reference}`,
    { headers: { 'public-key': process.env.REEPLE_PUBLIC_KEY } }
  );
  const verified = await verifyRes.json();

  if (verified.data.status === 'success') {
    await db.orders.markPaid(reference);
  }

  res.send('<html><body>Processing...</body></html>');
  // The SDK closes the modal; your onSuccess callback handles the UI redirect
});

Keep your public key server-side in an environment variable — never hardcode it or bundle it into client-side code for this call.

The verify endpoint responds with { success, statusCode, message, data: { status, reference, amount, currency } }, where data.status is one of pending, success, or failed. It returns 400 if the order isn’t found, 401 for an invalid/missing key, and 500 on an internal error.

See Verify a payment order for the full endpoint reference, including error responses.

Session timeout

If the checkout session isn’t completed within 10 minutes, onError fires and the session expires.

Get Started

Integration Guide

Framework Examples

Mobile

Help

Callbacks & Verification

The callback flow

`ReepleSuccessData` shape

Verifying on your server

Session timeout

​The callback flow

​ReepleSuccessData shape

​Verifying on your server

​Session timeout

The callback flow

`ReepleSuccessData` shape

Verifying on your server

Session timeout