Bank Account Verification

POST /bankaccount/verify

Try it

Parameters

X-Correlation-IDheaderIdempotency-Keyheader

Bodyapplication/json

siteCode*reference*region*accountNumber*branchCode*accountType*identification.type*identification.country*identification.identifier*surname*initialsmobileemail

Request sampleLanguage

curl -X POST 'https://one.ozow.com/v1/bankaccount/verify' \
  -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 '{
  "siteCode": "TSTSTE0001",
  "reference": "string",
  "region": "ZA",
  "accountNumber": "string",
  "branchCode": "string",
  "accountType": "cheque",
  "identification": {
    "type": "said",
    "country": "ZA",
    "identifier": "0000000000000"
  },
  "surname": "string",
  "initials": "string",
  "mobile": "+27821234567",
  "email": "merchant@example.com"
}'

Response exampleStatus

{
  "reference": "<reference>",
  "accountFound": true,
  "accountOpen": true,
  "account3Months": true,
  "acceptCredits": true,
  "acceptDebits": true,
  "accountTypeMatched": true,
  "identificationMatched": true,
  "surnameMatched": true,
  "initialsMatched": true,
  "mobileMatched": true,
  "emailMatched": true
}

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

POSThttps://one.ozow.com/v1/bankaccount/verifyProduction

Confirm a bank account exists, can accept credits, and matches the identity supplied. Charged, and must be enabled for the merchant.

Authentication

OAuth 2.0
scopespayments

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

siteCode string required
The site code of the merchant site for which this request is being performed.
max length50
reference string required
A reference to uniquely identify this bank account verification request.
max length50
region string required
The applicable region identifer in ISO 3166-Alpha-2 format.
min length2max length2
accountNumber string required
The bank account number to be verified.
branchCode string required
The branch code of the bank account to be verified.
max length6
accountType string required
The account type of the bank account.
values"cheque""savings""transmission""bond"
identification Identification required
The identification of the owner of the bank account.
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
surname string required
The surname of the owner of the bank account.
initials string
Optional initials of the owner of the bank account.
max length5
mobile string
Optional mobile number of the owner of the bank account.
max length15
email string email
Optional email address of the owner of the bank account.
max length255

Responses

200 OK

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

reference string required
The reference of this bank account verification request.
max length50
accountFound boolean required
Whether or not the account was found.
accountOpen boolean required
Whether or not the account is currently open.
account3Months boolean required
Whether or not the account has been open for more than 3 months.
acceptCredits boolean required
Whether or not the account can accept credits.
acceptDebits boolean required
Whether or not the account can accept debits.
accountTypeMatched boolean required
Whether or not the account type matches the supplied account type.
identificationMatched boolean required
Whether or not the identification supplied matches the account owner on record.
surnameMatched boolean required
Whether or not the surname matches the account owner surname on record.
initialsMatched boolean required
Whether or not the initial matches the account owner initials on record.
mobileMatched boolean required
Whether or not the mobile matches the account owner mobile on record.
emailMatched boolean required
Whether or not the email matches the account owner email on record.

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/bankaccount/verify' \
  -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 '{
  "siteCode": "TSTSTE0001",
  "reference": "<reference>",
  "region": "ZA",
  "accountNumber": "<accountNumber>",
  "branchCode": "<branchCode>",
  "accountType": "cheque",
  "identification": {
    "type": "said",
    "country": "ZA",
    "identifier": "0000000000000"
  },
  "surname": "<surname>",
  "initials": "<initials>",
  "mobile": "+27821234567",
  "email": "merchant@example.com"
}'

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://one.ozow.com/v1/bankaccount/verify");
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(@"{
  ""siteCode"": ""TSTSTE0001"",
  ""reference"": ""<reference>"",
  ""region"": ""ZA"",
  ""accountNumber"": ""<accountNumber>"",
  ""branchCode"": ""<branchCode>"",
  ""accountType"": ""cheque"",
  ""identification"": {
    ""type"": ""said"",
    ""country"": ""ZA"",
    ""identifier"": ""0000000000000""
  },
  ""surname"": ""<surname>"",
  ""initials"": ""<initials>"",
  ""mobile"": ""+27821234567"",
  ""email"": ""merchant@example.com""
}", 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/bankaccount/verify',
    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'
{
  "siteCode": "TSTSTE0001",
  "reference": "<reference>",
  "region": "ZA",
  "accountNumber": "<accountNumber>",
  "branchCode": "<branchCode>",
  "accountType": "cheque",
  "identification": {
    "type": "said",
    "country": "ZA",
    "identifier": "0000000000000"
  },
  "surname": "<surname>",
  "initials": "<initials>",
  "mobile": "+27821234567",
  "email": "merchant@example.com"
}
JSON,
]);

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

const response = await fetch("https://one.ozow.com/v1/bankaccount/verify", {
  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({
    "siteCode": "TSTSTE0001",
    "reference": "<reference>",
    "region": "ZA",
    "accountNumber": "<accountNumber>",
    "branchCode": "<branchCode>",
    "accountType": "cheque",
    "identification": {
      "type": "said",
      "country": "ZA",
      "identifier": "0000000000000"
    },
    "surname": "<surname>",
    "initials": "<initials>",
    "mobile": "+27821234567",
    "email": "merchant@example.com"
  }),
});

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 = {
    "siteCode": "TSTSTE0001",
    "reference": "<reference>",
    "region": "ZA",
    "accountNumber": "<accountNumber>",
    "branchCode": "<branchCode>",
    "accountType": "cheque",
    "identification": {
        "type": "said",
        "country": "ZA",
        "identifier": "0000000000000",
    },
    "surname": "<surname>",
    "initials": "<initials>",
    "mobile": "+27821234567",
    "email": "merchant@example.com",
}

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

Response

{
  "reference": "<reference>",
  "accountFound": true,
  "accountOpen": true,
  "account3Months": true,
  "acceptCredits": true,
  "acceptDebits": true,
  "accountTypeMatched": true,
  "identificationMatched": true,
  "surnameMatched": true,
  "initialsMatched": true,
  "mobileMatched": true,
  "emailMatched": true
}

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

Created

{
  "reference": "<reference>",
  "accountFound": true,
  "accountOpen": true,
  "account3Months": true,
  "acceptCredits": true,
  "acceptDebits": true,
  "accountTypeMatched": true,
  "identificationMatched": true,
  "surnameMatched": true,
  "initialsMatched": true,
  "mobileMatched": true,
  "emailMatched": 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"
  }
}