Skip to content

Quickstart: Hosted checkout

By the end of this page you’ll have redirected a test customer to the Pesepay sandbox payment page and got a transaction reference back — the core loop behind every Pesepay integration.

  • Your test keys, an integration key and an encryption key. They are on the Merchant Control Panel as soon as you register; see Get your test keys.
  • One of: Node.js 22.12 or newer, Python 3, PHP, or Java
  1. You need a version that can call the sandbox: pesepay 2.x for Node.js, 1.1.0 or newer for Python and Java, 1.0.3 or newer for PHP.

    Terminal window
    npm install pesepay@^2
  2. Use your test keys, and tell the library to call the sandbox. Without that switch, every library calls production, where test keys are rejected.

    pesepay.mjs
    import { Pesepay } from 'pesepay';
    const pesepay = new Pesepay({
    integrationKey: process.env.PESEPAY_INTEGRATION_KEY,
    encryptionKey: process.env.PESEPAY_ENCRYPTION_KEY,
    resultUrl: 'https://example.com/payments/result',
    returnUrl: 'https://example.com/payments/return',
    baseUrl: 'https://api.test.sandbox.pesepay.com/payments-engine',
    });
  3. This is Hosted checkout: create a transaction for an amount and currency, then initiate it to get a redirectUrl. The sandbox takes USD only.

    const { redirectUrl, referenceNumber } = await pesepay.initiateTransaction({
    amount: 10,
    currencyCode: 'USD',
    reasonForPayment: 'Order #1042 — running shoes',
    merchantReference: 'order-1042',
    });
    console.log(redirectUrl); // send the customer here
    console.log(referenceNumber); // store this for later

    A failed call throws a PesepayError; see the library’s README for the error classes.

  4. Send the customer’s browser to redirectUrl. In the sandbox, use the test payment methods to complete or deliberately fail the payment.

  5. Pesepay calls your resultUrl with the final status as soon as the customer finishes — see The result callback. As a fallback, you can also poll: Check Payment Status using the referenceNumber you stored when you initiated the transaction.

Swap in the live keys of your application and drop the sandbox switch: remove baseUrl in Node.js, or the third constructor argument in Python, PHP and Java. Work through the go-live checklist first.