Best practices

Handle payments asynchronously

Don’t treat a payout as complete when you send it. Check its status a few seconds later, and double the wait before each further check so you don’t hit rate limits.

async function waitForResult(reference) {
  let delay = 3000; // start with 3 seconds
  for (let attempt = 0; attempt < 6; attempt++) {
    await sleep(delay);
    const status = await checkStatus(reference);
    if (status.final) return status;
    delay *= 2; // double the wait each time
  }
  return { pending: true }; // keep it pending, never assume success
}

Use webhooks before status checks

Listen for Paga’s payment notifications and only check status once a notification arrives. It’s faster for your customers and avoids unnecessary status checks.

Always verify a notification: recreate its hash with your hash key and compare it with the one you received. See Authentication.

Only count confirmed successes

Treat a request as successful only when its status is confirmed. Don’t read a non-zero responseCode as a failure: it may mean pending, duplicate reference or failed, so look it up in that API’s code list before you acce or failed, so look it up in that API’s code list before you act.

Map Paga’s errors to clear messages for your users, and never show raw error text. See Error handling.

Validate customer details first

Before a bank transfer, validate the account details the customer gave you. Before a bill payment, fetch the biller’s services and validate the customer’s reference. It prevents failed and misdirected payments.

Go-live checklist