Capitec Pay Recurring

Tokenized Alternatives Bundle

Capitec Pay Recurring enables merchants to collect recurring payments from customers with a single, upfront consent, known as enrollment. Ideal for subscription services, customers approve the first request in the Capitec app, and future payments occur automatically within agreed-upon limits.

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

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

Key Features

• Enrollment (One-Time Consent): Customers approve the recurring mandate once
• Secure Authentication: Approval is handled securely within the customer's Capitec app. The customer has five minutes to approve the mandate before the transaction times out.
• Flexible Billing: Supports fixed amounts, variable amounts within a set range, and other billing models.
• Minimum amount per transaction: R1
• Maximum amount per transaction: R49 999
• Refund date range: Refunds can be processed within 180 days.

By following this basic integration guide, you will understand how to create enrollments and accept Capitec Pay recurring payments in your checkout by using EBANX’s Direct API. To complete a payment with Capitec Pay, you will need a few API calls that will create an enrollment for your customer, the recurring payment, and provide the necessary information for the customer to complete the transaction.

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.

• Displaying 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.

• Capitec Pay should be presented as a standalone payment method on the merchant's checkout page with the correct Capitec Pay logo. It should NOT be nested under any payment method, such as bank transfer, etc.

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

How it works

Capitec Pay Recurring supports two enrollment flows, depending on whether the merchant needs to create a new enrollment or pass an existing one that was already approved through Capitec.

Standard enrollment flow

In this flow, EBANX requests Capitec to create a new enrollment. The customer receives a push notification in the Capitec Bank app and must approve the mandate within five minutes. Once approved, EBANX confirms the enrollment and the merchant can start processing recurring charges.

The standard enrollment flow covers the following enrollment options:

• Enrollment with variable amount (min and max)
• Enrollment with a fixed amount
• Enrollment with payable_now_amount

Step	Action	Endpoint	Description
1	Create Enrollment	/ws/userenrollment	Register the customer and define the subscription terms (amount, frequency)
2	Customer Approval	(Via Capitec Bank App)	The customer receives a push notification and has five minutes to approve the mandate
3	Query Enrollment Status	/ws/userenrollments/query	Poll this endpoint to confirm if the enrollment was accepted
4	Recurring Payments	/ws/direct	Merchant schedules payments based on the enrollment
5	Enrollment cancellation	/ws/userenrollment	Where applicable, merchants can cancel the enrollment

Note

• Enrollment mandates can be cancelled by the merchant using the /ws/userenrollment endpoint, or they can be cancelled by the user via the Capitec Bank App. If a cancellation is initiated by the user, EBANX will send a webhook notification update to the merchant.
• Merchants have an option to submit an enrollment and a charge simultaneously. This means combining enrollment and the first payment in a single request.
• Merchants can update an existing enrollment without requiring the end user to accept a new mandate by calling the /ws/userenrollment endpoint.

Pass existing enrollment flow (sharable tokens)

This flow supports Capitec's sharable token functionality, where a merchant creates an enrollment with one partner (partner A) and later wants to process recurring charges through EBANX. Sharable tokens allow the merchant to reuse an existing approved Capitec enrollment across different partners without requiring the customer to approve a new mandate.

In this flow, the merchant already has an approved Capitec enrollment and wants to pass it to EBANX. Because the enrollment is already active on Capitec's side, EBANX does not communicate with Capitec during the enrollment creation. Instead, EBANX creates the enrollment internally and links the provided consent_id (enrollment identifier) and consent_receipt (enrollment agreement identifier) to it, enabling the merchant to process recurring charges through EBANX.

Note

EBANX requires that an enrollment must be registered before any recurring charge can be executed. Even if the enrollment was originally created by another partner, the merchant must pass and register the enrollment with EBANX in order to process future recurring payments.

Step	Action	Endpoint	Description
1	Pass Enrollment	/ws/userenrollment	Create the enrollment in EBANX by providing the consent_id and consent_receipt from the existing Capitec enrollment
2	Recurring Payments	/ws/direct	Merchant schedules payments based on the passed enrollment
3	Enrollment cancellation (optional)	/ws/userenrollment	Where applicable, merchants can cancel the enrollment

Note

• The merchant only needs to use this flow when passing a Capitec enrollment that is already approved and in use (for example, an enrollment originally created through a different partner). This is part of Capitec's sharable token support.
• Since the enrollment is already approved on Capitec's side, no customer approval step is required and no push notification is sent to the Capitec Bank app.
• The consent_id and consent_receipt are passed as-is to Capitec when processing recurring charges. EBANX does not modify these values.
• If one of these fields (consent_id or consent_receipt) is provided, both must be informed. The merchant can omit both when using a standard enrollment flow.

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.
• Branding Assets - Capitec Pay must be displayed as a standalone payment method. Contact our Integration Specialists for the official logo and branding guidelines.

Instructions

To complete a Capitec Pay enrollment and recurring payments, 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. Subscription enrollment parameters

   To start the recurring payment process, enroll the subscription using the /ws/userenrollment endpoint. This step involves collecting essential customer details and subscription parameters to establish the recurring billing agreement. Once the process is complete, the customer will be enrolled for the recurring payment cycle.

   There are different enrolment options available:

   • Enrollment with variable amount (min and max)
   • Enrollment with a fixed amount
   • Enrollment with payable_now_amount
   • Pass existing enrollment with consent_id and consent_receipt (for merchants passing an already-approved Capitec enrollment via sharable tokens)

   The enrolment is valid until the expiry date (if one is set) or until the enrolment is revoked by the user or the merchant.

   You will need to specify the following parameters in your enrollment request:

   Basic parameters

   These apply to all enrolment options.

   Parameter	Requirement	Description
   integration_key	Required	Your integration key
   payment_type_code	Required	Must be capitec-pay-recurring
   operation	Required	Must be enrollment

   
   

   Enrollment Data

   The field phone_number, 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. Below is a list of the required parameters, which further down shows specific additional fields required depending on the enrollment option used. In the payload, only the subscription information will change depending on the enrollment option.

   Parameter	Requirement	Description
   country	Required	Must be za
   email	Required	Customer’s e-mail
   name	Required	Customer’s name
   phone_number	Required	Customer’s phone number linked to Capitec Account
   document	Optional	Customer's South African ID number
   merchant_enrollment_code	Required	Unique enrollment code
   subscription_name	Required	Descriptor of the service being provided, which will be displayed in the customer's banking app
   expiration_date	Optional	When provided, it defines when the enrollment is no longer valid, and no further payments will be charged ( YYYY-MM-DD 00:00:00)
   frequency	Required	The billing cycle of the enrollment. Available frequencies are daily; weekly; fortnightly; monthly; yearly; biennially. For on demand, merchants can use daily frequency
   start_date	Required	The scheduled date for the first transaction that starts the enrollment ( YYYY-MM-DD)

   
   
   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.
   
   

   Enrollment Option one: Variable amount (min and max)

   This option allows merchants to specify minimum and maximum amounts, which then determines the allowed range for future charges. Use this to charge variable amounts within a pre-approved range. The minimum amount can be set to 1 ZAR and the maximum amount as required. The price increases or decreases are tied to the minimum and maximum values provided in the payload request.

   
   

   In addition to the above basic and enrollment parameters, the following additional parameters will be required:

   
   

   Parameter	Requirement	Description
   min_amount	Required	Minimum amount (per payment) during the validity of the subscription plan (in ZAR currency)
   max_amount	Required	Maximum amount (per payment) during the validity of the subscription plan (in ZAR currency)

   
   

   Check a request example below:

   
   
   curl -X POST 'https://sandbox.ebanx.com/ws/userenrollment/' \
   --header 'Content-Type: application/json' \
   --data '{
       "integration_key": "your_ebanx_integration_key",
       "payment_type_code": "capitec-pay-recurring",
       "operation": "enrollment",
       "enrollment": {
           "country": "za",
           "name": "John Doe",
           "email": "john.doe@example.com",
           "phone_number": "0121234567",
           "document": "{{tax_id}}",
           "merchant_enrollment_code": "unique-enrollment-abc-123",
           "subscription": {
               "subscription_name": "Descriptor of the subscription",
               "expiration_date": "2026-12-30",
               "frequency": "monthly",
               "min_amount": "100",
               "max_amount": "500",
               "start_date": "2026-12-15"
           }
       }
   }’
   

   
   

   Check a response example below:

   
   
   {
       "status": "SUCCESS",
       "redirect_url": "no-redirect",
       "enrollment": {
           "merchant_enrollment_code": "unique-enrollment-abc-123",
           "country": "za",
           "name": "John Doe",
           "document": "{{tax_id}}",
           "email": "john.doe@example.com",
           "phone_number": "0121234567",
           "subscription": {
               "frequency": "monthly",
               "min_amount": "100",
               "max_amount": "500",
               "expiration_date": "2026-12-30",
               "subscription_name": "Descriptor of the subscription.",
               "start_date": "2026-12-15",
               "consent_id": "cd3bd512-338e-4327-b5c1-fc7face3c7b5",
               "consent_receipt": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
           },
          "open_date": "2025-10-13 17:43:53"
       }
   }
   

   Note

   The consent_id and consent_receipt fields in the enrollment response are the sharable tokens that merchants can use to process recurring charges with a different partner through the Pass existing enrollment flow (sharable tokens).

   
   

   Enrollment Option two: Fixed amount

   This option allows the merchants to specify a fixed amount during enrollment. Use this option when the recurring charge is always the same.

   In addition to the basic parameters and enrollment information, the following additional parameters will be required:

   
   

   Parameter	Requirement	Description
   fixed_amount	Required	The exact amount to be charged on each payment

   
   

   Check a request example below:

   
   
   curl -X POST 'https://sandbox.ebanx.com/ws/userenrollment/' \
   --header 'Content-Type: application/json' \
   --data '{
       "integration_key": "your_ebanx_integration_key",
       "payment_type_code": "capitec-pay-recurring",
       "operation": "enrollment",
       "enrollment": {
           "country": "za",
           "name": "John Doe",
           "email": "john.doe@example.com",
           "phone_number": "0121234567",
           "document": "{{tax_id}}",
           "merchant_enrollment_code": "unique-enrollment-abc-123",
           "subscription": {
               "subscription_name": "Descriptor of the subscription.",
               "expiration_date": "2026-12-30",
               "frequency": "monthly",
               "fixed_amount": "100",
               "start_date": "2026-12-15"
           }
       }
   }’
   

   
   

   Check a response example below:

   
   
   {
       "status": "SUCCESS",
       "redirect_url": "no-redirect",
       "enrollment": {
           "merchant_enrollment_code": "unique-enrollment-abc-123",
           "country": "za",
           "name": "John Doe",
           "document": "{{tax_id}}",
           "email": "john.doe@example.com",
           "phone_number": "0121234567",
           "subscription": {
               "frequency": "monthly",
               "fixed_amount": "100",
               "expiration_date": "2026-12-30",
               "subscription_name": "Descriptor of the subscription.",
               "start_date": "2026-12-15",
               "min_amount": "100",
               "max_amount": "100",
               "consent_id": "cd3bd512-338e-4327-b5c1-fc7face3c7b5",
               "consent_receipt": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
           },
           "open_date": "2025-10-13 17:43:53"
       }
   }
   

   Note

   The consent_id and consent_receipt fields in the enrollment response are the sharable tokens that merchants can use to process recurring charges with a different partner through the Pass existing enrollment flow (sharable tokens).

   
   

   Enrollment Option three: Enrollment with payable_now_amount

   This option should be used when a subscription has a future start_date, but the merchant needs to authorize and collect one or more payments before that official start date. A common scenario is charging an initial setup fee, a deposit, or a one-time administrative cost or any other use case where there is an amount to be paid before the subscription start date. To be more clear, this should be used when the merchant sets a future start_date but still wants to create one or more payments after the subscription is approved and before the start_date.

   
   

   Step 1 Enrolment

   Merchant sends an enrollment request with the future start_date and includes the payable_now_amount. A successful response confirms that the subscription and payable now amount authorisation has been approved. This step does not charge the customer.

   Step 2 Execute the Charge

   After receiving a successful enrollment confirmation, the merchant must make a separate call to the ws/direct endpoint to process the payment. Merchants can initiate one or multiple charges up to the total value defined in payable_now_amount.

   
   

   In addition to the basic parameters and enrollment information, the following additional parameters will be required:

   Parameter	Requirement	Description
   payable_now_amount	Required	The total amount (in ZAR) that the merchant wants to charge the customer before the subscription's start_date. This acts as a pre-payment limit. It could be due now or any time before the start date.

   
   

   Example of this scenario: The merchant wants to create an enrollment with the start_date set to 2025-12-01, but would like to create a payment before that. So, they provide the payable_now_amount, which will determine the total amount that can be charged before 2025-12-01. However, this is only an AUTHORIZATION for early charges; to actually create these charges before 2025-12-01, the merchant must use the ws/direct endpoint as defined in the common flow.

   
   

   Here is an example of an enrollment request with a future start_date and a payable_now_amount of 30 ZAR:

   
   
   curl -X POST 'https://sandbox.ebanx.com/ws/userenrollment/' \
   --header 'Content-Type: application/json' \
   --data ' {
     "integration_key": "your_ebanx_integration_key",
     "payment_type_code": "capitec-pay-recurring",
     "operation": "enrollment",
     "enrollment": {
       "country": "za",
       "name": "John Doe",
       "email": "john.doe@example.com",
       "phone_number": "0121234567",
       "document": "{{tax_id}}",
       "merchant_enrollment_code": "unique-enrollment-abc-123",
       "subscription": {
         "subscription_name": "Descriptor of the subscription.",
         "expiration_date": "2027-12-31",
         "frequency": "monthly",
         "min_amount": "50",
         "max_amount": "1000",
         "start_date": "2025-12-10"
       },
       “capitec”: {
         "payable_now_amount": "30"
       }
     }
   }
   

   
   

   Check a response example

   
   
   {
       "status": "SUCCESS",
       "redirect_url": "no-redirect",
       "enrollment": {
           "merchant_enrollment_code": "unique-enrollment-abc-123",
           "country": "za",
           "name": "John Doe",
           "document": "{{tax_id}}",
           "email": "john.doe@example.com",
           "phone_number": "0121234567",
           "subscription": {
               "frequency": "monthly",
               "fixed_amount": "100",
               "expiration_date": "2027-12-31",
               "subscription_name": "Descriptor of the subscription.",
               "start_date": "2025-12-10",
               "min_amount": "100",
               "max_amount": "5000",
               "consent_id": "cd3bd512-338e-4327-b5c1-fc7face3c7b5",
               "consent_receipt": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
           },
           "open_date": "2025-10-13 17:43:53"
       }
   }
   

   By creating the subscription with this payload, this will create an enrollment that has its start date on 2025-12-10, with an amount between 50 and 1000 ZAR. However, since the payable_now_amount was provided, Capitec allows multiple payments to be created before 2025-12-10, totaling up to the maximum value set by the payable_now_amount field. Thus, after receiving the subscription confirmation, the merchant will be able to use the ws/direct endpoint with this subscription, even before the defined start_date to create the payment, for example the merchant could create one payment of 30 ZAR, or 3 payments of 10 ZAR each, etc.

   
   
   Note

   • Separate Payment Action: Remember, including payable_now_amount only authorizes the charge. A second, explicit call to ws/direct is required to capture the payment.
   • More than one charge can be made during this period before the start_date, until the limit set by payable_now_amount is reached. And the charge does not need to be created immediately after the subscription, but it CAN be made before the start date.
   • Notifications: EBANX will notify you of the enrollment status once confirmed by Capitec. You can also query the enrollment status at any time using the ws/userenrollments/query endpoint.
   • Subscription Start: The recurring subscription charges (e.g., the monthly 50-1000 ZAR) will only begin on or after the start_date defined in the enrollment using the normal ws/direct flow.
   Note

   The consent_id and consent_receipt fields in the enrollment response are the sharable tokens that merchants can use to process recurring charges with a different partner through the Pass existing enrollment flow (sharable tokens).

   
   

   Enrollment Option four: Pass existing enrollment with consent_id and consent_receipt (sharable tokens)

   This option supports Capitec's sharable token functionality. It is used when the merchant already has an approved Capitec enrollment (e.g., created through a different partner) and wants to pass it to EBANX to process recurring charges. By sending the consent_id and consent_receipt inside the capitec object, the merchant can register the enrollment in EBANX without triggering a new enrollment request to Capitec and without requiring customer approval in the Capitec Bank app.

   Note

   • The merchant should only use this option when they have an existing Capitec enrollment that is already approved and in use. For new enrollments that require customer approval, use one of the standard enrollment options above.
   • EBANX requires that an enrollment must be registered before any recurring charge can be executed. Even if the enrollment was originally created by another partner, the merchant must pass and register it with EBANX in order to process future recurring payments.
   
   

   In addition to the basic parameters and enrollment information, the following additional parameters are required inside the capitec object:

   Parameter	Requirement	Description
   consent_id	Conditionally required	The enrollment identifier in Capitec. This value is passed as-is to Capitec when processing recurring charges.
   consent_receipt	Conditionally required	The enrollment agreement identifier. This value is passed as-is to Capitec when processing recurring charges.

   Note

   If one of these fields (consent_id or consent_receipt) is provided, both are required. The merchant should not inform consent_id without consent_receipt (and vice versa). Both fields can be omitted when using a standard enrollment flow.

   
   

   Check a request example below:

   
   
   curl -X POST 'https://sandbox.ebanx.com/ws/userenrollment/' \
   --header 'Content-Type: application/json' \
   --data '{
       "integration_key": "your_ebanx_integration_key",
       "payment_type_code": "capitec-pay-recurring",
       "operation": "enrollment",
       "enrollment": {
           "country": "za",
           "name": "John Doe",
           "email": "john.doe@example.com",
           "phone_number": "0121234567",
           "document": "{{tax_id}}",
           "merchant_enrollment_code": "unique-enrollment-abc-123",
           "subscription": {
               "subscription_name": "Descriptor of the subscription",
               "expiration_date": "2026-12-30",
               "frequency": "monthly",
               "min_amount": "100",
               "max_amount": "500",
               "start_date": "2026-12-15"
           },
           "capitec": {
               "consent_id": "value-from-existing-capitec-enrollment",
               "consent_receipt": "value-from-existing-capitec-enrollment-agreement"
           }
       }
   }'
   

   
   

   Check a response example below:

   
   
   {
       "status": "SUCCESS",
       "redirect_url": "no-redirect",
       "enrollment": {
           "merchant_enrollment_code": "unique-enrollment-abc-123",
           "country": "za",
           "name": "John Doe",
           "document": "{{tax_id}}",
           "email": "john.doe@example.com",
           "phone_number": "0121234567",
           "subscription": {
               "frequency": "monthly",
               "min_amount": "100",
               "max_amount": "500",
               "expiration_date": "2026-12-30",
               "subscription_name": "Descriptor of the subscription.",
               "start_date": "2026-12-15",
               "consent_id": "value-from-existing-capitec-enrollment",
               "consent_receipt": "value-from-existing-capitec-enrollment-agreement"
           },
           "open_date": "2025-10-13 17:43:53"
       }
   }
   

   Note

   • When using this option, no push notification is sent to the customer and no approval is required in the Capitec Bank app.
   • The enrollment is created directly in EBANX with an accepted status, allowing the merchant to immediately start processing recurring charges.
   • The consent_id and consent_receipt values are stored and included in all subsequent charge requests to Capitec.
   
   

3. Displaying payment instructions

   The merchant should display an instructions page to inform users that they must open the Capitec Bank app and complete the payment within five 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. The instructions page should be displayed as per the image below.

   
   

   Check the example below:

   
   

   Once a customer completes the approval in the Capitec Bank app, EBANX will send you a status update notification and the merchant should handle this on the UX.

   
   
   Note

   The payment instruction page is displayed only during the initial enrollment process, allowing the user to approve the mandate. Once the mandate has been approved, recurring payments are processed automatically without requiring further user approval. Therefore, merchants do not need to display the payment instruction page when executing recurring payments.

   
   

4. Enrollment Status

   During any enrollment status change, EBANX will notify the merchant via our async webhook notification, for example, operation=enrollment_status_change&notification_type=update&merchant_enrollment_code=testenrollment00104

   Additionally, EBANX allows merchants to actively retrieve user enrollment status before performing a new transaction. Using the ID provided in merchant_enrollment_code, use the ws/userenrollments/query endpoint to get the latest status of the enrollment.

   
   

   Check a request example below:

   
   
   curl -X POST 'https://sandbox.ebanx.com/ws/userenrollments/query' \
   --header 'Content-Type: application/json' \
   --data '{
       "integration_key": "your_ebanx_integration_key",
       "enrollment": {
           "merchant_enrollment_code": "unique-enrollment-abc-123"
       }
   }'
   

   A successful request will return a JSON response like the one below, with status accepted for customer-approved enrollments. Other possible enrollment statuses include not accepted, pending, expired, not_found, and revoked, depending on the actions taken by the merchant or customer.

   
   
   {
      "status": "SUCCESS",
      "payment_type": "capitec-pay-recurring",
      "enrollment": {
           "status": "accepted",
           "email": "john.doe@example.com"
       },
       "subscription": {
           "subscription_name": "Descriptor of the subscription.",
           "start_date": "2025-07-26",
           "expiration_date": "2025-12-31 00:00:00",
           "frequency": "weekly",
           "retry": null,
           "fixed_amount": "100.00",
           "consent_id": "cd3bd512-338e-4327-b5c1-fc7face3c7b5",
           "consent_receipt": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
       }
   }
   

   Note

   The subscription object in the query response will include the consent_id and consent_receipt fields when these attributes exist and are linked to the enrollment. These values are the sharable tokens associated with the enrollment and are required for processing recurring charges.

5. Process Recurring Payments

   Once an enrollment is accepted, you can charge the customer on each billing cycle using the /ws/direct endpoint.

   Note

   • If the start date of the payment is on the 29th, 30th, or 31st and the recurring month does not have 29, 30, or 31 days, the payment will occur on the last day of that month.
   • If the payment fails, the merchant should make a new API call on using the /ws/direct end point.
   • The merchant can retry the failed payment once every 60 minutes until the next occurrence
   • If the first payment date (start_date), enrollment creation date and recurring payment date are on the same day (current date), and the system fails to deduct any amount due to insufficient funds, the payment request will fail. This means that the enrollment will be considered invalid and future recurring payments will not be possible.
   
   

   Scheduling a recurring payment with Capitec Pay is really straightforward. The following fields will be required:

   
   
   

   Parameter	Requirement	Description
   integration_key	Required	Your unique and secret integration key, used to authenticate the request.
   merchant_payment_code	Required	Unique merchant payment code
   amount_total	Required	Total amount to be charged. Note that the amount must match the one set in the enrollment
   currency_code	Required	Must be ZAR
   payment_type_code	Required	Must be capitec-pay-recurring
   country	Required	Must be za
   email	Required	Customer’s email
   name	Required	Customer’s name
   phone_number	Required	Customer’s phone number linked to Capitec Bank
   document	Optional	Customers ID
   merchant_enrollment_code	Required	The enrollment code generated in the previous steps. The enrollment must have an accepted status to be used in recurring payments

   
   

   Check a request example below:

   
   
   curl -X POST 'https://sandbox.ebanx.com/ws/direct' \
   --data '{
       "integration_key": "your_ebanx_integration_key",
       "payment": {
           "name": "John Doe",
           "email": "john.doe@example.com",
           "country": "za",
           "payment_type_code": "capitec-pay-recurring",
           "merchant_payment_code": "unique-paymentid-abc-00123",
           "currency_code": "ZAR",
           "amount_total": "155",
           "phone_number": "0121234567",
           "document": "{{tax_id}}",
           "merchant_enrollment_code": "unique-enrollment-abc-123"
       }
   }'
   

   A successful request will return a JSON response like the one below. The Capitec Pay Recurring payment will have a pending (PE) status and will be confirmed later by the customer's bank.

   
   
   {
       "payment": {
           "hash": "68d594b5507d55db21b2e2de7a3337dfe45e456c21164d82",
           "country": "za",
           "merchant_payment_code": "unique-paymentid-abc-00123",
           "order_number": null,
           "status": "PE",
           "status_date": null,
           "open_date": "2025-09-25 19:15:01",
           "confirm_date": null,
           "transfer_date": null,
           "amount_br": "155.00",
           "amount_ext": "155.00",
           "amount_iof": "0.00",
           "currency_rate": "1.0000",
           "currency_ext": "ZAR",
           "due_date": "2025-09-28",
           "instalments": "1",
           "payment_type_code": "capitec-pay-recurring",
           "pre_approved": false,
           "capture_available": null,
           "customer": {
               "document": "{{tax_id}}",
               "email": "john.doe@example.com",
               "name": "John Doe",
               "birth_date": null
           },
           "enrollment": {
               "status": "pending",
               "merchant_enrollment_code": "unique-enrollment-abc-123"
           },
           "subscription": {
               "subscription_name": "Descriptor of the subscription.",
               "start_date": "2025-07-26",
               "expiration_date": "2025-12-31 00:00:00",
               "frequency": "weekly",
               "retry": null,
               "fixed_amount": "100.00"
           }
       },
       "status": "SUCCESS"
   }
   

6. Confirming the payment

   As soon as the payment is confirmed by the customer's bank, the payment status is modified from PE to CO, and a Status Update notification webhook is sent.

   {
      "operation": "payment_status_change",
      "notification_type": "update",
      "merchant_payment_code":"unique-paymentid-abc-00123"
   }
   

   Using the hash provided in the payment response, use the /ws/query endpoint to get the latest status of the payment

   
   

   Check a request example below:

   
   
   curl -X POST 'https://sandbox.ebanx.com/ws/query' \
   --header 'Content-Type: application/json' \
   --data '{
       "integration_key": "your_ebanx_integration_key",
       "hash": "unique_payment_hash-123"
   }'
   

   A successful request will return a JSON response like the one below, with a status of CO for the successful recurring payment.

   {
       "payment": {
           "hash": "68dc290b3dd5011c2a01bc9d68d55fd561d97f81e744e469",
           "country": "za",
           "merchant_payment_code": "unique-paymentid-abc-00123",
           "order_number": null,
           "status": "CO",
           "status_date": null,
           "open_date": "2025-09-30 19:01:31",
           "confirm_date": null,
           "transfer_date": null,
           "amount_br": "155.00",
           "amount_ext": "155.00",
           "amount_iof": "0.00",
           "currency_rate": "1.0000",
           "currency_ext": "ZAR",
           "due_date": "2025-10-03",
           "instalments": "1",
           "payment_type_code": "capitec-pay-recurring",
           "pre_approved": false,
           "capture_available": null,
           "customer": {
               "document": "{{tax_id}}",
               "email": "john.doe@example.com",
               "name": "John Doe",
               "birth_date": null
           },
           "subscription": {
               "subscription_name": "Descriptor of the subscription.",
               "start_date": "2026-07-01",
               "expiration_date": "2027-01-01 00:00:00",
               "frequency": "weekly",
               "retry": null,
               "fixed_amount": "155.00"
           },
           "enrollment": {
               "merchant_enrollment_code": "unique-enrollment-abc-123"
           },
           "ewallet": {
               "account_number": "100xxxxx000"
           }
       },
       "status": "SUCCESS"
   }
   

   The response includes the following additional field:

   Field	Description
   ewallet.account_number	User's Capitec Bank account number that the payment was paid from. Only returned when a charge is successful.

   
   

   Now, for each new billing cycle, simply repeat 5 and 6! Above.

7. Enrollment Cancellation

   If you need to revoke/cancel a subscription for a customer, you can simply send a request with operation: cancel, which will immediately cancel the subscription.

   
   

   Check a request example below:

   
   
   curl -X POST 'https://sandbox.ebanx.com/ws/userenrollment' \
   --header 'Content-Type: application/json' \
   --data '{
       "integration_key": "your_ebanx_integration_key",
       "operation": "cancel",
       "payment_type_code": "capitec-pay-recurring",
       "enrollment": {
           "merchant_enrollment_code": "unique-enrollment-abc-123"
       }
    }'
   

   
   

   Check a response example below:

   
   
   {
      "status": "SUCCESS",
      "enrollment": {
          "status": "revoked"
      }
   }
   

8. Updating an Existing Enrollment

   Merchants can update an existing enrollment without requiring the end user to accept a new mandate by calling the ws/userenrollment endpoint. These updates can be made in scenarios such as:

   • Price increase or decrease
   • Subscription plan upgrade
   • Subscription plan downgrade
   
   
   Note

   Capitec supports the configuration of a global maximum amount limit for recurring payments, as well as a percentage variation that can be applied once the maximum limit is reached. Merchants may reach out to the EBANX Integration Specialists for more information and guidance.

   Capitec will work on optimising the user experience on the app related to changes in the subscription amount from early 2026.

   
   
   

   Option one: Updating minimum and maximum amount (variable)

   This option is used when there is a need to adjust the minimum and maximum amount already defined in an existing enrollment. Merchants are encouraged to consider potential changes when setting up the initial enrollment to minimize future updates. The price increases or decreases are tied to the min and max values provided in the payload request.

   
   

   Check a request example below:

   
   
   curl --location 'https://sandbox.ebanx.com/ws/userenrollment' \
   --header 'Content-Type: application/json' \
   --data '{
       "integration_key": "your_ebanx_integration_key",
       "operation": "update_subscription",
       "payment_type_code": "capitec-pay-recurring",
       "enrollment": {
           "merchant_enrollment_code": "unique-enrollment-abc-123",
           "subscription": {
                   "expiration_date": "2026-01-01",
                   "min_amount": "100",
                   "max_amount": "3000"
           }
       }
    }'
   

   
   

   Check a response example below:

   
   
   {
       "status": "SUCCESS",
       "enrollment": {
           "merchant_enrollment_code": "a9b152ca-67fa-4881-a746-ee368801b55f",
           "subscription": {
               "min_amount": "100",
               "max_amount": "3000",
               "expiration_date": "2026-01-01"
           }
       }
   }
   

   
   

   Option two: Updating a fixed amount (fixed)

   This option is used when the fixed amount defined during the initial enrollment needs to be updated. If the merchant expects recurring changes in the subscription amount, it is recommended to use the variable amount option instead.

   
   

   Check a request example below:

   
   
   curl --location 'https://sandbox.ebanx.com/ws/userenrollment' \
   --header 'Content-Type: application/json' \
   --data '{
       "integration_key": "your_ebanx_integration_key",
       "operation": "update_subscription",
       "payment_type_code": "capitec-pay-recurring",
       "enrollment": {
           "merchant_enrollment_code": "unique-enrollment-abc-123",
           "subscription": {
               "expiration_date": "2026-01-01",
               "fixed_amount": "500"
           }
       }
   }'
   

   
   

   Check a response example below:

   
   
   {
       "status": "SUCCESS",
       "enrollment": {
           "merchant_enrollment_code": "a9b152ca-67fa-4881-a746-ee368801b55f",
           "subscription": {
               "min_amount": "500",
               "max_amount": "500",
               "expiration_date": "2026-01-01",
               "fixed_amount": "500"
           }
       }
   }
   

   
   

   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
   
   

   Error Codes

   Click here to see a list of common error codes

9. Congratulations!

   You have successfully integrated Capitec Pay Recurring.

   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 recurring. 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 approves the consent as a way to confirm the enrollment.

While the merchant's UX flow is the same, the user's experience varies based on their Capitec Bank App login status: logged out or logged in.

User logged out of the Capitec Bank App

User already logged in the Capitec Bank App

Capitec Pay mandatory UX requirements

Warning

Mandatory requirement: These UX guidelines are a mandatory requirement by Capitec. All merchants must comply before going live.

For the full mandatory UX requirements (checkout display, branding, phone number validation, instruction screen, error handling, and implementation checklist), refer to the Capitec Pay mandatory UX requirements section.

For recurring-specific differences (Capitec app approval screen and merchant confirmation screen), see the Recurring payment differences subsection.

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.