South Africa Account Charge

📘

Before you start

We recommend reading the introductory section to understand how direct charge works first.

Add introduction content.

Requirements

This payment method is only available to South African F4B accounts. To start collecting payments using this method:

1. Ensure that your account is approved for live transactions. Read more about getting your account approved here.
2. Request this feature on your account from your dashboard or via email to our support team.
3. Retrieve your test mode API keys to test your integration.
4. Confirm your webhook setup to ensure you get webhook and callbacks after completing your tests.

❗️

Refunds are not supported for transactions using this payment method.

Understanding the payment process

When your customer initiates the payment, several things happen behind the scenes:

1. First, you (the merchant) collect the customer information on your app or website.
2. The transaction is initiated using the customer's details and other information, such as the amount, currency, transaction reference, etc.
3. Flutterwave sends the customer and transaction information to our Capitec for processing.
4. Capitec performs several checks on the transaction and then notifies the customer to approve the transaction.
5. The customer gets the notification, logs into their bank app and authorizes the transaction.
6. Capitec sends the transaction status and information back to Flutterwave.
7. Flutterwave notifies the merchant via the webhooks and callback about the transaction's final processing status.

Flutterwave abstracts this entire process into three steps: transaction initiation, authorization and verification.

Transaction Initiation

Initiate the payment using the customer's information and transaction details. Send your request to the initiate-charge endpoint to create the charge.

See the full list of request requirements to initiate the charge here.

curl --location 'https://api.flutterwave.com/v3/charges/?type=capitec' \
--header 'Authorization: YOUR_SECRET_KEY-X' \
--header 'Content-Type: application/json' \
--data-raw '{
	"tx_ref": "cfdsfvgvedxwsc",
	"amount": "11",
	"currency": "ZAR",
	"email": "[email protected]",
	"phone_number": "0824514947",
	"account_number": "0001234567"
}'

Authorization

After initiating the charge, the customer is notified on their mobile phones about the transactions. To prevent a timeout, customers should authorize the payment within 2 minutes of receiving the notification.

Transaction Verification

The last step is to verify the transaction to complete the integration process. You can query the transaction status by querying the status endpoint or by using the transaction webhook:

{
  "event": "charge.completed",
  "data": {
    "id": 1688303596,
    "tx_ref": "Rave-Pages214544211401",
    "flw_ref": "ACH7260317345049430",
    "device_fingerprint": "5efee755549538b7c89afbf6d8c7f592",
    "amount": 11,
    "currency": "ZAR",
    "charged_amount": 10.25,
    "app_fee": 0.25,
    "merchant_fee": 0,
    "processor_response": "Transaction Successful",
    "auth_model": "CAPITEC",
    "ip": "209.206.31.100",
    "narration": "Test Account",
    "status": "successful",
    "payment_type": "capitec",
    "created_at": "2024-12-18T06:55:42.000Z",
    "account_id": 18428,
    "customer": {
      "id": 1089379175,
      "name": "John Doe",
      "phone_number": "08*000000047",
      "email": "[email protected]",
      "created_at": "2024-12-18T06:53:20.000Z"
    }
  },
  "meta_data": {
    "__CheckoutInitAddress": "https://flutterwave.com/pay/1m0zohaldlcj",
    "fxconversionrate": "18.29013196",
    "converted_currency": "USD",
    "converted_amount": "0.56"
  }
}

If the transaction fails, check the processor_response field for more information on the error.

{
  "event": "charge.completed",
  "data": {
    "id": 8311495,
    "tx_ref": "new_declined",
    "flw_ref": "MOCK_REF_1736248316446",
    "device_fingerprint": "N/A",
    "amount": 11,
    "currency": "ZAR",
    "charged_amount": 100,
    "app_fee": 2.5,
    "merchant_fee": 0,
    "processor_response": "Your payment has been declined. It looks like the consent request was not approved. Please check your app for more details.",
    "auth_model": "CAPITEC",
    "ip": "54.75.161.64",
    "narration": "Dotuns Fashion Limited",
    "status": "failed",
    "payment_type": "capitec",
    "created_at": "2025-01-07T11:11:56.000Z",
    "account_id": 92319,
    "customer": {
      "id": 2568908,
      "name": "Anonymous customer",
      "phone_number": null,
      "email": "[email protected]",
      "created_at": "2025-01-07T11:11:56.000Z"
    }
  },
  "meta_data": {},
  "event.type": "CAPITEC_TRANSACTION"
}

Possible values for transaction status are:

In your webhook handler implementation, you can then verify the payment and credit your customers with whatever they paid for. See our guide to transaction verification for details.

Testing your integration

Use the following details to mock different scenarios in your integration tests.

To test successful transactions, pass any value for account_number (excluding the set values for the error scenarios) in your request.