PaystackOSS/sample-express-backend

Sample backend for use with the Paystack mobile SDKs

Paystack Sample Express Backend

This is a simple Express app that you can use to run a backend for initializing transactions on Paystack. To get started, you can choose from the following options:

1. Run it on a free Render account
2. Run it on Heroku
3. Run it locally on your machine
4. Run it locally via Docker CLI

ℹ️ You also need to obtain your Paystack secret, test mode API Key, available in the Dashboard. Note that you must use your secret key, not your public key, to set up the backend. For more information on the differences between secret and public keys, as well as test and live mode, see our help centre article.

Running the app

Running on Render

1. Set up a free Render account.
2. Click the button below to deploy the example backend. You'll be prompted to enter a name for the Render service group as well as your Paystack API key.
3. Go to the next steps in this README for how to use this app

Running on Heroku

1. Set up a Heroku account.
2. Click the button below to deploy the example backend. You'll be prompted to enter a name for the Heroku application as well as your Stripe API key.
3. Go to the next steps in this README for how to use this app

Running locally on your machine

If you prefer running the backend locally, ensure you're using at least Node version 20.

Clone down this repo to your computer, and then follow the steps below:

1. Rename the file named .env.example to .env within the newly cloned repo directory and add your Paystack secret key:

PAYSTACK_SECRET_KEY={YOUR_API_KEY}

2. In your terminal, run npm install
3. Run npm start
4. The example backend should now be running at http://localhost:5001
5. Go to the next steps in this README for how to use this app

Running locally with Docker

We have a pre-built Docker image you can run locally if you're into the convenience of containers.

Install Docker Desktop if you don't already have it. Then follow the steps below:

1. In your terminal, cd into the cloned repo and run docker build -t sample-backend ..
2. Run docker run -e PAYSTACK_SECRET_KEY={YOUR_API_KEY} -p 5001:5001 sample-backend
3. The sample backend should now be running at http://localhost:5001
4. Go to the next steps in this README for how to use this app

---

Next steps

Set your webhook URL

In order to receive notifications for successful transactions, you'll need to set your webhook URL on your Paystack dashboard.

Render

1. Find the URL of your Render web service on the service's dashboard
2. Set your webhook URL on your Paystack dashboard to {YOUR_RENDER_SERVICE_URL}/webhook.

Heroku

1. Find the URL of your Heroku app on the app's Settings page (under Domains)
2. Set your webhook URL on your Paystack dashboard to {YOUR_HEROKU_APP_URL}/webhook.

Local

1. Your Paystack Webhook URL has to be an https URL, so you'll need to use a service like ngrok's http endpoints to generate an https URL and tunnel requests to your local machine. This is out of the scope of this tutorial, but the ngrok documentation shows how to do this.
2. Once you've obtained your ngrok https URL, set your webhook URL on your Paystack dashboard to {YOUR_NGROK_URL}/webhook.

Docker

1. Follow the same instructions under Local

First, set your webhook URL on your Paystack dashboard. This will ensure your server receives notifications for successful transactions.

Next, make an API call to the server passing email, amount, and any other optional parameters

⚠️ Note that this backend is intended for example purposes only. Because endpoints are not authenticated, you should not use this backend in production.