Capitec Pay Integration Process
No integration changes are required to include Capitec Pay, unless:
- Capitec deems your business high-risk, and you require a Verified Flow implementation;
- Your business is a TPPP (third-party payment provider) and facilitates payments to sub-merchants; and/or
- You wish to provide Capitec Pay as a standalone payment option.
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.
Only the payer's South African Identity Number can be used as a verified identifier. If a value is provided, it will only be validated when paying with Capitec Pay.
The identityNumber must be a valid South African ID number. Passport numbers are not supported.
If an invalid ID number is provided, the Capitec Pay payment initiation request will fail with a message indicating that a valid South African ID number is required.
Within the payment request mutation, initiating the verified flow on Capitec Pay is as follows:
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 support@stitch.money 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 identifier you provide.
This is because the payer would be unable to proceed at all if the identifier is 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 scenario | Error Code | Error Message |
|---|---|---|
| Invalid identity number provided | BAD_USER_INPUT | Expected identity number to be a valid South African identity number. |
| No identifier provided | VERIFICATION_REQUIRED | A 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:
| Scenario | Beneficiary Reference |
|---|---|
| MFA successful and payment completed | success |
| MFA request pending completion | success-pending |
| MFA request timed out | success-timeout |
| MFA request declined by user | success-declined |
| Payment initiation failure at Capitec | success-failed |
| Payment marked as fraudulent by user | success-fraud |