Recurring payments

This guide walks you through integrating recurring payments via One API. Recurring payments follow a strict two-step process, a consent request that the customer approves once, followed by merchant-initiated collections that happen silently without any further customer action.

Before you start#

• Recurring payments must be enabled on your merchant profile by Ozow: contact your account manager to confirm this before integrating
• Your One API client must have the subscriptions scope, when creating your API client on the Ozow Dashboard, ensure this scope is included. Without it, all subscription endpoints will return an authorisation error
• You have completed standard One API authentication setup: see Redirect: One API for the token flow
• If your business operates in a high-risk industry, Customer Identity VerificationCustomer Identity Verification Checking that the payment instrument belongs to the natural person making the payment. Ozow requires it for merchants it has classified as high-risk, on Pay by Bank, Absa Pay, Capitec Pay, Nedbank Direct EFT, FNB Payment Requests and PayShap Request, and can disable those methods where it is not implemented correctly. must be built into the consent step: see Customer Identity Verification

Environments#

How it works#

---

Core integration#

Step 1: Create a subscription (consent request)#

Create a subscription to initiate the consent process. The customer must approve the consent in their Capitec app before any collections can be made.

POST https://one.ozow.com/v1/subscriptions
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Request example

{
  "siteCode": "YOUR_SITE_CODE",
  "paymentMethod": "capitec",
  "amount": {
    "currency": "ZAR",
    "value": 500.00
  },
  "amountConstraints": {
    "min": { "currency": "ZAR", "value": 500 },
    "max": { "currency": "ZAR", "value": 600 }
  },
  "description": "Meal kit",
  "merchantReference": "SUB-001",
  "bankReference": "MEALKIT",
  "frequency": "Monthly",
  "firstPaymentDate": "2026-09-01",
  "occurrences": 12
}

Key request fields

For the full request schema see One API reference.

Successful response

{
  "subscriptionId": "00000000-0000-0000-0000-000000000000",
  "status": "PendingAuthorization",
  "redirectUrl": "https://pay.ozow.com/subscriptions/00000000-0000-0000-0000-000000000000",
  "links": {
    "self": "https://one.ozow.com/v1/subscriptions/00000000-0000-0000-0000-000000000000",
    "cancel": "https://one.ozow.com/v1/subscriptions/00000000-0000-0000-0000-000000000000",
    "transactions": "https://one.ozow.com/v1/subscriptions/00000000-0000-0000-0000-000000000000/transactions"
  }
}

Store the subscriptionId, you will need it for all subsequent calls.

---

Step 2: Redirect the customer for consent#

Redirect your customer's browser to the redirectUrl returned in the response. The customer will:

1. Land on the Ozow payment page
2. Enter their Capitec-linked cell phone number
3. Approve the consent request in their Capitec app

Once the customer approves, Capitec notifies Ozow and the subscription status updates from PendingAuthorization to Active. Only then can collections be actioned.

---

Step 3: Action a payment (trigger collection)#

Once the subscription is Active and the firstPaymentDate has been reached, trigger a collection by calling the transaction endpoint.

POST https://one.ozow.com/v1/subscriptions/{subscriptionId}/transactions
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Replace {subscriptionId} with the ID returned in Step 1.

Request example

{
  "amount": { "currency": "ZAR", "value": 500.00 },
  "merchantReference": "SUB-001-SEP"
}

Both fields are required. amount.value must fall inside the amountConstraints band the customer authorised. merchantReference identifies this individual collection, not the subscription itself.

The customer does not receive any authentication prompt, the debit happens silently based on the consent already granted.

---

Step 4: Handle the webhook notification#

Ozow sends webhookWebhook A URL of yours that Ozow calls when something happens, rather than you polling to find out. The call carries no credential of yours and arrives at a public URL, so authenticate it before acting on it: a hash field on the Payments API, a Svix signature on One API. notifications for subscription events. Subscribe to these events in your One API client webhook configuration:

Subscribe to the name exactly as written. An event name the service does not know is rejected, so a subscription to something close is a subscription that never fires.

Handle these exactly as described in Step 4: Handle the webhook notification in the One API redirect guide, the same Svix signature verification process applies.

---

Subscription management#

---

Subscription statuses#

---

Go-live checklist#

• Recurring payments have been enabled on your merchant profile by Ozow
• One API client has the subscriptions scope
• paymentMethod is set to capitec in the subscription payload
• firstPaymentDate is set to a valid present or future date
• merchantReference is unique per subscription with no spaces
• Customer Identity Verification is included in the consent step if required for your industry
• Redirect flow correctly sends customers to the Capitec consent page
• Webhook handlers are configured for the consent and collection events you rely on, spelled as the service spells them
• Your system handles the Expired status and can create a new subscription when needed
• Staging testing completed end to end before production go-live

---

Next steps#

• Review the Building a secure integration checklist before going live
• See the One API reference for the full subscription endpoint specifications
• Contact support@ozow.com to confirm recurring payments are enabled on your merchant profile