Skip to main content

Capitec Pay Integration Process

No integration changes are required to include Capitec Pay, unless:

Implementing the Verified Flow

Should Capitec require that you implement the "Verified flow", you will need to include the payer's verified identifier when creating a payment request.

The following fields can be used as a verified identifier:

  1. The payer's South African Identity Number
  2. The payer's Capitec account number

If a value is provided, it will only be validated if the payer bank is restricted to Capitec. Each identifier is validated as follows:

  • identityNumber must be a valid South African identity number. Passport numbers are not supported.
  • accountNumber must be a string containing only digits.

Within the payment request mutation, this looks as follows:


If both identityNumber and accountNumber are populated, then only identityNumber will be used.

Unverified users

If the user selects Capitec from the list of banks while attempting to make their payment, and the identifier passed in the above mutations is either invalid, missing, or is not associated with a Capitec bank account they will be presented with a message indicating that they need to verify their details before being redirected back to your site with reason=verification_required.

Merchant specification for TPPPs

For clients that will operate as a Third-Party Payment Provider (TPPP), it is required to specify a merchant reference when initiating Capitec Pay payments. This reference should uniquely identify the sub-merchant that the payment is being initiated for, and should be the same reference specified as part of the merchant's Capitec onboarding.

This reference should be provided in the merchantDetails.capitecPayMerchantReference field. An example of a payment initiation request including this is shown below:


If your client does not have the permission to provide a capitecPayMerchantReference, an error saying Client does not have the required permissions to set a custom Capitec Pay merchant reference. will be presented, please reach out to to resolve this.

Handling non-nominated merchants

When your client is enabled for Capitec Pay, this method will be enabled in all payment requests by default. If your sub-merchant has not been onboarded with Capitec, payment requests for this merchant will need to have the option explicitly disabled, by setting the paymentMethods.eft.capitecPay.enabled field to false.

An example of a request that would have Capitec Pay disabled is shown below:

Restricting Payer Bank to Capitec

It is possible to display Capitec Pay as a separate payment method in your app by including the restrictPayerBank field in mutations on the Stitch API.

If restrictPayerBank is set to "capitec" the payer will only be able to link/make payments with Capitec Pay. An example request is shown below:

Error Handling (with verified flow)

If you are using the verified flow and you restrict the payer bank to "capitec", the API will validate the identifiers you provide. This is because the payer would be unable to proceed at all if the identifiers are missing or invalid, as they would not be able to select another bank.

Should this validation fail, an error will be returned. Possible error scenarios and associated response codes/messages are:

Error scenarioError CodeError Message
Invalid identity number providedBAD_USER_INPUTExpected identity number to be a valid South African identity number.
Invalid account number providedBAD_USER_INPUTExpected account number to be a non-empty string containing only digits.
No identifier providedVERIFICATION_REQUIREDA verified South African identity number or Capitec account number is required in order to authorize an account using Capitec Pay on the verified ID flow.

Testing Capitec Pay Scenarios

Our sandbox environment allows simulation of specific Capitec Pay scenarios that users may experience in production, including how a user could handle MFA (multi-factor authentication) in their Capitec app. To simulate these cases, the beneficiaryReference of your payment request can be tweaked as follows:

ScenarioBeneficiary Reference
MFA successful and payment completedsuccess
MFA request pending completionsuccess-pending
MFA request timed outsuccess-timeout
MFA request declined by usersuccess-declined
Payment initiation failure at Capitecsuccess-failed
Payment marked as fraudulent by usersuccess-fraud