Request Transaction for Payment

POST /payments/{id}/transactions

Try it

Parameters

X-Correlation-IDheaderIdempotency-Keyheaderid*path

Bodyapplication/json

paymentType*details.institutionId*details.beneficiary.institutionId*details.beneficiary.institutionNamedetails.beneficiary.accountNumber*details.beneficiary.branchCode*details.verifiedBankAccount.institutionId*details.verifiedBankAccount.institutionNamedetails.verifiedBankAccount.accountNumber*details.verifiedBankAccount.branchCode*

Request sampleLanguage

curl -X POST 'https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/transactions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'X-Correlation-ID: 00000000-0000-0000-0000-000000000000' \
  -H 'Idempotency-Key: string' \
  -d '{
  "paymentType": "ozowredirect",
  "details": {
    "institutionId": "00000000-0000-0000-0000-000000000000",
    "beneficiary": {
      "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
      "institutionName": "Demo Bank",
      "accountNumber": "1234567890",
      "branchCode": "5040"
    },
    "verifiedBankAccount": {
      "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
      "institutionName": "Demo Bank",
      "accountNumber": "1234567890",
      "branchCode": "5040"
    }
  }
}'

Response exampleStatus

{
  "transaction": {
    "links": {
      "self": "https://one.ozow.com/v1/transactions/497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "refund": "https://one.ozow.com/v1/transactions/497f6eca-6276-4993-bfeb-53cbbbba6f08/refunds"
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "amount": {
      "currency": "ZAR",
      "value": 50
    },
    "merchantReference": "12345-abcde",
    "siteCode": "SITE-001",
    "institution": "First National Bank",
    "status": "Incomplete",
    "reason": "<reason>",
    "createdDate": "2026-01-15T09:30:00Z",
    "completedDate": "2026-01-15T09:32:47Z"
  },
  "requiredActionOptions": [
    {
      "action": "redirect",
      "uri": "https://pay.ozow.com/497f6eca-6276-4993-bfeb-53cbbbba6f08/secure",
      "inputRequired": {
        "transactionId": "5ecaafc2-354f-47d9-822d-d0bd8b77eab3",
        "paymentStep": "Login",
        "pageTitle": "Login Details",
        "pageInstructions": "Log in using your internet banking profile.",
        "pageActionText": "Login",
        "displayType": "form",
        "inputFields": [
          {
            "name": "MobileNumber",
            "label": "Enter Mobile Number",
            "fieldType": "text",
            "properties": {
              "maxLength": 10,
              "isOptional": true,
              "isSensitive": true
            }
          }
        ]
      }
    }
  ]
}

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

POSThttps://one.ozow.com/v1/payments/{id}/transactionsProduction

Start a transaction against an existing payment request by supplying the payment details directly, rather than redirecting the payer to Ozow. Takes a paymentType and the details object matching it.

Authentication

OAuth 2.0
scopespayments

Path parameters

id string required
The unique identifier of the payment.
example497f6eca-6276-4993-bfeb-53cbbbba6f08

Header parameters

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.
Idempotency-Key string
The unique key idempotency key as per the following IETF Draft

Request body

paymentType string required
The payment type being made. To redirect to Ozow with a specific institution pre-selected please use the ozowredirect type.

Except for the ozowredirect payment type, all the other listed options require implementation of a callback url to handle responses and requests for more information to complete processing.

Payment types such as absapay, card and payshap have pre-requisites that must be met and may not be available for particular payments and amounts.
values"ozowredirect""absapay""bankdeposit""card""nedbankdirecteft""ozowwallet""payshap""voucher"
details one of

Responses

200 OK

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

transaction Transaction
Fields of Transaction
- links TransactionLinks
  Fields of TransactionLinks
  self string uri required
  The unique URI for this resource.
  refund string uri
  The refund operation for this transaction. This is a POST operation.
  Open TransactionLinks on its own page
- id string uuid required
  The transaction id of the payment.
- amount Amount
  The amount that was requested.
  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
- merchantReference string required
  The merchant's reference for the transaction.
  max length50
- siteCode string required
  The merchant site code in use for this payment.
  max length50
- institution string required
  The institution for the transaction.
- status TransactionStatus required
  The status of the transaction.
  values"Incomplete""Successful""Error""Pending""Refunded"
- reason string
  Payment status reason.
- createdDate string date-time required
  The date the transaction was created.
- completedDate string date-time
  The date the transaction was completed.
Open Transaction on its own page
requiredActionOptions array of RequiredAction
Fields of RequiredAction
- action string required
  The action if any that is required next.
  values"redirect""api""websocket"
- uri string uri
  The URI to redirect, connect to the WebSocket or make the POST API call if required.
- inputRequired InputResponse
  Fields of InputResponse
  transactionId string uuid required
  The transaction id of the payment being processed.
  paymentStep string required
  The name of the payment step being performed.
  pageTitle string required
  The title of the page, this will be a user friendly message and can be displayed to the end user.
  pageInstructions string required
  Instructions for the end user to perform, this will be a user friendly message and can be displayed to the end user.
  pageActionText string required
  The action type, this could typically be used as the text for a button or link. This will be a user friendly message and can be displayed to the end user.
  displayType string required
  The display type which indicates what sort of action should be taken. form will require asking the user for input, prompt will require instructing the user to perform an action (e.g. accept a push message) and busy will require asking the user to wait.
  values"form""prompt""busy"
  inputFields array of InputField
  If the object is of the form display type the input fields the user would need to complete will be returned in this array.
  Fields of InputField
  name string required
  The name of the transaction input field.
  label string
  The display name of the transaction input field, this will be a user friendly message and can be displayed to the end user.
  fieldType string required
  values"text""select""imagecapture""iframe""partialtext"
  properties any of required
  InputFieldText
  InputFieldSelect
  InputFieldImageCapture
  InputFieldIFrame
  InputFieldPartialText
  Open InputField on its own page
  Open InputResponse on its own page
Open RequiredAction on its own page

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

Request

curl -X POST 'https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/transactions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'X-Correlation-ID: 00000000-0000-0000-0000-000000000000' \
  -H 'Idempotency-Key: string' \
  -d '{
  "paymentType": "ozowredirect",
  "details": {
    "institutionId": "00000000-0000-0000-0000-000000000000",
    "beneficiary": {
      "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
      "institutionName": "Demo Bank",
      "accountNumber": "1234567890",
      "branchCode": "5040"
    },
    "verifiedBankAccount": {
      "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
      "institutionName": "Demo Bank",
      "accountNumber": "1234567890",
      "branchCode": "5040"
    }
  }
}'

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/transactions");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("X-Correlation-ID", "00000000-0000-0000-0000-000000000000");
request.Headers.Add("Idempotency-Key", "string");

request.Content = new StringContent(@"{
  ""paymentType"": ""ozowredirect"",
  ""details"": {
    ""institutionId"": ""00000000-0000-0000-0000-000000000000"",
    ""beneficiary"": {
      ""institutionId"": ""ba18699f-8f5f-497b-9bcd-445133076408"",
      ""institutionName"": ""Demo Bank"",
      ""accountNumber"": ""1234567890"",
      ""branchCode"": ""5040""
    },
    ""verifiedBankAccount"": {
      ""institutionId"": ""ba18699f-8f5f-497b-9bcd-445133076408"",
      ""institutionName"": ""Demo Bank"",
      ""accountNumber"": ""1234567890"",
      ""branchCode"": ""5040""
    }
  }
}", 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/497f6eca-6276-4993-bfeb-53cbbbba6f08/transactions',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_ACCESS_TOKEN',
        'Content-Type: application/json',
        'X-Correlation-ID: 00000000-0000-0000-0000-000000000000',
        'Idempotency-Key: string',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "paymentType": "ozowredirect",
  "details": {
    "institutionId": "00000000-0000-0000-0000-000000000000",
    "beneficiary": {
      "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
      "institutionName": "Demo Bank",
      "accountNumber": "1234567890",
      "branchCode": "5040"
    },
    "verifiedBankAccount": {
      "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
      "institutionName": "Demo Bank",
      "accountNumber": "1234567890",
      "branchCode": "5040"
    }
  }
}
JSON,
]);

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

const response = await fetch("https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/transactions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "X-Correlation-ID": "00000000-0000-0000-0000-000000000000",
    "Idempotency-Key": "string",
  },
  body: JSON.stringify({
    "paymentType": "ozowredirect",
    "details": {
      "institutionId": "00000000-0000-0000-0000-000000000000",
      "beneficiary": {
        "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
        "institutionName": "Demo Bank",
        "accountNumber": "1234567890",
        "branchCode": "5040"
      },
      "verifiedBankAccount": {
        "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
        "institutionName": "Demo Bank",
        "accountNumber": "1234567890",
        "branchCode": "5040"
      }
    }
  }),
});

const data = await response.json();

import requests

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

payload = {
    "paymentType": "ozowredirect",
    "details": {
        "institutionId": "00000000-0000-0000-0000-000000000000",
        "beneficiary": {
            "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
            "institutionName": "Demo Bank",
            "accountNumber": "1234567890",
            "branchCode": "5040",
        },
        "verifiedBankAccount": {
            "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
            "institutionName": "Demo Bank",
            "accountNumber": "1234567890",
            "branchCode": "5040",
        },
    },
}

response = requests.post(
    "https://one.ozow.com/v1/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/transactions",
    headers=headers,
    json=payload,
)

Response

{
  "transaction": {
    "links": {
      "self": "https://one.ozow.com/v1/transactions/497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "refund": "https://one.ozow.com/v1/transactions/497f6eca-6276-4993-bfeb-53cbbbba6f08/refunds"
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "amount": {
      "currency": "ZAR",
      "value": 50
    },
    "merchantReference": "12345-abcde",
    "siteCode": "SITE-001",
    "institution": "First National Bank",
    "status": "Incomplete",
    "reason": "<reason>",
    "createdDate": "2026-01-15T09:30:00Z",
    "completedDate": "2026-01-15T09:32:47Z"
  },
  "requiredActionOptions": [
    {
      "action": "redirect",
      "uri": "https://pay.ozow.com/497f6eca-6276-4993-bfeb-53cbbbba6f08/secure",
      "inputRequired": {
        "transactionId": "5ecaafc2-354f-47d9-822d-d0bd8b77eab3",
        "paymentStep": "Login",
        "pageTitle": "Login Details",
        "pageInstructions": "Log in using your internet banking profile.",
        "pageActionText": "Login",
        "displayType": "form",
        "inputFields": [
          {
            "name": "MobileNumber",
            "label": "Enter Mobile Number",
            "fieldType": "text",
            "properties": {
              "maxLength": 10,
              "isOptional": true,
              "isSensitive": true
            }
          }
        ]
      }
    }
  ]
}

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

Created

{
  "transaction": {
    "links": {
      "self": "https://one.ozow.com/v1/transactions/497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "refund": "https://one.ozow.com/v1/transactions/497f6eca-6276-4993-bfeb-53cbbbba6f08/refunds"
    },
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "amount": {
      "currency": "ZAR",
      "value": 50
    },
    "merchantReference": "12345-abcde",
    "siteCode": "SITE-001",
    "institution": "First National Bank",
    "status": "Incomplete",
    "reason": "<reason>",
    "createdDate": "2026-01-15T09:30:00Z",
    "completedDate": "2026-01-15T09:32:47Z"
  },
  "requiredActionOptions": [
    {
      "action": "redirect",
      "uri": "https://pay.ozow.com/497f6eca-6276-4993-bfeb-53cbbbba6f08/secure",
      "inputRequired": {
        "transactionId": "5ecaafc2-354f-47d9-822d-d0bd8b77eab3",
        "paymentStep": "Login",
        "pageTitle": "Login Details",
        "pageInstructions": "Log in using your internet banking profile.",
        "pageActionText": "Login",
        "displayType": "form",
        "inputFields": [
          {
            "name": "MobileNumber",
            "label": "Enter Mobile Number",
            "fieldType": "text",
            "properties": {
              "maxLength": 10,
              "isOptional": true,
              "isSensitive": true
            }
          }
        ]
      }
    }
  ]
}

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