Capitec Pay

Cash and Codes Bundle

Capitec Pay is an open banking payment method available exclusively to Capitec Bank clients in South Africa. Transactions can be initiated using either the client’s phone number or ID number that is linked to their Capitec banking app, with the phone number being the most commonly used identifier.

This method enables secure payments, as no sensitive information—such as card numbers or CVV codes—is shared during the process. Once the transaction is initiated, the client receives a prompt in the Capitec Bank app and has 5 minutes to approve or decline the payment.

Phone_number: A standard South African mobile number consists of 10 digits, starts with a zero (0) and no country code, "Example 0891234567"

Note

For Direct API Integration, the merchant is responsible for ensuring the user experience required by Capitec Bank. This includes:

• Displaying Capitec Pay as a standalone payment method, using the official Capitec Pay logo.
• Requesting a field for the user to enter their phone number.
• Implementing and displaying a payment instructions countdown timer (5 minutes).
• Providing both success and failure screens to the user.

Check the UX flow and Capitec Pay mandatory UX requirements, or for further information contact our integration specialists.

Requirements

• API authentication - All API requests must be authenticated using JWS (JSON Web Signature). The legacy integration_key is being deprecated — if you still use it, follow the Migration Guide to transition to JWS. If you don't have credentials yet, complete the Merchant Signup Form.
• Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters.

How it works

• Request payment - Call the ws/direct endpoint with the required parameters.
• Payment instructions - Display to the customer a page with the instructions to complete the payment and a countdown(5 minutes).
• Customer completes the payment - Customer has 5 minutes to complete the payment in their Capitec Bank app.
• Payment Conformation - Once the customer completes the payment, EBANX updates the payment status from pending (PE) to confirmed (CO). If the payment is not completed, the status updates to canceled (CA). You will get a payment status update notification for all these scenarios.

Key information

• Minimum amount per transaction: R1
• Maximum amount per transaction: R49 999
• Transaction expiration time: 5 minutes.
• Refund date range: Refunds can be processed within 180 days.

Instructions

Follow the steps below.

1. Select your environment

   Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

   SandboxProduction

   https://sandbox.ebanx.com/ws/direct

2. Define your parameters

   With Capitec Pay, customers receive a notification in the Capitec Bank app to complete the payment quickly and safely. To trigger this notification, call the ws/direct endpoint with the following required fields:

   Basic parameters

   Parameter	Requirement	Description
   integration_key	Required	Your EBANX integration key
   payment_type_code	Required	Set to capitec-pay
   country	Required	Set to za for South Africa

   
   

   Payment parameters

   Parameter	Requirement	Description
   merchant_payment_code	Required	A unique code you generate to identify this payment.
   currency_code	Required	Supported value: ZAR
   amount_total	Required	Total amount to be charged

   
   

   Customer data

   The phone_number field, linked to the customer’s Capitec Bank account, is mandatory to initiate the transaction. Optionally, the ID number associated with the account can also be provided in the field document.

   
   

   Parameter	Requirement	Description
   name	Required	Customer name
   email	Required	Customer email
   phone_number	Required	Customer phone number
   document	Optional	Customer ID number

   
   
   Note

   • The merchant must collect the customer's full name and email address on a separate UX screen, outside of the Capitec Pay payment method flow screen.
   • If the merchant is unable to collect an email address, they may pass a dummy email value.
   
   

   Check a request example below:

   
   
   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/direct' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "{{integration_key}}",
       "payment": {
           "name": "John Doe",
           "email": "john.doe@example.com",
           "phone_number": "5555555555",
           "document": "{{tax_id}}",
           "country": "za",
           "payment_type_code": "capitec-pay",
           "merchant_payment_code": "{{merchant_payment_code}}",
           "currency_code": "ZAR",
           "amount_total": "99.85"
       }
     }'
   

3. Displaying payment instructions

   A successful request returns a response like the example below. At this stage payment status will be PE, and you should display clear instructions on how do complete the payment.

   
   
   {
     "payment": {
       "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
       "country": "za",
       "merchant_payment_code": "{{merchant_payment_code}}",
       "order_number": null,
       "status": "PE",
       "status_date": null,
       "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
       "confirm_date": null,
       "transfer_date": null,
       "amount_br": "99.85",
       "amount_ext": "99.85",
       "amount_iof": "0.00",
       "currency_rate": "1.0000",
       "currency_ext": "ZAR",
       "due_date": "{{YYYY-MM-DD}}",
       "instalments": "1",
       "payment_type_code": "capitec-pay",
       "pre_approved": false,
       "capture_available": null,
       "customer": {
         "document": "{{tax_id}}",
         "email": "john.doe@example.com",
         "name": "John Doe",
         "birth_date": null
       }
     },
     "status": "SUCCESS"
   }
   

   On the instructions page, make sure to inform customers they must open Capitec Bank app and complete the payment within 5 minutes, calculated from the open_date in the response. On the same page, include a visible countdown timer starting from 5 minutes and counting down to zero, so the customer can clearly see how much time remains to complete the payment.

   Check the example below:

   Once customer completes the payment in Capitec Bank app, EBANX will send you a status update notification.

4. Monitor payment for status changes

   Notifications

   • EBANX will send a notification whenever a payment status changes.

   • Make sure your system is set up to receive notifications from EBANX for any changes in payment status.

   • Learn more about Payment Notificationschevron_right

   Status

   • After receiving a notification that status has changed, retrieve the payment status.

   • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will eventually change to cancelled (CA).

   • Learn more about Retrieving Payment Statuschevron_right

5. Congratulations!

   You have successfully integrated Capitec Pay.

   For more information, refer to the

   Direct API reference guidechevron_right

Capitec Pay UX flow

This demo illustrates the end-to-end payment experience with Capitec Pay. The journey begins on the merchant's checkout page, where the customer selects Capitec Pay and enters their mobile number. After submitting the request, a push notification is sent to their Capitec Bank app. The user reviews and approves the payment directly within the app, and once confirmed, both the customer and the merchant receive immediate payment confirmation.

Capitec Pay mandatory UX requirements

Warning

Mandatory requirement: These UX guidelines are a mandatory requirement by Capitec. All merchants must comply before going live. A Capitec Pay UX review and sign-off is required before go-live. Submit your UX design for review before development has started.

Warning

Branding assets and logos: Contact the EBANX Sales or Account Management team at sales.engineering@ebanx.com for the official Capitec Pay logo and any questions regarding these guidelines.

Tip

Early UX review: Share your UX design as early as possible once you prioritize Capitec Pay development, to allow sufficient time for review and feedback.

UX design resources:

• Figma: Capitec Pay One Time Payment
• Figma: Capitec Pay Recurring
• Capitec Pay Logo Guidelines

UX example: one-time payment flow

The screens below illustrate the complete one-time payment flow on mobile. Each step is labeled to show whether it is controlled by the merchant or by Capitec.

Steps 1-4: Checkout, phone entry, instruction page, push notification

Steps 5-8: Capitec app approval, transaction confirmation, return to merchant

Flow summary

Step	Controlled by	Description
1	Merchant	Display Capitec Pay as a standalone payment method on the checkout page.
2	Merchant	Ask the user to enter the cellphone number linked to their Capitec Bank account.
3	Merchant	Display a payment instruction page with a countdown timer and steps to approve payment in the Capitec app.
4	Capitec	A push notification is sent to the user's phone number to approve the payment.
5	Capitec	The user is directed to the Capitec Banking App to approve the transaction.
6	Capitec	The user authorizes the transaction on the banking app.
7	Capitec	The transaction is confirmed on the banking app.
8	Merchant	The customer is returned to the merchant platform with a final confirmation screen.

1. Checkout display and branding

Warning

These are Capitec Pay non-negotiable requirements.

• Standalone payment button - Present Capitec Pay as a clear, standalone payment method on your checkout page, distinct from traditional card options. Do not group it under a generic "Other Payment Methods" dropdown.
• Official branding - Use the official Capitec Pay logo (provided by EBANX) and adhere to all brand guidelines to build customer trust and ensure brand consistency. Add Capitec Pay text next to the logo.
• Logo sizing - Maintain the logo at the recommended size. Do not stretch, distort, or alter the Capitec Pay logo in any way.

Logo guidelines and checkout examples

Note

It is important to display the "Capitec Pay" text next to the Capitec Pay logo. Refer to the checkout display examples above and choose the option that best suits your implementation needs.

2. Customer identification and input

Warning

This is a Capitec Pay non-negotiable requirement. No other fields should be displayed on the Capitec Pay option besides phone number and/or ID number (when applicable).

• Primary identifier - Use the customer's cellphone number to initiate a Capitec Pay transaction. ID number is also supported as an option, but the key identifier is the phone number.
• Clear instructional text - Display the following message clearly at the phone number input field to prevent user error: "Enter the cellphone number linked to your Capitec account."
• Phone number validation - Implement front-end validation to ensure the cellphone number is in the correct format before submission.

Checkout display examples

Label horizontal

Label vertical

Phone number format rules

When an invalid phone number format is entered, display an inline validation error to the user before submitting the request to EBANX.

Rule	Details
Prefix	Must start with 0 (local format only)
Length	Must be exactly 10 digits
International format	Not accepted — +27 or 27 prefix will be rejected
Valid example	0821234567
Invalid examples	+27821234567, 27821234567, 12345, 08212345678

ID number validation

Note

ID number is passed as document in the API request.

Where ID number is used, or where a merchant passes the ID (document), the merchant should perform the validation as follows.

National ID number

A 13-digit numeric string based on the customer's date of birth, formatted as: YYMMDD SSSS C A Z

Segment	Positions	Description
YYMMDD	0-5	Customer's date of birth
SSSS	6-9	Sequence number (also encodes gender: 0000-4999 = female, 5000-9999 = male)
C	10	Citizenship: 0 = SA citizen, 1 = permanent resident
A	11	Must be 8 or 9 (legacy field)
Z	12	Check digit (Luhn algorithm)

Validation rules:

• Must be exactly 13 digits, numeric only.
• The date portion (YYMMDD) must be a valid calendar date.
• Position 10 must be 0 or 1.
• Position 11 must be 8 or 9.
• The final digit must satisfy the Luhn checksum across all 13 digits.

3. Instruction screen

Warning

This is a Capitec Pay non-negotiable requirement.

After the user initiates a payment, redirect them to an instruction page that follows the specific design and content guidelines provided by Capitec. The instruction page must:

• Display the Capitec Pay logo prominently.
• Display text clearly informing the user that they have 5 minutes to approve the payment.
• Include a 5-minute countdown timer so the user knows how much time remains to complete the approval.
• Clearly instruct the user to approve the payment in the Capitec Banking App.
• Show only payment instructions — do not clutter this page with other content.

Note

Display a message informing the user of the remaining time, for example: "You have 4 min 59 sec to approve the payment in your Capitec app" or "Approve payment within 4 min 59 sec." The time shown should function as a live countdown timer from 5 minutes down to zero.

4. Post-payment messaging

Dynamically handle the final user experience based on the payment status received from EBANX. Display a clear success, failure, or timeout message using the specific description returned in the API response.

Error handling

Handle error messages through the UX flow after receiving responses from EBANX. The following error scenarios must be handled:

Error type	When it occurs	Required merchant action
Incorrect customer data	The phone number or ID number entered is not associated with a Capitec Bank account. EBANX returns "Incorrect Customer Data" in the response.	Display a message prompting the user to verify their details and try again.
Timeout	The user does not approve the transaction within 5 minutes. EBANX returns "Expired by User Inaction" in the response.	Display a message informing the user that the transaction timed out and that they can try again.
Payment unsuccessful	The payment fails for any reason other than incorrect customer data or timeout. EBANX returns any other error in the response.	Display a "Payment Failed" message or similar notification to clearly indicate that the payment was not successful.

Error message screen examples

Below are reference mockups for the three error scenarios:

Incorrect Customer Data

Timeout

Payment Unsuccessful

5. Capitec Pay Recurring UX differences

From the merchant side, the UX flow for recurring payments is the same as one-time payments — there are no changes to the merchant checkout or instruction screens. The key differences are on the Capitec Banking App, where the user sees recurring-specific details during approval. The only merchant-side change is that the success message should clearly reflect the recurring use case (e.g., subscription confirmation rather than a single payment receipt).

Capitec App approval screen (recurring)

The Capitec Banking App displays payment frequency, first payment date, and per-payment fee. The user approves both the payment and the recurring consent in a single step.

Merchant confirmation screen (recurring)

After a successful recurring enrollment, the merchant displays a subscription-oriented confirmation message (e.g., "Payment received" with ongoing service access).

Note

All other UX requirements (checkout display, phone number input, instruction screen, error handling) apply equally to recurring payments. There are no changes required on the merchant checkout or instruction pages for recurring.

6. Implementation checklist

Use this checklist to verify your implementation before submitting for Capitec review:

• Capitec Pay is displayed as a standalone payment method (not grouped under "Other").
• Official Capitec Pay logo is used at the recommended size with Capitec Pay text next to the logo.
• Phone number input field includes the instructional text: "Enter the cellphone number linked to your Capitec account."
• Phone number validation is implemented (starts with 0, exactly 10 digits, no international prefix).
• ID (document) number validation is implemented (where applicable).
• Inline error is shown for invalid phone number format.
• Instruction page follows Capitec design guidelines (logo, countdown timer, clear instructions).
• 5-minute countdown timer is displayed on the instruction page.
• Post-payment screens are handled dynamically based on EBANX API response status.
• Error messages are displayed for: Incorrect Customer Data, Timeout, and Payment Unsuccessful.
• UX flows are consistent across desktop and mobile.

Appendix: common merchant implementation issues

The following examples illustrate common UX issues observed during merchant reviews, along with recommended improvements.

A. Phone number input

Issue	Recommendation
Pre-populated phone number	Do not pre-populate the phone number field. The number registered on your platform may not be the same number linked to the user's Capitec Bank account. This is a common cause of "incorrect customer data" errors.
Unclear instructional text (e.g., "Confirm your Phone Number")	Use clear text such as: "Enter the number linked to your Capitec Account, then approve the payment request in the Capitec App."
International phone format (+27 or 27 prefix)	Ensure the phone number format is local only (starting with 0, 10 digits total). Do not use international format.
No phone number validation	Implement front-end validation per the format rules in section 2 before submitting to EBANX.

B. Instruction page

Issue	Recommendation
No countdown timer	Include a 5-minute countdown timer to show the user how much time is left to approve the payment. This helps reduce timeout scenarios.
Cluttered instruction page	Keep the instruction screen focused purely on payment instructions. Too much information may confuse users. Use the instruction screen exactly as shared by Capitec, including the logo and message.
No dynamic error handling	Handle UX screens dynamically based on responses from EBANX. Display appropriate messages for success, failure, and timeout — do not leave the user on a static screen.
Missing error messages for failed or timed-out payments	Ensure your implementation displays specific error messages for all three error types: Incorrect Customer Data, Timeout, and Payment Unsuccessful.

C. Capitec Pay visibility and consistency

• Consistent availability - Capitec Pay must be consistently displayed as a payment method across all user flows, including promotional flows (e.g., "Spin the Wheel" campaigns). Inconsistent availability creates user confusion and reduces trust in the payment method.
• All purchase flows - Ensure Capitec Pay appears in all relevant purchase flows. If users see Capitec Pay in some flows but not others, they may lack confidence in it and abandon the payment.

D. Poor performance due to not adhering to UX guidelines

Failure to adhere to Capitec Pay UX guidelines may result in poor performance, where users become confused by the UX flow and abandon the transaction, leading to a high number of timeout-related performance errors.

E. Delayed go-live due to incorrect UX standards

Merchants delaying go-live dates due to incorrect UX implementations that are not aligned with Capitec Pay mandatory requirements. This is why merchants should share their UX designs as early as possible, to ensure reviews and alignment are completed well in advance.

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.