Create Subscription

POST /subscriptions

Try it

Parameters

Idempotency-KeyheaderX-Correlation-IDheader

Bodyapplication/json

siteCode*amount.currency*amount.value*min 0.01amountConstraints.min.currency*amountConstraints.min.value*min 0.01amountConstraints.max.currency*amountConstraints.max.value*min 0.01payableNow.amount.currency*payableNow.amount.value*min 0.01payableNow.date*identity.type*identity.country*identity.identifier*description*merchantReference*^\S+$bankReference*^[a-zA-Z0-9]+$frequency*firstPaymentDate*occurrences*min 1, max 120paymentMethod

Request sampleLanguage

curl -X POST 'https://one.ozow.com/v1/subscriptions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'X-Correlation-ID: 00000000-0000-0000-0000-000000000000' \
  -d '{
  "siteCode": "ABC-123456789",
  "amount": {
    "currency": "ZAR",
    "value": 50
  },
  "amountConstraints": {
    "min": {
      "currency": "ZAR",
      "value": 50
    },
    "max": {
      "currency": "ZAR",
      "value": 50
    }
  },
  "payableNow": {
    "amount": {
      "currency": "ZAR",
      "value": 50
    },
    "date": "2026-06-25"
  },
  "identity": {
    "type": "said",
    "country": "ZA",
    "identifier": "string"
  },
  "description": "Monthly plan",
  "merchantReference": "SUB-0001",
  "bankReference": "MyStore",
  "frequency": "Monthly",
  "firstPaymentDate": "2026-07-01",
  "occurrences": 12,
  "paymentMethod": "capitec"
}'

Response exampleStatus

{
  "subscriptionId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "Active",
  "siteCode": "ABC-123456789",
  "amount": {
    "currency": "ZAR",
    "value": 50
  },
  "amountConstraints": {
    "min": {
      "currency": "ZAR",
      "value": 50
    },
    "max": {
      "currency": "ZAR",
      "value": 50
    }
  },
  "payableNow": {
    "amount": {
      "currency": "ZAR",
      "value": 50
    },
    "date": "2026-06-25"
  },
  "description": "Monthly plan",
  "merchantReference": "SUB-0001",
  "bankReference": "MyStore",
  "frequency": "Monthly",
  "firstPaymentDate": "2026-07-01",
  "occurrences": 12,
  "redirectUrl": "https://example.com/redirecturl",
  "authorization": {
    "status": "<status>"
  },
  "links": {
    "self": "https://example.com/self",
    "cancel": "https://example.com/cancel",
    "transactions": "https://example.com/transactions"
  }
}

Built from the response schema. Values are placeholders, not real data.

POSThttps://one.ozow.com/v1/subscriptionsProduction

Build with AI 1 package

A build package is every page for one task, with the API operations they use. Copy the prompt into a coding assistant, or hand it the package itself: slim links to each page, full inlines all of them in one document.

Take a recurring paymentEverything needed to collect from a customer on a schedule with One API, from the consent the customer gives once through to each collection and the webhook that reports it.
View package

Create a recurring payment subscription. The response includes a redirectUrl to the hosted page where the customer authorises the amount band; the subscription becomes active once authorised.

Authentication

OAuth 2.0
scopessubscriptions

Header parameters

Idempotency-Key string
The unique key idempotency key as per the following IETF Draft
X-Correlation-ID string
Optional correlation id for the request, if not supplied a new one will be generated and passed onto all underlying requests and returned as a header.

Request body

siteCode string required
The site code the subscription belongs to.
max length50
amount Amount required
The recurring charge amount. Must be ZAR and fall within the authorised band [amountConstraints.min, amountConstraints.max].
Fields of Amount
- currency string required
  The ISO 4217 current code.
  min length3max length3
- value number float required
  The amount in the currency specified.
  min0.01
Open Amount on its own page
amountConstraints AmountConstraints required
The per-payment authorisation band the customer approves.
Fields of AmountConstraints
- min Amount required
  The minimum authorised per-payment amount. Whole Rand, greater than 0.
  Fields of Amount
  currency string required
  The ISO 4217 current code.
  min length3max length3
  value number float required
  The amount in the currency specified.
  min0.01
  Open Amount on its own page
- max Amount required
  The maximum authorised per-payment amount. Whole Rand, greater than min, and not exceeding 100000.
  Fields of Amount
  currency string required
  The ISO 4217 current code.
  min length3max length3
  value number float required
  The amount in the currency specified.
  min0.01
  Open Amount on its own page
Open AmountConstraints on its own page
payableNow PayableNow
An optional once-off charge taken at sign-up. This charge is not bound by amountConstraints.
Fields of PayableNow
- amount Amount required
  The once-off charge amount. Must be ZAR.
  Fields of Amount
  currency string required
  The ISO 4217 current code.
  min length3max length3
  value number float required
  The amount in the currency specified.
  min0.01
  Open Amount on its own page
- date string date required
  The date the once-off charge is taken. Must be today or a future date.
Open PayableNow on its own page
identity object
An optional customer identifier used for matching. Treated as personal information: it is accepted on the request but is never returned on any response (POPIA data minimisation).
- type string required
  The type of identification for the customer.
  values"said""passport""registration""cellphone"
- country string required
  The ISO 3166 alpha-2 code for the country of identification.
  min length2max length2
- identifier string required
  The identifier value for the given identity type.
  max length20
description string required
A short description of the subscription.
max length20
merchantReference string required
Your unique reference for the subscription. Must not contain spaces.
max length50pattern^\S+$
bankReference string required
The reference that appears on the merchant's bank statement for each payment in the subscription. Letters and numbers only. A site prefix, where one is configured, counts towards the 20 characters.
max length20pattern^[a-zA-Z0-9]+$
frequency SubscriptionFrequency required
The billing cadence of a subscription.
values"Daily""Weekly""Fortnightly""Monthly""Biannually""Annually"
firstPaymentDate string date required
The date of the first scheduled charge. Must be today or a future date.
occurrences integer required
The total number of scheduled charges over the life of the subscription.
min1max120
paymentMethod string
Optional. The payment method (rail) used to collect charges. Defaults to capitec when omitted, which is currently the only supported method. Not returned on responses.
values"capitec"

Responses

201 Created. The subscription was created and is awaiting customer authorisation.

X-Correlation-ID header
The correlation id for the request that was processed.
Location header
The unique URI for this subscription.

subscriptionId string required
The unique identifier of the subscription.
status SubscriptionStatus required
The lifecycle status of a subscription:
- PendingAuthorization - created, awaiting customer authorisation via redirectUrl.
- Active - authorised; scheduled charges are being taken.
- Canceled - cancelled; no further charges.
- Completed - all scheduled occurrences have been taken.
- Expired - the authorisation lapsed before activation.
- Failed - the subscription could not be established or sustained.
- Unknown - the status could not be determined.
values"PendingAuthorization""Active""Canceled""Completed""Expired""Failed""Unknown"
siteCode string required
The site code the subscription belongs to.
amount Amount required
The recurring charge amount.
Fields of Amount
- currency string required
  The ISO 4217 current code.
  min length3max length3
- value number float required
  The amount in the currency specified.
  min0.01
Open Amount on its own page
amountConstraints AmountConstraints
The authorised per-payment band. Returned on create and get.
Fields of AmountConstraints
- min Amount required
  The minimum authorised per-payment amount. Whole Rand, greater than 0.
  Fields of Amount
  currency string required
  The ISO 4217 current code.
  min length3max length3
  value number float required
  The amount in the currency specified.
  min0.01
  Open Amount on its own page
- max Amount required
  The maximum authorised per-payment amount. Whole Rand, greater than min, and not exceeding 100000.
  Fields of Amount
  currency string required
  The ISO 4217 current code.
  min length3max length3
  value number float required
  The amount in the currency specified.
  min0.01
  Open Amount on its own page
Open AmountConstraints on its own page
payableNow PayableNow
The once-off sign-up charge. Returned on create only.
Fields of PayableNow
- amount Amount required
  The once-off charge amount. Must be ZAR.
  Fields of Amount
  currency string required
  The ISO 4217 current code.
  min length3max length3
  value number float required
  The amount in the currency specified.
  min0.01
  Open Amount on its own page
- date string date required
  The date the once-off charge is taken. Must be today or a future date.
Open PayableNow on its own page
description string
The subscription description.
merchantReference string required
Your reference for the subscription.
bankReference string
The reference that appears on the merchant's bank statement for each payment in the subscription.
frequency SubscriptionFrequency
The billing cadence of a subscription.
values"Daily""Weekly""Fortnightly""Monthly""Biannually""Annually"
firstPaymentDate string date required
The date of the first scheduled charge.
occurrences integer required
The total number of scheduled charges.
redirectUrl string uri
The hosted authorisation page the customer must be redirected to in order to approve the subscription. Present while authorisation is pending.
authorization object
The customer's authorisation (consent) status. Populated once the customer has authorised via redirectUrl.
- status string
  The provider-mirrored authorisation status.
links object required
Related resource links for the subscription.
- self string uri
  The URI of this subscription.
- cancel string uri
  The URI to cancel this subscription.
- transactions string uri
  The URI to create an ad-hoc charge against this subscription.

400 Bad Request.

X-Correlation-ID header
The correlation id for the request that was processed.

id string uuid required
a unique identifier for this particular occurrence of the problem.
links object nullable
Present on an authentication or authorisation failure, and null otherwise.
- about string uri
  A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error.
- type string uri
  A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error.
code string required
An application-specific error code, expressed as a string value. Key on this rather than on title or detail, which are written for a person. A rejection at the transport level uses the status name, one of BadRequest, Unauthorized, Forbidden, NotFound, NotAllowed, Conflict, UnsupportedMediaType, BadGateway or InternalServerError. An operation refusing a request on its own rules returns a code of its own.
title string required
A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail string required
A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source object nullable
Where in the request the problem was found. All three keys are present whenever source is, with the ones that do not apply set to null. source itself is null where the failure is not about a part of the request.
- pointer string json-pointer nullable
  a JSON Pointer RFC6901 to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer.
- parameter string nullable
  A string indicating which URI query parameter caused the error.
- header string nullable
  A string indicating the name of a single request header which caused the error.
meta object nullable
A meta object containing non-standard meta-information about the error. Null where the request carried no X-Correlation-ID, and on an authentication failure, which does not echo it.
- correlationId string
  The X-Correlation-ID sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header.

A field in the request body did not validate

{
  "id": "3a6c9e01-5f2b-4d8a-9c47-1e0b7d5a2f83",
  "links": null,
  "code": "BadRequest",
  "title": "Bad Request",
  "detail": "amount: Amount must be greater than 0",
  "source": {
    "pointer": "/amount",
    "parameter": null,
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

401 Unauthorised.

X-Correlation-ID header
The correlation id for the request that was processed.

id string uuid required
a unique identifier for this particular occurrence of the problem.
links object nullable
Present on an authentication or authorisation failure, and null otherwise.
- about string uri
  A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error.
- type string uri
  A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error.
code string required
An application-specific error code, expressed as a string value. Key on this rather than on title or detail, which are written for a person. A rejection at the transport level uses the status name, one of BadRequest, Unauthorized, Forbidden, NotFound, NotAllowed, Conflict, UnsupportedMediaType, BadGateway or InternalServerError. An operation refusing a request on its own rules returns a code of its own.
title string required
A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail string required
A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source object nullable
Where in the request the problem was found. All three keys are present whenever source is, with the ones that do not apply set to null. source itself is null where the failure is not about a part of the request.
- pointer string json-pointer nullable
  a JSON Pointer RFC6901 to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer.
- parameter string nullable
  A string indicating which URI query parameter caused the error.
- header string nullable
  A string indicating the name of a single request header which caused the error.
meta object nullable
A meta object containing non-standard meta-information about the error. Null where the request carried no X-Correlation-ID, and on an authentication failure, which does not echo it.
- correlationId string
  The X-Correlation-ID sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header.

No usable access token on the request

{
  "id": "1cecc2b7-1c29-418a-b26a-bf7546926083",
  "links": {
    "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token",
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1"
  },
  "code": "Unauthorized",
  "title": "Unauthorized Request",
  "detail": "Authorization header is missing or invalid.",
  "source": {
    "pointer": null,
    "parameter": null,
    "header": "Authorization"
  },
  "meta": null
}

409 Conflict.

X-Correlation-ID header
The correlation id for the request that was processed.

id string uuid required
a unique identifier for this particular occurrence of the problem.
links object nullable
Present on an authentication or authorisation failure, and null otherwise.
- about string uri
  A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error.
- type string uri
  A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error.
code string required
An application-specific error code, expressed as a string value. Key on this rather than on title or detail, which are written for a person. A rejection at the transport level uses the status name, one of BadRequest, Unauthorized, Forbidden, NotFound, NotAllowed, Conflict, UnsupportedMediaType, BadGateway or InternalServerError. An operation refusing a request on its own rules returns a code of its own.
title string required
A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail string required
A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source object nullable
Where in the request the problem was found. All three keys are present whenever source is, with the ones that do not apply set to null. source itself is null where the failure is not about a part of the request.
- pointer string json-pointer nullable
  a JSON Pointer RFC6901 to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer.
- parameter string nullable
  A string indicating which URI query parameter caused the error.
- header string nullable
  A string indicating the name of a single request header which caused the error.
meta object nullable
A meta object containing non-standard meta-information about the error. Null where the request carried no X-Correlation-ID, and on an authentication failure, which does not echo it.
- correlationId string
  The X-Correlation-ID sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header.

The idempotency key was reused with a different body

{
  "id": "2f8b6d40-1c7e-49a5-b03f-8d5a2e1c9704",
  "links": null,
  "code": "Conflict",
  "title": "Conflict",
  "detail": "Idempotency key and request data do not match a previous request.",
  "source": {
    "pointer": null,
    "parameter": null,
    "header": "Idempotency-Key"
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

502 Bad Gateway. An upstream payment service was unreachable or returned an error; the request was not completed. Safe to retry shortly.

X-Correlation-ID header
The correlation id for the request that was processed.

id string uuid required
a unique identifier for this particular occurrence of the problem.
links object nullable
Present on an authentication or authorisation failure, and null otherwise.
- about string uri
  A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error.
- type string uri
  A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error.
code string required
An application-specific error code, expressed as a string value. Key on this rather than on title or detail, which are written for a person. A rejection at the transport level uses the status name, one of BadRequest, Unauthorized, Forbidden, NotFound, NotAllowed, Conflict, UnsupportedMediaType, BadGateway or InternalServerError. An operation refusing a request on its own rules returns a code of its own.
title string required
A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail string required
A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source object nullable
Where in the request the problem was found. All three keys are present whenever source is, with the ones that do not apply set to null. source itself is null where the failure is not about a part of the request.
- pointer string json-pointer nullable
  a JSON Pointer RFC6901 to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer.
- parameter string nullable
  A string indicating which URI query parameter caused the error.
- header string nullable
  A string indicating the name of a single request header which caused the error.
meta object nullable
A meta object containing non-standard meta-information about the error. Null where the request carried no X-Correlation-ID, and on an authentication failure, which does not echo it.
- correlationId string
  The X-Correlation-ID sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header.

An upstream payment service could not be reached

{
  "id": "6c3a1f95-8d07-4e2b-a94c-5f0b7d2e8134",
  "links": null,
  "code": "BadGateway",
  "title": "Bad Gateway",
  "detail": "The upstream service is currently unavailable. Please try again shortly.",
  "source": null,
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

Guides

Recurring paymentsCollect repeat payments with One API. One consent the customer approves, then merchant-initiated collections that need no further customer action.

Request

curl -X POST 'https://one.ozow.com/v1/subscriptions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'X-Correlation-ID: 00000000-0000-0000-0000-000000000000' \
  -d '{
  "siteCode": "ABC-123456789",
  "amount": {
    "currency": "ZAR",
    "value": 50
  },
  "amountConstraints": {
    "min": {
      "currency": "ZAR",
      "value": 50
    },
    "max": {
      "currency": "ZAR",
      "value": 50
    }
  },
  "payableNow": {
    "amount": {
      "currency": "ZAR",
      "value": 50
    },
    "date": "2026-06-25"
  },
  "identity": {
    "type": "said",
    "country": "ZA",
    "identifier": "<identifier>"
  },
  "description": "Monthly plan",
  "merchantReference": "SUB-0001",
  "bankReference": "MyStore",
  "frequency": "Monthly",
  "firstPaymentDate": "2026-07-01",
  "occurrences": 12,
  "paymentMethod": "capitec"
}'

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://one.ozow.com/v1/subscriptions");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Idempotency-Key", "string");
request.Headers.Add("X-Correlation-ID", "00000000-0000-0000-0000-000000000000");

request.Content = new StringContent(@"{
  ""siteCode"": ""ABC-123456789"",
  ""amount"": {
    ""currency"": ""ZAR"",
    ""value"": 50
  },
  ""amountConstraints"": {
    ""min"": {
      ""currency"": ""ZAR"",
      ""value"": 50
    },
    ""max"": {
      ""currency"": ""ZAR"",
      ""value"": 50
    }
  },
  ""payableNow"": {
    ""amount"": {
      ""currency"": ""ZAR"",
      ""value"": 50
    },
    ""date"": ""2026-06-25""
  },
  ""identity"": {
    ""type"": ""said"",
    ""country"": ""ZA"",
    ""identifier"": ""<identifier>""
  },
  ""description"": ""Monthly plan"",
  ""merchantReference"": ""SUB-0001"",
  ""bankReference"": ""MyStore"",
  ""frequency"": ""Monthly"",
  ""firstPaymentDate"": ""2026-07-01"",
  ""occurrences"": 12,
  ""paymentMethod"": ""capitec""
}", Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://one.ozow.com/v1/subscriptions',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_ACCESS_TOKEN',
        'Content-Type: application/json',
        'Idempotency-Key: string',
        'X-Correlation-ID: 00000000-0000-0000-0000-000000000000',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "siteCode": "ABC-123456789",
  "amount": {
    "currency": "ZAR",
    "value": 50
  },
  "amountConstraints": {
    "min": {
      "currency": "ZAR",
      "value": 50
    },
    "max": {
      "currency": "ZAR",
      "value": 50
    }
  },
  "payableNow": {
    "amount": {
      "currency": "ZAR",
      "value": 50
    },
    "date": "2026-06-25"
  },
  "identity": {
    "type": "said",
    "country": "ZA",
    "identifier": "<identifier>"
  },
  "description": "Monthly plan",
  "merchantReference": "SUB-0001",
  "bankReference": "MyStore",
  "frequency": "Monthly",
  "firstPaymentDate": "2026-07-01",
  "occurrences": 12,
  "paymentMethod": "capitec"
}
JSON,
]);

$response = curl_exec($curl);
curl_close($curl);

const response = await fetch("https://one.ozow.com/v1/subscriptions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Idempotency-Key": "string",
    "X-Correlation-ID": "00000000-0000-0000-0000-000000000000",
  },
  body: JSON.stringify({
    "siteCode": "ABC-123456789",
    "amount": {
      "currency": "ZAR",
      "value": 50
    },
    "amountConstraints": {
      "min": {
        "currency": "ZAR",
        "value": 50
      },
      "max": {
        "currency": "ZAR",
        "value": 50
      }
    },
    "payableNow": {
      "amount": {
        "currency": "ZAR",
        "value": 50
      },
      "date": "2026-06-25"
    },
    "identity": {
      "type": "said",
      "country": "ZA",
      "identifier": "<identifier>"
    },
    "description": "Monthly plan",
    "merchantReference": "SUB-0001",
    "bankReference": "MyStore",
    "frequency": "Monthly",
    "firstPaymentDate": "2026-07-01",
    "occurrences": 12,
    "paymentMethod": "capitec"
  }),
});

const data = await response.json();

import requests

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Idempotency-Key": "string",
    "X-Correlation-ID": "00000000-0000-0000-0000-000000000000",
}

payload = {
    "siteCode": "ABC-123456789",
    "amount": {
        "currency": "ZAR",
        "value": 50,
    },
    "amountConstraints": {
        "min": {
            "currency": "ZAR",
            "value": 50,
        },
        "max": {
            "currency": "ZAR",
            "value": 50,
        },
    },
    "payableNow": {
        "amount": {
            "currency": "ZAR",
            "value": 50,
        },
        "date": "2026-06-25",
    },
    "identity": {
        "type": "said",
        "country": "ZA",
        "identifier": "<identifier>",
    },
    "description": "Monthly plan",
    "merchantReference": "SUB-0001",
    "bankReference": "MyStore",
    "frequency": "Monthly",
    "firstPaymentDate": "2026-07-01",
    "occurrences": 12,
    "paymentMethod": "capitec",
}

response = requests.post(
    "https://one.ozow.com/v1/subscriptions",
    headers=headers,
    json=payload,
)

Response

Created. The subscription was created and is awaiting customer authorisation.

{
  "subscriptionId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "Active",
  "siteCode": "ABC-123456789",
  "amount": {
    "currency": "ZAR",
    "value": 50
  },
  "amountConstraints": {
    "min": {
      "currency": "ZAR",
      "value": 50
    },
    "max": {
      "currency": "ZAR",
      "value": 50
    }
  },
  "payableNow": {
    "amount": {
      "currency": "ZAR",
      "value": 50
    },
    "date": "2026-06-25"
  },
  "description": "Monthly plan",
  "merchantReference": "SUB-0001",
  "bankReference": "MyStore",
  "frequency": "Monthly",
  "firstPaymentDate": "2026-07-01",
  "occurrences": 12,
  "redirectUrl": "https://example.com/redirecturl",
  "authorization": {
    "status": "<status>"
  },
  "links": {
    "self": "https://example.com/self",
    "cancel": "https://example.com/cancel",
    "transactions": "https://example.com/transactions"
  }
}

Built from the response schema. Values are placeholders, not real data.

Bad Request.

{
  "id": "3a6c9e01-5f2b-4d8a-9c47-1e0b7d5a2f83",
  "links": null,
  "code": "BadRequest",
  "title": "Bad Request",
  "detail": "amount: Amount must be greater than 0",
  "source": {
    "pointer": "/amount",
    "parameter": null,
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

Unauthorised.

{
  "id": "1cecc2b7-1c29-418a-b26a-bf7546926083",
  "links": {
    "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token",
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1"
  },
  "code": "Unauthorized",
  "title": "Unauthorized Request",
  "detail": "Authorization header is missing or invalid.",
  "source": {
    "pointer": null,
    "parameter": null,
    "header": "Authorization"
  },
  "meta": null
}

Conflict.

{
  "id": "2f8b6d40-1c7e-49a5-b03f-8d5a2e1c9704",
  "links": null,
  "code": "Conflict",
  "title": "Conflict",
  "detail": "Idempotency key and request data do not match a previous request.",
  "source": {
    "pointer": null,
    "parameter": null,
    "header": "Idempotency-Key"
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

Bad Gateway. An upstream payment service was unreachable or returned an error; the request was not completed. Safe to retry shortly.

{
  "id": "6c3a1f95-8d07-4e2b-a94c-5f0b7d2e8134",
  "links": null,
  "code": "BadGateway",
  "title": "Bad Gateway",
  "detail": "The upstream service is currently unavailable. Please try again shortly.",
  "source": null,
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}