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.
The following fields can be used as a verified identifier:
- The payer's South African Identity Number
- 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:
identityNumbermust be a valid South African identity number. Passport numbers are not supported.accountNumbermust 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 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 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 scenario | Error Code | Error Message |
|---|---|---|
| Invalid identity number provided | BAD_USER_INPUT | Expected identity number to be a valid South African identity number. |
| Invalid account number provided | BAD_USER_INPUT | Expected account number to be a non-empty string containing only digits. |
| 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 |