Request Transaction

POST /transactions

Try it

Parameters

Idempotency-KeyheaderX-Correlation-IDheader

Bodyapplication/json

paymentRequest.siteCode*paymentRequest.regionpaymentRequest.amount.currency*paymentRequest.amount.value*min 0.01paymentRequest.variableAmount.minimumValue*min 0.01paymentRequest.variableAmount.maximumValue*min 0.01paymentRequest.merchantReference*paymentRequest.beneficiaryReference^[A-Za-z0-9]*$paymentRequest.payerReferencepaymentRequest.payer.id*paymentRequest.payer.name*

paymentRequest.payer.identity

{
  "type": "said",
  "country": "ZA",
  "identifier": "0000000000000"
}

{
  "type": "said",
  "country": "ZA",
  "identifier": "0000000000000"
}

paymentRequest.payer.cellphonepaymentRequest.payer.emailpaymentRequest.returnUrlpaymentRequest.notifyUrlpaymentRequest.expireAt*paymentRequest.institutionIdpaymentDetail.paymentType*paymentDetail.details.institutionId*

paymentDetail.details.beneficiary

{
  "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
  "institutionName": "Demo Bank",
  "accountNumber": "1234567890",
  "branchCode": "5040"
}

{
  "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
  "institutionName": "Demo Bank",
  "accountNumber": "1234567890",
  "branchCode": "5040"
}

paymentDetail.details.verifiedBankAccount

{
  "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
  "institutionName": "Demo Bank",
  "accountNumber": "1234567890",
  "branchCode": "5040"
}

{
  "institutionId": "ba18699f-8f5f-497b-9bcd-445133076408",
  "institutionName": "Demo Bank",
  "accountNumber": "1234567890",
  "branchCode": "5040"
}

Request sampleLanguage

curl -X POST 'https://one.ozow.com/v1/transactions' \
  -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 '{
  "paymentRequest": {
    "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"
  },
  "paymentDetail": {
    "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

{
  "payment": {
    "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"
  },
  "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/transactionsProduction

Create a transaction with the specified channel and transaction details for a specified type of payment.

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

paymentRequest PaymentRequest required
The payment request details.
Fields of PaymentRequest
- 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.
Open PaymentRequest on its own page
paymentDetail PaymentDetail
Fields of PaymentDetail
- 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
Open PaymentDetail on its own page

Responses

200 OK

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

payment PaymentResponse required
The payment request response.
Fields of PaymentResponse
- 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.
Open PaymentResponse on its own page
transaction Transaction required
The transaction details.
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
If a subsequent action is required, the details of what options are available.
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"
  }
}

Guides

Server to server paymentsCapture payment details on your own checkout, submit them to Ozow from your backend, and drive the rest of the transaction over a WebSocket. Not yet available for merchant integrations.

Request

curl -X POST 'https://one.ozow.com/v1/transactions' \
  -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 '{
  "paymentRequest": {
    "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"
  },
  "paymentDetail": {
    "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/transactions");
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(@"{
  ""paymentRequest"": {
    ""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""
  },
  ""paymentDetail"": {
    ""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/transactions',
    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'
{
  "paymentRequest": {
    "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"
  },
  "paymentDetail": {
    "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/transactions", {
  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({
    "paymentRequest": {
      "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"
    },
    "paymentDetail": {
      "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",
    "Idempotency-Key": "string",
    "X-Correlation-ID": "00000000-0000-0000-0000-000000000000",
}

payload = {
    "paymentRequest": {
        "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",
    },
    "paymentDetail": {
        "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/transactions",
    headers=headers,
    json=payload,
)

Response

{
  "payment": {
    "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"
  },
  "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"
  },
  "requiredAction": {
    "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"
  }
}