Quickstart: Your first payment

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

Prerequisites

• A Pesepay account with a sandbox integration key and encryption key
• Node.js, Python, PHP, or Java installed locally

Caution

The official SDKs currently call the production API only — they have no sandbox base URL. To run this against the sandbox, use the raw HTTP calls in the API reference, which show the sandbox URLs, and switch to an SDK once you’re integrating for real.

1. Install the SDK

   Node.js

   npm install pesepay

   Python

   pip install pesepay

   PHP

   composer require codevirtus/pesepay

   Java

   <dependency>
     <groupId>com.pesepay</groupId>
     <artifactId>pesepay</artifactId>
     <version>1.0.0</version>
   </dependency>

2. Initialize the client

   Use your sandbox integration key and encryption key from Onboarding.

   Node.js

   pesepay.js

   const { Pesepay } = require('pesepay');
   
   const pesepay = new Pesepay('YOUR_INTEGRATION_KEY', 'YOUR_ENCRYPTION_KEY');
   pesepay.resultUrl = 'https://example.com/payments/result';
   pesepay.returnUrl = 'https://example.com/payments/return';

   Python

   pesepay_client.py

   from pesepay import Pesepay
   
   pesepay = Pesepay("YOUR_INTEGRATION_KEY", "YOUR_ENCRYPTION_KEY")
   pesepay.result_url = "https://example.com/payments/result"
   pesepay.return_url = "https://example.com/payments/return"

   PHP

   pesepay.php

   <?php
   require_once 'vendor/autoload.php';
   use Codevirtus\Payments\Pesepay;
   
   $pesepay = new Pesepay('YOUR_INTEGRATION_KEY', 'YOUR_ENCRYPTION_KEY');
   $pesepay->returnUrl = 'https://example.com/payments/return';
   $pesepay->resultUrl = 'https://example.com/payments/result';

   Java

   PesepayClient.java

   Pesepay pesepay = new Pesepay(integrationKey, encryptionKey);
   pesepay.setResultUrl("https://example.com/payments/result");
   pesepay.setReturnUrl("https://example.com/payments/return");

3. Create and initiate a transaction

   This is the redirect flow: create a transaction for an amount and currency, then initiate it to get a redirectUrl.

   Node.js

   const transaction = pesepay.createTransaction(
     10.0,
     'USD',
     'Order #1042 — running shoes'
   );
   
   pesepay
     .initiateTransaction(transaction)
     .then((response) => {
       console.log(response.redirectUrl);   // send the customer here
       console.log(response.referenceNumber); // store this for later
     })
     .catch((error) => console.error(error));

   Python

   transaction = pesepay.create_transaction(
       10.0, "USD", "Order #1042 — running shoes"
   )
   
   try:
       response = pesepay.initiate_transaction(transaction)
       print(response.redirect_url)     # send the customer here
       print(response.reference_number) # store this for later
   except Exception as err:
       print(err)

   PHP

   $transaction = $pesepay->createTransaction(
       10.0, 'USD', 'Order #1042 — running shoes'
   );
   
   $response = $pesepay->initiateTransaction($transaction);
   
   if ($response->success()) {
       $redirectUrl = $response->redirectUrl();       // send the customer here
       $referenceNumber = $response->referenceNumber(); // store this for later
   } else {
       echo $response->message();
   }

   Java

   Transaction transaction = pesepay.createTransaction(
       10.0, "USD", "Order #1042 — running shoes"
   );
   
   Response response = pesepay.initiateTransaction(transaction);
   
   if (response.isSuccess()) {
       String redirectUrl = response.getRedirectUrl();       // send the customer here
       String referenceNumber = response.getReferenceNumber(); // store this for later
   } else {
       System.out.println(response.getMessage());
   }

4. Redirect your customer

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

5. Confirm the result

   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 in step 3.

Tip

Not using an SDK, or building in another language? The Initiate Transaction reference walks through the same flow at the raw HTTP + AES-256-CBC encryption level. The encryption playground encrypts and decrypts payloads in your browser, so you can check your implementation against a known-good one before you send a single request.

What’s next

• Add the payment methods you want to support
• Handle the result callback on your server
• Move to production