Request Payment

POST /payments

Try it

Parameters

Idempotency-KeyheaderX-Correlation-IDheader

Bodyapplication/json

siteCode*regionamount.currency*amount.value*min 0.01variableAmount.minimumValue*min 0.01variableAmount.maximumValue*min 0.01merchantReference*beneficiaryReference^[A-Za-z0-9]*$payerReferencepayer.id*payer.name*payer.identity.type*payer.identity.country*payer.identity.identifier*payer.cellphonepayer.emailreturnUrlnotifyUrlexpireAt*institutionId

Request sampleLanguage

curl -X POST 'https://one.ozow.com/v1/payments' \
  -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": "SITE-001",
  "region": "ZA",
  "amount": {
    "currency": "ZAR",
    "value": 50
  },
  "variableAmount": {
    "minimumValue": 10,
    "maximumValue": 50
  },
  "merchantReference": "12345-abcde",
  "beneficiaryReference": "ONLINESHOP002",
  "payerReference": "12345-abcde",
  "payer": {
    "id": "string",
    "name": "Firstname Lastname",
    "identity": {
      "type": "said",
      "country": "ZA",
      "identifier": "0000000000000"
    },
    "cellphone": "+27821234567",
    "email": "a@example.com"
  },
  "returnUrl": "https://example.com/",
  "notifyUrl": "https://example.com/",
  "expireAt": "2026-01-15T09:30:00Z",
  "institutionId": "00000000-0000-0000-0000-000000000000"
}'

Response exampleStatus

{
  "links": {
    "self": "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "cancel": "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel",
    "transactions": "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/transactions"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "Created",
  "reason": "<reason>",
  "redirectUrl": "https://example.com/redirecturl"
}

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

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

Build with AI 3 packages

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 paymentEverything needed to take a payment end to end with One API, from credentials through the hosted page to the webhook that confirms it, and the test cases that prove each outcome before you go live.
View package
Migrate a payin from the Payments API to One APIEverything needed to move an existing redirect payin onto One API, with the legacy guide and its One API counterpart side by side.
View package
Migrate refunds from the Payments API to One APIEverything needed to move an existing refunds integration onto One API, with the legacy guide and its One API counterpart side by side.
View package

Create a payment request with the specified channel and transaction details.

Authentication

OAuth 2.0
scopespayments

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 merchant site code in use for this payment. Site codes are available on the Ozow dashboard.
max length50
region string
ISO 3166-Alpha-2 code for the originating country of the payment.

Must be "ZA" for South Africa.

If region is not specified IP geolocation will be used to determine the applicable region.
min length2max length2
amount Amount required
The currency and amount of the payment request.
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
variableAmount VariableAmount
If the payment amount can be changed by the payer, the variable amounts need to be passed in.
Fields of VariableAmount
- minimumValue number float required
  The minimum amount.
  min0.01
- maximumValue number float required
  The maximum amount.
  min0.01
Open VariableAmount on its own page
merchantReference string required
The merchant's reference for the transaction. It is pre-populated in the payer's own reference field at their bank, shortened by banks that limit it, so it is not an internal-only value.
max length50
beneficiaryReference string
The reference that appears on the merchant's bank statement for the payment. Letters and numbers only. Rejected as missing unless the site is configured to let the payer supply the reference. A site prefix, where one is configured, counts towards the 20 characters.
max length20pattern^[A-Za-z0-9]*$
payerReference string
max length20
payer Payer
Information on the payer used for identification and fraud purposes.
Fields of Payer
- id string required
  The merchant identifier for the payer.
  max length50
- name string required
  max length200
- identity Identification
  The identity of a payer. In high risk cases this information is required.
  Fields of Identification
  type string required
  The type of identification for the person or business.
  values"said""passport""registration""cellphone"
  country string required
  The ISO-3166-alpha-2 identifier for the country of identification.
  min length2max length2
  identifier string required
  The identifier for the consumer based on the identity type.
  max length20
  Open Identification on its own page
- cellphone string
  The cellphone number for the payer.
  max length15
- email string email
  The email address of the payer.
Open Payer on its own page
returnUrl string uri
The URI that Ozow needs to redirect back to once the payment has reached a conclusion. Must be reachable from the internet. localhost is rejected with a 403, so a local integration needs a tunnel rather than the address the browser uses.
notifyUrl string uri
Optional notify URL to send notifications of the status of the payment. The recommendation is to use webhooks instead of this method which are configurable via the webhooks endpoints of the API or via the Ozow Dashboard. Must be reachable from the internet. localhost is rejected with a 403, so a local integration needs a tunnel rather than the address the browser uses.
expireAt string date-time required
The date and time the payment request should expire at and make the payment link unusable
institutionId string uuid
The institution to send the payer straight to, skipping the payment method selection screen. The identifier for each payment method is on that method's page under Payment products.

Responses

200 OK

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

links PaymentLinks required
The relevant links to the this payment.
Fields of PaymentLinks
- self string uri
  The unique URI for this resource.
- cancel string uri
  The cancel URI for this payment. This is a POST operation.
- transactions string uri
  The transactions associated with this payment request.
Open PaymentLinks on its own page
id string uuid required
The identifier for the payment request.
status PaymentStatus required
The status of the payment.
values"Created""Expired"
reason string
The payment status reason.
redirectUrl string uri
The url to redirect a consumer to. A redirect url will be provided should a payment require further client interaction.

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
}

403 Forbidden.

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 token is valid but lacks the scope the operation needs

{
  "id": "c47a2e08-9b31-4f6d-85a0-7e2c1d9f3b56",
  "links": {
    "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token",
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1"
  },
  "code": "Forbidden",
  "title": "Forbidden Request",
  "detail": "Request is forbidden, most likely scope does not match required scope to perform requested action.",
  "source": {
    "pointer": null,
    "parameter": null,
    "header": "Authorization"
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

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"
  }
}

500 Internal Server Error.

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 request failed on the Ozow side

{
  "id": "9e0d5a83-6b24-4c19-8f7a-2d1b3e6c0a97",
  "links": null,
  "code": "InternalServerError",
  "title": "Internal Server Error",
  "detail": "Error occurred while processing request.",
  "source": {
    "pointer": "/data",
    "parameter": null,
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

Guides

Request

curl -X POST 'https://one.ozow.com/v1/payments' \
  -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": "SITE-001",
  "region": "ZA",
  "amount": {
    "currency": "ZAR",
    "value": 50
  },
  "variableAmount": {
    "minimumValue": 10,
    "maximumValue": 50
  },
  "merchantReference": "12345-abcde",
  "beneficiaryReference": "ONLINESHOP002",
  "payerReference": "12345-abcde",
  "payer": {
    "id": "<id>",
    "name": "Firstname Lastname",
    "identity": {
      "type": "said",
      "country": "ZA",
      "identifier": "0000000000000"
    },
    "cellphone": "+27821234567",
    "email": "a@example.com"
  },
  "returnUrl": "https://example.com/returnurl",
  "notifyUrl": "https://example.com/notifyurl",
  "expireAt": "2026-01-15T09:30:00Z",
  "institutionId": "00000000-0000-0000-0000-000000000000"
}'

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://one.ozow.com/v1/payments");
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"": ""SITE-001"",
  ""region"": ""ZA"",
  ""amount"": {
    ""currency"": ""ZAR"",
    ""value"": 50
  },
  ""variableAmount"": {
    ""minimumValue"": 10,
    ""maximumValue"": 50
  },
  ""merchantReference"": ""12345-abcde"",
  ""beneficiaryReference"": ""ONLINESHOP002"",
  ""payerReference"": ""12345-abcde"",
  ""payer"": {
    ""id"": ""<id>"",
    ""name"": ""Firstname Lastname"",
    ""identity"": {
      ""type"": ""said"",
      ""country"": ""ZA"",
      ""identifier"": ""0000000000000""
    },
    ""cellphone"": ""+27821234567"",
    ""email"": ""a@example.com""
  },
  ""returnUrl"": ""https://example.com/returnurl"",
  ""notifyUrl"": ""https://example.com/notifyurl"",
  ""expireAt"": ""2026-01-15T09:30:00Z"",
  ""institutionId"": ""00000000-0000-0000-0000-000000000000""
}", 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/payments',
    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": "SITE-001",
  "region": "ZA",
  "amount": {
    "currency": "ZAR",
    "value": 50
  },
  "variableAmount": {
    "minimumValue": 10,
    "maximumValue": 50
  },
  "merchantReference": "12345-abcde",
  "beneficiaryReference": "ONLINESHOP002",
  "payerReference": "12345-abcde",
  "payer": {
    "id": "<id>",
    "name": "Firstname Lastname",
    "identity": {
      "type": "said",
      "country": "ZA",
      "identifier": "0000000000000"
    },
    "cellphone": "+27821234567",
    "email": "a@example.com"
  },
  "returnUrl": "https://example.com/returnurl",
  "notifyUrl": "https://example.com/notifyurl",
  "expireAt": "2026-01-15T09:30:00Z",
  "institutionId": "00000000-0000-0000-0000-000000000000"
}
JSON,
]);

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

const response = await fetch("https://one.ozow.com/v1/payments", {
  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": "SITE-001",
    "region": "ZA",
    "amount": {
      "currency": "ZAR",
      "value": 50
    },
    "variableAmount": {
      "minimumValue": 10,
      "maximumValue": 50
    },
    "merchantReference": "12345-abcde",
    "beneficiaryReference": "ONLINESHOP002",
    "payerReference": "12345-abcde",
    "payer": {
      "id": "<id>",
      "name": "Firstname Lastname",
      "identity": {
        "type": "said",
        "country": "ZA",
        "identifier": "0000000000000"
      },
      "cellphone": "+27821234567",
      "email": "a@example.com"
    },
    "returnUrl": "https://example.com/returnurl",
    "notifyUrl": "https://example.com/notifyurl",
    "expireAt": "2026-01-15T09:30:00Z",
    "institutionId": "00000000-0000-0000-0000-000000000000"
  }),
});

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": "SITE-001",
    "region": "ZA",
    "amount": {
        "currency": "ZAR",
        "value": 50,
    },
    "variableAmount": {
        "minimumValue": 10,
        "maximumValue": 50,
    },
    "merchantReference": "12345-abcde",
    "beneficiaryReference": "ONLINESHOP002",
    "payerReference": "12345-abcde",
    "payer": {
        "id": "<id>",
        "name": "Firstname Lastname",
        "identity": {
            "type": "said",
            "country": "ZA",
            "identifier": "0000000000000",
        },
        "cellphone": "+27821234567",
        "email": "a@example.com",
    },
    "returnUrl": "https://example.com/returnurl",
    "notifyUrl": "https://example.com/notifyurl",
    "expireAt": "2026-01-15T09:30:00Z",
    "institutionId": "00000000-0000-0000-0000-000000000000",
}

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

Response

{
  "links": {
    "self": "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "cancel": "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel",
    "transactions": "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/transactions"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "Created",
  "reason": "<reason>",
  "redirectUrl": "https://example.com/redirecturl"
}

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

Created

{
  "links": {
    "self": "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "cancel": "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel",
    "transactions": "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/transactions"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "Created",
  "reason": "<reason>",
  "redirectUrl": "https://example.com/redirecturl"
}

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
}

Forbidden.

{
  "id": "c47a2e08-9b31-4f6d-85a0-7e2c1d9f3b56",
  "links": {
    "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token",
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1"
  },
  "code": "Forbidden",
  "title": "Forbidden Request",
  "detail": "Request is forbidden, most likely scope does not match required scope to perform requested action.",
  "source": {
    "pointer": null,
    "parameter": null,
    "header": "Authorization"
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

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"
  }
}

Internal Server Error.

{
  "id": "9e0d5a83-6b24-4c19-8f7a-2d1b3e6c0a97",
  "links": null,
  "code": "InternalServerError",
  "title": "Internal Server Error",
  "detail": "Error occurred while processing request.",
  "source": {
    "pointer": "/data",
    "parameter": null,
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}