Before you accept real customer payments via Pesapal, it is important to test your payment integration in the Pesapal Sandbox environment. To test payments in the Pesapal Sandbox, you need Test Cards.
The sandbox enables developers and merchants to practice the card payment process without having to charge a real credit or debit card. It's useful if you want someone to confirm the customer will be able to navigate to your Pesapal checkout page, make a payment, return to your website, and it will update the status of the order.
This tutorial details the test card to use, how to complete a test transaction, and what to check before moving your integration to live mode on Pesapal.
For testing a Visa card payment in the Pesapal Sandbox, use the following information:
Pesapal’s published sandbox guidance lists `4111111111111111` as the test Visa card number, `962` as the CVV, and any future date as the expiry date.
Always verify placeholders on the current Pesapal Sandbox Payment Form. A card's information may change in the Sandbox, and the information on the actual checkout page may override older documentation.
Don't just assume that because it is a commonly used test card number, it will be valid. It is also the number that is typically used for testing with Stripe, and older discussions of Stripe with Pesapal indicate it might raise a failure to authorize in the Pesapal environment.
The Pesapal Sandbox is a testing environment where you can test payments without transferring real money.
It enables you to test:
Pesapal suggests testing the integrations in the sandbox before switching to the live API. The current API is API 3.0, REST/JSON-based; API 2.0 is deprecated.
Firstly, get sandbox credentials from the Pesapal developer platform.
You will need:
Do not use your production consumer key and secret in the sandbox for testing purposes. Pesapal offers unique test credentials for connection to the demo environment.
Securely store credentials in environment variables or other protected configuration system. Avoid leaking the consumer secret in the public repository, browser source code or in the front-end JS.
Pass your Sandbox consumer key and consumer secret to the Pesapal `RequestToken` endpoint.
From there, the access token generated by Pesapal is used as a bearer token for any protected API endpoints. Pesapal has separate token-generation endpoints for sandbox and production.
Verify your application can:
Prior to ordering, register an Instant Payment Notification URL.
An IPN (Internet Payment Notification) URL is a place on your website or application where Pesapal will post when the status of a transaction is updated. Pesapal's API 3.0 includes a dedicated endpoint for registering IPNs.
The endpoint of your IPN should be accessible to the public. Normally, a URL that is set to 'localhost' or 'private dev network' cannot receive Pesapal notifications.
If developing locally, use a secure tunnelling service or deploy test endpoint to an accessible staging server.
Order the products in your application and submit them using the Pesapal `SubmitOrderRequest` endpoint.
The request normally contains information such as:
On acceptance by Pesapal, it will return an order tracking ID and a redirect URL. The customer should now be directed to that URL to select a payment method and complete the transaction.
Save the merchant reference and Pesapal order tracking ID in your database before redirecting the customer.
A sandbox transaction involves no actual money or card being involved.
The callback URL is the page to which the customer will be redirected after completing or abandoning the payment process on Pesapal.
A redirect means that a user is coming back to your site. It is not conclusive evidence that Pesapal successfully completed the payment.
When a customer closes their browser before returning, refreshes the callback page, or opens the page multiple times, the callback page is served again. If a customer closes their browser window before going back, refreshes the callback page, or opens it twice, a second copy of the callback page is served. Your payment logic must continue to work safely in all these situations.
IPN is an acronym that stands for Instant Payment Notification.
Pesapal sends an IPN request when the transaction status changes. This is particularly relevant for transactions that are initially pending and for customers who leave the checkout page without returning to your site.
Your IPN handler should:
Not all IPN notifications are successful payments!
For security reasons, the final payment status is not included directly in the callback / IPN request provided by Pesapal. The order tracking ID must be specified in your application to be able to call the `GetTransactionStatus` endpoint.
Your integration should correctly handle the following statuses:
1. COMPLETED
The payment went through!
Prior to marking your internal order as "paid", confirm your order has been paid for by checking that:
The result sheets from Texas Instruments and Casio match.
The quantity is the same as the quantity ordered
The currency matches
The transaction hasn't been made before
The amount paid is for the expected customer/orders
2. PENDING
The Result of the transaction is still unknown, as Pesapal is still working on it.
Don't cancel or delete the order but keep it pending or awaiting payment. Do not deliver a product or issue a ticket/confirm a booking until payment is complete.
Your application might try again to update later or wait for another IPN notification.
3. FAILED
The payment could not be processed.
Do not pay the order, and if it is appropriate, give the customer the chance to try again.
Pesapal's integration guide lists the following transaction states as ones that merchants must deal with: `PENDING`, `COMPLETED` and `FAILED`.
Pesapal Payment Scenarios You Should Test
A successful integration should have more than one successful card transaction.
COMPLETED - Process a Visa payment with the test card and see that the order transitions from pending to paid only in response to a verified `COMPLETED` response.
FAILED - Open Pesapal's payment page and close it without paying. Verify that the order is not paid in your system.
The customer comes back without paying for the item. Go back to the callback page if the transaction was not completed. Your system should check the status: pending or unsuccessful, not confirm payment.
Duplicate callback requests - Refresh the callback page a few times. There should be no duplicate orders, repeated confirmations, or duplicate payments.
Repeated IPN notifications - Repeat the action with the same IPN. Your handler should be idempotent: if you're called twice with the same notification, it must still end up in the same state as it was after the first.
Delayed payment confirmation - Test an ordered item without waiting for it to be added to the order. Verify that the IPN handler can update the order after the customer has already left your site.
Invalid card information - Enter an incorrect expiry date, card number or test information. Ensure your customer is given a clear error and that you still have an unpaid internal order.
Unavailable IPN endpoint - Temporarily return an error from your IPN endpoint and validate that your application does not incorrectly update your order and logs the failure.
The amount and reference don't match - Practice with an internal validation by returning an invalid status back with an unexpected amount, currency, or merchant reference? You should be alerted to the transaction for review rather than it being processed automatically.
Pesapal’s publicly available documentation does not provide an equivalent extensive catalogue of scenario-specific card numbers.
No need to create Pesapal decline, fraud or 3D Secure test cards.
If it is application level testing, then the developer can expect responses like `PENDING`, `COMPLETED`, and `FAILED`. The mocked tests should be used in addition to real end-to-end tests in the Pesapal Sandbox, however.
Using live credentials with sandbox endpoints
Live credentials are configured to point to sandbox endpoints.
Sandbox and production credentials are separate. Make sure the API credentials and environment match.
Using the wrong test card
Use the checkout info on the Pesapal Sandbox form. The details of the Visa test that are published are:
When an order is placed via the callback, it is marked as paid.
Always query `GetTransactionStatus`. Call back is not payment.
Expects the IPN to include the payment status
You are notified about a change in the IPN. Your server is then required to request the actual status from Pesapal.
Using a private IPN URL
Your IPN endpoint needs to be accessible to Pesapal via the internet. Private network and localhost URLs are not accessible for public use.
Payments cannot be processed twice.
Callbacks and IPN notifications may be resent. To make the processing idempotent, use the merchant reference or order tracking ID.
Failing to save the tracking ID
Save order tracking ID from Pesapal once the order is successfully requested. It is necessary to check the status and to handle the transaction later.
Pesapal Sandbox Testing Checklist
Before going live, be sure to check that:
After you have tested all of the payment flows, replace the sandbox credentials and API endpoints with production Pesapal credentials and endpoints.
A production-ready integration must be able to successfully log in to Pesapal, place orders, redirect the customer to the correct page, handle the callback, and successfully return a payment confirmation back to the client using the transaction-status endpoint, as well as receive the IPN notifications and check all payments via the transaction-status endpoint.
For testing the payment flow, use the Pesapal Sandbox Visa card number of `4111111111111111`, CVV number of `962,` and any future expiry date. First and foremost, don't confirm an order through the redirect only. Ask Pesapal to check the latest status, confirm the transaction details are correct, and ensure that all callbacks and IPN operations are safe to run more than once.
