Docs

Support
Home Billing Payments Receivables RevRec Retention
Payments
Home
Billing
Payments
Receivables
RevRec
Retention
API Reference
Release Notes
Tutorials
Frontend Capabilities
Partner SPI
API Changelog
API Reference
Release Notes
Tutorials
Frontend Capabilities
Partner SPI
API Changelog

Paystack 

This feature is a Private Beta Release. Contact Chargebee support  to enable Paystack for your Test and Live site.

Introduction 

Paystack is a leading online payment processing platform that enables businesses to accept payments seamlessly. With an easy-to-integrate API and support for multiple currencies, Paystack helps businesses grow by providing secure, efficient, and user-friendly payment solutions. It is particularly popular in Africa, offering a localized payment experience that caters to the unique needs of the region.

Integration Options 

You can integrate Paystack with Chargebee using the following:

Integration Method Description PCI Requirements
Chargebee Hosted Pages In this method, customers' card information is collected by Chargebee's checkout and directly passed on to Paystack. Low (Your PCI compliance is significantly reduced by using Chargebee's Checkout)
Chargebee JS In this method, you can use Chargebee Components and Hosted Fields to collect the customer's card details. Low
Chargebee JS Via Raw Card details
You will collect raw card details via your custom checkout and pass them to Chargebee.js. 		High
Chargebee API In this method, you will collect card information and pass it on to Chargebee. Chargebee then routes this card information to Paystack. Since you will be collecting card information directly, you will have to take care of PCI Compliance requirements. High
Chargebee API using Tokens Using Permanent Token, a token that represents a customer's card details stored in the Paystack vault to process payments. When using a direct gateway token, PCI requirements are minimal to None.

Choosing Paystack 

Consider the following factors before choosing Paystack as a payment solution:

  • Countries Supported: Paystack is currently available for companies based in Nigeria, South Africa, Ghana, Kenya, and Cote d'Ivoire. As they are gradually expanding across Africa, you can check here  whether Paystack is available in your country.
  • Currencies Supported: Paystack currently supports five currencies: the Nigerian Naira (NGN), the Ghanaian Cedi (GHS), the South African Rand (ZAR), the Kenyan Shilling (KES), and the United States Dollar (USD).
  • Pricing: Click here  to learn more about Paystack's pricing information.
Note

The United States Dollar (USD) is accepted only in Kenya and Nigeria.

Supported Payment Methods 

Chargebee currently supports only Card payments made via Paystack.

With Paystack, you can receive payments from customers anywhere in the world using a Mastercard, Visa, or Verve card. For Nigeria, Kenya, and South Africa-based businesses, Paystack also supports international payments through American Express cards.

Learn  how to enable international payments for your business using Paystack.

Cards Supported Countries
Mastercard Global (Accepted worldwide)
Visa Global (Accepted worldwide)
Verve Global (Accepted worldwide)
American Express Nigeria, Kenya, and South Africa
(for international payments)

Limitations 

The following limitations apply to the Paystack gateway integration with Chargebee:

  • Paystack does not support statement descriptors. The transaction descriptions displayed on customer statements are not determined by Chargebee.
  • 3D Secure authentication is mandatory for all card payments. Transactions cannot be processed without completing the 3D Secure verification step. As a result, merchants will not be able to add cards via the UI, since this flow does not trigger the required 3DS authentication.
  • Automatic Account Updater functionality is not supported by Paystack and is not available in this integration.
  • Updating saved card details via API is not supported by Paystack and is not available in this integration.
  • Chargeback management is not supported in this integration. Merchants will need to handle chargeback disputes on their own.
Note
  • Paystack recommends a minimum charge amount for the first transaction. Check the minimum limits for each currency here .
  • Refunds may fail if the amount is below the minimum transaction limit. Before initiating the request, ensure the refund meets Paystack's minimum amount requirement.
  • When processing multiple partial refunds consecutively, each refund request can only be retried after 30 minutes. Multiple refund attempts on the same card for a single transaction are not guaranteed to succeed. This is a limitation at the gateway end and not at Chargebee.

Multi-Currency Support on Paystack 

  • Single Account: A single Paystack account cannot support multiple currencies simultaneously, except for businesses in Nigeria and Kenya, where USD can be configured alongside the base currency.
  • Multiple Accounts: Merchants who need to process payments in multiple currencies (ZAR, NGN, KES, USD, GHS) must create separate business accounts for each currency and configure them as separate gateway accounts in Chargebee. This is due to compliance and regulatory requirements, as each account is configured to handle a specific currency.

Retrieve Key Information from your Paystack Account 

Chargebee requires your Paystack Secret Key for connecting with the gateway, and for subsequent API interaction with Paystack.

Follow the steps below to fetch the information that you will be required to enter in your Chargebee site:

  1. Login to your Paystack Account .

  2. Go to Settings from the left navigation menu and select the API Keys & Webhooks tab.

  3. Scroll down to the API Configuration - Test Mode section. Copy the Test Secret Key and save it for later use.

  4. Scroll to the API Configuration - Live Mode section. Copy the Live Secret Key and save it for use in the configuration in Chargebee.

Configuring PayStack in your Chargebee site 

Follow the steps below to configure Paystack in your Chargebee site:

  1. Login to your Chargebee site .

  2. Go to Settings > Configure Chargebee > Payment Gateways.

  3. Click Add Gateway and select Paystack.

  4. Enter the Secret Key as copied from your Paystack account in Step 3 of the previous section.

  5. Click Connect.

Note

When connecting your Paystack gateway account, use a clear naming convention to easily identify each account. Since Paystack requires a separate gateway account for each currency, we recommend naming them based on the country and currency.

Configuring Card Settings 

Follow the steps below to configure card settings for your Paystack account in Chargebee:

  1. The Cards payment method is enabled by default. On the Configure Paystack page, click Manage to enable other settings.

  2. Enable the following:

    • Card Verification: Chargebee verifies the customer's card before adding them. In this process, a small amount will be debited from the customer's card and will be refunded instantly. In case this authorization fails, the customer cannot add their card.
    • Always retain card information in Paystack when customer updates it: Enabling this option stores the updated card information in Paystack rather than the default gateway.
    • Enable 3D Secure: 3D Secure is mandatory for Paystack and cannot be turned off.

  3. Click Save.

Note

Since 3D Secure (3DS) is mandatory for Paystack, adding a payment method using raw card details via API may fail. This is especially relevant for Merchant-Initiated Transactions (MITs), which might require prior authentication via 3DS before being used for subsequent payments.

Additional Configuration (Required) 

Follow these additional steps to complete the configuration of the Paystack gateway in Chargebee:

  1. Go to Settings > Configure Chargebee > Currencies. Review your Currency settings and add the required currency.

  2. Review your Smart Routing settings to update gateway preferences to payment methods.

  3. Configure mandatory Email Field. Follow these steps:
    a. Go to Settings > Configure Chargebee > Checkout & Self-Serve Portal.
    b. Select the Fields tab and enable Email under Account Information. Email must be set as a mandatory field for creating customers and charges at Paystack.

Note

This integration supports the use of the Payment Initiator API parameter, which, when passed along with the transaction, helps Chargebee distinguish between Customer-Initiated and Merchant-Initiated transactions and handle the payment more effectively.

Was this article helpful?
Loading…