Paystack in South Africa: Complete Developer Guide

South Africa is fundamentally different from every other Paystack market. The country has a mature banking system with widespread card issuance, strong internet infrastructure, and a population that is comfortable with online card payments. Mobile money exists but does not dominate the way it does in Kenya or Ghana.

Key characteristics that affect your integration:

• Cards are the primary online payment method. Most South African consumers have Visa or Mastercard debit cards issued by major banks like Standard Bank, FNB, ABSA, Nedbank, and Capitec. Card payments with 3D Secure authentication are the norm.
• EFT (Electronic Funds Transfer) is widely used. EFT is the standard for bank-to-bank transfers in South Africa. Many consumers and businesses prefer EFT for larger transactions.
• The South African Rand (ZAR) is the currency. All domestic transactions happen in ZAR. Amounts in the API are in cents. One rand equals 100 cents.
• POPIA compliance is mandatory. The Protection of Personal Information Act governs how you handle customer data. Your payment integration must comply with POPIA's requirements for collecting, storing, and processing personal information.
• The South African Reserve Bank (SARB) and the Payments Association of South Africa (PASA) regulate payment systems. This regulatory framework is more formalized than in some other African markets.

Paystack entered South Africa to serve the card-heavy market and has been building out its channel offering. If your product targets South African consumers, card payments should be your primary focus.

Setting up Paystack for a South African business requires more documentation than some other markets due to the regulatory environment.

Step 1: Create your account

Sign up at paystack.com and select South Africa. Test mode is available immediately.

Step 2: Complete business verification

South African verification requires CIPC (Companies and Intellectual Property Commission) registration documents, SARS tax clearance certificate, director identification (South African ID or passport), proof of bank account, and proof of address for the business.

Step 3: Initialize a ZAR transaction

var response = await fetch('https://api.paystack.co/transaction/initialize', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'customer@example.co.za',
    amount: 99900, // 999 ZAR in cents
    currency: 'ZAR',
    reference: 'za_order_' + Date.now(),
    callback_url: 'https://yoursite.co.za/payment/callback',
  }),
});

var data = await response.json();
// Redirect to data.data.authorization_url

Always pass currency: 'ZAR' explicitly. The amount of 99900 represents 999 ZAR.

For detailed onboarding requirements, see Paystack onboarding and compliance in South Africa.

South Africa's payment channel mix reflects its mature banking system.

Cards (Visa, Mastercard)

Card payments are the primary channel. South African cards use 3D Secure (3DS) authentication, which means the customer enters their card details and then completes a verification step with their bank (typically an OTP or banking app approval). This adds security but also adds a step to the checkout flow.

Bank Transfer (EFT)

EFT allows customers to pay by transferring from their bank account. This is common for higher-value transactions and B2B payments. The customer initiates the transfer from their banking app or internet banking portal.

// Initialize a card-only transaction for South Africa
var response = await fetch('https://api.paystack.co/transaction/initialize', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'customer@example.co.za',
    amount: 250000, // 2,500 ZAR
    currency: 'ZAR',
    channels: ['card'],
    reference: 'za_' + Date.now(),
  }),
});

For a detailed breakdown of each channel with conversion data, see payment methods available on Paystack in South Africa.

The South African Rand uses cents as the smallest unit. One rand equals 100 cents.

function zarToCents(zar) {
  return Math.round(zar * 100);
}

function centsToZar(cents) {
  return cents / 100;
}

// Examples
zarToCents(999);     // 99900 cents = 999 ZAR
zarToCents(49.99);   // 4999 cents = 49.99 ZAR
zarToCents(25000);   // 2500000 cents = 25,000 ZAR

South African customers expect prices formatted with the "R" symbol: R 999.00, R 49.99. Display amounts in this format on your checkout page and receipts.

The verification pattern is the same as other markets:

var verifyData = await verifyTransaction(reference);

if (verifyData.data.status === 'success') {
  var expectedCents = 99900;
  if (verifyData.data.amount !== expectedCents || verifyData.data.currency !== 'ZAR') {
    console.error('Amount or currency mismatch');
    return;
  }
  // Verified. Grant value.
}

Because cards are the dominant channel in South Africa, your engineering focus should be on optimizing the card payment experience.

3D Secure (3DS) considerations:

• 3DS is mandatory for most South African card transactions. The customer will be redirected to their bank's verification page after entering card details.
• Different banks have different 3DS flows. Some use OTP via SMS, others use banking app push notifications, and some use a combination. You cannot control which method the bank uses.
• 3DS adds friction to the checkout. To minimize drop-off, set expectations in your UI. Tell the customer they will need to verify with their bank after entering card details.

Handling card payment failures:

// Common card failure reasons in South Africa
function handleCardFailure(gatewayResponse) {
  var message = gatewayResponse.toLowerCase();

  if (message.indexOf('insufficient') !== -1) {
    return 'Your card has insufficient funds. Please try a different card or payment method.';
  }
  if (message.indexOf('declined') !== -1) {
    return 'Your card was declined by your bank. Please contact your bank or try a different card.';
  }
  if (message.indexOf('expired') !== -1) {
    return 'Your card has expired. Please use a valid card.';
  }
  if (message.indexOf('3ds') !== -1 || message.indexOf('authentication') !== -1) {
    return 'Bank verification was not completed. Please try again and complete the verification step.';
  }
  return 'Payment could not be processed. Please try again or use a different payment method.';
}

Recurring payments: Card authorization reuse works in South Africa. After a successful payment, you can store the authorization for future charges (subscriptions, installments). This avoids the customer having to re-enter card details and go through 3DS again.

South Africa's Protection of Personal Information Act (POPIA) affects how you handle customer payment data. While Paystack handles PCI DSS compliance for card data, your application is responsible for how you collect, store, and process customer information.

Key POPIA requirements for payment integrations:

• Purpose limitation. Only collect personal information that is necessary for processing the payment. Do not collect extra data "just in case."
• Consent. Ensure customers consent to their data being processed for payment purposes. Your terms of service and privacy policy should cover this.
• Data minimization. Store only what you need. If you are storing transaction records, keep the minimum necessary data. You do not need to store full card numbers (Paystack handles tokenization).
• Security. Implement appropriate security measures for any personal data you store. This includes encryption at rest, access controls, and audit logging.
• Data subject rights. Customers can request access to, correction of, or deletion of their personal information. Your system should support these requests.

Paystack is PCI DSS compliant and handles card data securely. Your responsibility under POPIA relates to the customer data you collect and store in your own systems: email addresses, phone numbers, transaction histories, and any metadata you attach to transactions.

Settlement in South Africa follows Paystack's standard model with market-specific timelines.

• Settlement is to your registered South African bank account. Ensure your bank details are verified during onboarding.
• Card transaction settlements follow a schedule specific to your account tier. Check your dashboard for exact timelines.
• Fees are deducted before settlement. The net amount after Paystack's processing fee is what lands in your bank account.
• Refunds reduce your settlement. If you process refunds, the refund amounts are deducted from your next settlement batch.

For detailed settlement information, see settlement and payouts on Paystack in South Africa.

Developers coming from Nigeria or Ghana to the South African market make these mistakes frequently:

• Assuming mobile money dominates. South Africa is a card market. Do not design your checkout around mobile money as the primary channel. Cards should be front and center.
• Ignoring 3DS drop-off. The 3D Secure verification step causes some customers to abandon the checkout. Prepare your UI to handle this: show clear instructions, offer retry options, and track 3DS failure rates in your analytics.
• Not handling VAT correctly. South Africa has a 15% VAT. While this is a business concern rather than an API concern, your pricing display and invoicing should account for VAT if applicable to your product.
• Overlooking POPIA. Data protection is taken seriously in South Africa. Ensure your data handling practices comply with POPIA before launching.
• Using Nigerian settlement assumptions. Settlement timelines in South Africa are different. Plan your cash flow based on your actual settlement schedule, not what you experienced in other markets.

For checkout design tailored to South African customers, see building a local checkout experience for South Africa.

Paystack in South Africa gives you access to the continent's most developed payment infrastructure. Cards, 3DS, EFT, and strong regulatory frameworks mean your integration needs to be thorough.

If you want to build payment systems that work across African markets, including South Africa's card-dominant environment, the McTaba bootcamp covers multi-market payment engineering.

Create a free McTaba account