Paystack

Paystack is a Nigerian fintech company that provides online and offline payment solutions for businesses across Africa. Founded in 2015 by Shola Akinlade and Ezra Olubi, Paystack was accepted into Y Combinator in 2016 as the accelerator's first Nigerian startup. In 2020, Paystack was acquired by Stripe for over $200 million—the largest startup acquisition from Nigeria at the time.

Why Paystack?

Paystack has become the go-to payment gateway for African businesses with compelling advantages:

• Market Leader: Processes more than half of all online transactions in Nigeria
• Trusted by 60,000+ Businesses: From startups to enterprises like FedEx, UPS, MTN, and AXA Mansard
• Stripe-Backed: Benefits from Stripe's global infrastructure and continued investment
• Developer-First: Known for excellent documentation, robust APIs, and developer tools
• Comprehensive Tools: Includes fraud detection, detailed dashboards, subscription billing, and identity verification

Getting Started with Paystack

Before integrating Paystack with Sails Pay, you'll need a Paystack account:

1. Create an account: Sign up at dashboard.paystack.com
2. Verify your business: Complete the KYC process with required documents
3. Get API credentials: Access your test and live secret keys from Settings → API Keys
4. Test your integration: Use test mode keys (starting with sk_test_) during development

TIP

Paystack provides a robust test environment. Use test credentials to thoroughly test your payment flows before switching to live keys. See Test Payments for test card numbers and credentials.

Installation

Specifying the adapter

In config/pay.js create a default payment provider and set the adapter property to @sails-pay/paystack.

module.exports.pay = {
  providers: {
    default: {
      adapter: '@sails-pay/paystack'
    }
  }
}

TIP

Do well to run npm i @sails-pay/paystack if you haven't installed the adapter previously.

Configuration

You can configure the Paystack adapter for both production and local development.

Local development

In your config/local.js specify the following object:

module.exports = {
  pay: {
    providers: {
      default: {
        secretKey: 'sk_test_xxxxxxxxxxxxxxxxxxxxxx',
        publicKey: 'pk_test_xxxxxxxxxxxxxxxxxxxxxx',
        callbackUrl: 'http://localhost:1337/payment/callback'
      }
    }
  }
}

Production

For production set same properties in the default provider but in config/pay.js:

module.exports.pay = {
  providers: {
    default: {
      adapter: '@sails-pay/paystack',
      secretKey: process.env.PAYSTACK_SECRET_KEY,
      publicKey: process.env.PAYSTACK_PUBLIC_KEY,
      callbackUrl: process.env.PAYSTACK_CALLBACK_URL
    }
  }
}

TIP

Note we are using environment variables in production as you don't want to commit those credentials to source control.

Configuring values

If you're unsure how to obtain the configuration values shown above, please refer to the links and instructions provided below:

secretKey (required)

To get your Paystack secret key:

1. Log in to your Paystack Dashboard
2. Navigate to Settings → Developers → API Keys & Webhooks
3. Copy your Secret Key (starts with sk_test_ for test mode or sk_live_ for production)

WARNING

Keep your secret key secure! Never commit it to source control or expose it in client-side code.

publicKey (optional)

To get your Paystack public key:

1. Log in to your Paystack Dashboard
2. Navigate to Settings → Developers → API Keys & Webhooks
3. Copy your Public Key (starts with pk_test_ for test mode or pk_live_ for production)

TIP

The public key is safe to use in client-side code and is typically used for inline payment integrations.

callbackUrl (optional)

The callback URL is where Paystack redirects users after a payment attempt. Setting this globally in your config means you don't have to specify it for every checkout call.

callbackUrl: 'https://yourdomain.com/payment/callback'

TIP

You can override this per-transaction by passing callbackUrl directly to the checkout method.

Local development with webhooks

Paystack webhooks require a publicly accessible URL. To test webhooks during local development, you'll need to expose your local server using a tunneling service:

• localtunnel - Free, no account required
• ngrok - Free tier available

WARNING

Cloudflare Tunnel may not work reliably with Paystack webhooks. If you're experiencing webhook delivery issues with Cloudflare Tunnel, try using localtunnel or ngrok instead.

Once you have a public URL (e.g., https://myapp.loca.lt), configure your Paystack webhook in the dashboard:

1. Log in to your Paystack Dashboard
2. Navigate to Settings → API Keys & Webhooks
3. Add your webhook URL: https://myapp.loca.lt/webhooks/paystack
4. Make sure you configure the webhook in the same mode (Test/Live) as your transactions

Default environment variables

If you don't provide configuration values, the adapter will automatically look for these environment variables as fallbacks:

Config Value	Environment Variable
secretKey	PAYSTACK_SECRET_KEY
publicKey	PAYSTACK_PUBLIC_KEY
callbackUrl	PAYSTACK_CALLBACK_URL

This means you can simply set the environment variables and use a minimal configuration:

module.exports.pay = {
  providers: {
    default: {
      adapter: '@sails-pay/paystack'
    }
  }
}

Next steps

• Creating checkouts - Redirect users to complete payment

Additional resources

• Paystack API Documentation
• Transaction Initialize API
• Paystack Dashboard
• Metadata Guide