# Payments API errors

> Every rejection Payments API returns, what was checked, and what to do about it. Source: https://hub.ozow.com/errors/payments-api/

Most rejections are an HTTP 200 with a null `url` and the reason in `errorMessage`. Check that field rather than the status code. The exceptions are the authorisation failures below, which do carry a status.

## Authorisation

Runs before anything else, on every endpoint that takes an API key. These are the only rejections here that carry a status code.

### API key is missing or invalid.

Arrives as HTTP 401 Unauthorized.

**What was checked:** Whether the request carried an `ApiKey` header at all.

**What to do:** Send your API key in an `ApiKey` header. It is not a bearer token and does not go in `Authorization`.

### Site code is missing.

Arrives as HTTP 401 Unauthorized.

**What was checked:** Whether a site code could be found, in the request body, a `siteCode` parameter, a `SiteCode` header or the query string.

**What to do:** Send `siteCode` in the request body.

### API key is invalid.

Arrives as HTTP 401 Unauthorized.

**What was checked:** Whether the API key belongs to the site you specified. The key is matched against that site's key, not merely checked for existence.

**What to do:** Use the API key issued for this site code, and check you are not using staging credentials against production or the reverse.

### Unable to authorize site code {siteCode}.

Arrives as HTTP 403 Forbidden.

**What was checked:** Whether the site code resolves to a site that is active.

**What to do:** Check the site code. If it is right and this persists, the site may be deactivated: contact support@ozow.com.

### Authorization service unavailable.

Arrives as HTTP 500 Internal Server Error.

**What was checked:** Nothing. The failure is on Ozow's side, not in your request.

**What to do:** Retry. If it continues, contact support@ozow.com.

## Merchant site

The first check on the request itself.

Reaching this means authorisation all passed.

### There is no active merchantSite that exists with Site Code: '{siteCode}'

**What was checked:** Whether the site code resolves to an active site.

**What to do:** Check the site code. Over the API you would normally see the authorisation failure above instead, so reaching this one means the request did not come through the API key path.

This message is being reworded. It names something internal to Ozow rather than anything the caller sent, and it is quoted here so that it can be found from the string itself.

## Merchant

Reached only when the site code resolved, so seeing this means the site code itself is correct.

Reaching this means authorisation, merchant site all passed.

### There is no active merchant that exists with Site Code: '{siteCode}'

**What was checked:** Whether the account that owns the site is active. The site was found; the merchant behind it was not.

**What to do:** Nothing in the request will fix this. Contact support@ozow.com about the account.

This message is being reworded. It names something internal to Ozow rather than anything the caller sent, and it is quoted here so that it can be found from the string itself.

## Third party provider

Reaching this means authorisation, merchant site, merchant all passed.

### The Third Party providerId is invalid

**What was checked:** Whether the `thirdProviderId` you sent is one Ozow knows.

**What to do:** Omit the field unless Ozow has given you a provider identifier.

## Transaction reference

Reaching this means authorisation, merchant site, merchant, third party provider all passed.

### Transaction reference missing

**What was checked:** Whether `transactionReference` was sent.

**What to do:** Send your own reference for the payment. It is how you match the notification back to an order.

## Duplicate transaction reference

Reaching this means authorisation, merchant site, merchant, third party provider, transaction reference all passed.

### Duplicate transaction reference not allowed.

**What was checked:** Whether this site has used the reference in the last 24 hours.

**What to do:** Use a new reference for each attempt. Retrying a failed payment needs a fresh one rather than the original.

## Bank reference

Reaching this means authorisation, merchant site, merchant, third party provider, transaction reference, duplicate transaction reference all passed.

### Bank reference missing

**What was checked:** Whether `bankReference` was sent.

**What to do:** Send the reference the payer will see on their bank statement.

## Transaction amount

Four limits apply in turn: the absolute floor, the currency's ceiling, and the minimum and maximum configured on your site.

Reaching this means authorisation, merchant site, merchant, third party provider, transaction reference, duplicate transaction reference, bank reference all passed.

### Transaction amount cannot be less than 0.01

**What was checked:** Whether the amount is at least one cent.

**What to do:** Send an amount of 0.01 or more.

### Transaction amount exceeds Currency maximum amount allowed

**What was checked:** The ceiling for the currency, which applies to every merchant.

**What to do:** Split the payment, or contact support@ozow.com.

### The amount is less than the minimum amount

**What was checked:** The minimum configured for your site.

**What to do:** Send more, or contact support@ozow.com to have the minimum changed.

### The amount is more than the maximum amount

**What was checked:** The maximum configured for your site.

**What to do:** Send less, or contact support@ozow.com to have the maximum changed.

### Merchant has a minimum transaction amount of {amount}

**What was checked:** The same minimum, reported with the figure.

**What to do:** Send at least the amount named in the message.

### Merchant has a maximum transaction amount of {amount}

**What was checked:** The same maximum, reported with the figure.

**What to do:** Send no more than the amount named in the message.

## Country and currency

The only stage that can report more than one problem at once, because the country and the currency are checked independently before they are checked against each other.

Reaching this means authorisation, merchant site, merchant, third party provider, transaction reference, duplicate transaction reference, bank reference, transaction amount all passed.

### Invalid country code

**What was checked:** Whether the country code is one Ozow has, and is active.

**What to do:** Send an ISO 3166-1 alpha-2 code. South Africa is `ZA`, which is the only country Ozow supports today.

### Country provided not available

**What was checked:** The same lookup, where the country exists and is deactivated.

**What to do:** Send `ZA`.

### Unsupported currency code

**What was checked:** Whether the currency code is one Ozow has, and is active.

**What to do:** Send an ISO 4217 code. South African rand is `ZAR`.

### Currency provided not available

**What was checked:** The same lookup, where the currency exists and is deactivated.

**What to do:** Send `ZAR`.

### This country code is not supported by the merchant

**What was checked:** Whether the country you sent is the country your account is registered in.

**What to do:** Send the country your account was onboarded in.

### This currency is not supported for the merchant's country

**What was checked:** Whether the currency belongs to your account's country. A South African account sends `ZAR`.

**What to do:** Send the currency of your account's country.

### This request currency is not allowed for this country

**What was checked:** The same pairing, from the country's side.

**What to do:** Send the currency of the country you specified.

## Banking details

Only reached when you send banking details in the request, which most integrations do not.

Reaching this means authorisation, merchant site, merchant, third party provider, transaction reference, duplicate transaction reference, bank reference, transaction amount, country and currency all passed.

### Merchant has not been activated for dynamic banking details

**What was checked:** Whether your account may send `bankId`, `bankAccountNumber`, `branchCode` or `bankAccountName` on a request.

**What to do:** Remove those fields and let the payer choose their bank, or contact support@ozow.com to have the account enabled.

### When passing banking details, the following fields are required: BankAccount, BranchCode, BeneficiaryBankName and BankId

**What was checked:** Whether all four arrived. Banking details are all or nothing.

**What to do:** Send all four, or none of them.

### Invalid bank ID

**What was checked:** Whether `bankId` is an identifier Ozow issues.

**What to do:** See [Payment method identifiers](/integration-methods/apis/payin/payment-method-ids/).

### Invalid bank account number

**What was checked:** The account number's format.

**What to do:** Send digits only, with no spaces or punctuation.

### Invalid branch code

**What was checked:** The branch code's format.

**What to do:** Send the universal branch code for the bank.

### Beneficiary bank name contains invalid characters.  Only alphanumeric characters and spaces are allowed

**What was checked:** The characters in the beneficiary bank name.

**What to do:** Remove punctuation and symbols from the name.

## Variable amount

Only reached when `allowVariableAmount` is true, which lets the payer choose what to pay.

Reaching this means authorisation, merchant site, merchant, third party provider, transaction reference, duplicate transaction reference, bank reference, transaction amount, country and currency, banking details all passed.

### The _merchantSite is not set to allow variable amounts

**What was checked:** Whether your site may accept a payment where the payer chooses the amount.

**What to do:** Remove `allowVariableAmount`, or contact support@ozow.com to have variable amounts enabled on this site.

This message is being reworded. It names something internal to Ozow rather than anything the caller sent, and it is quoted here so that it can be found from the string itself.

### The request minimum is less than the site minimum

**What was checked:** Whether `variableAmountMin` is at or above the minimum configured for your site.

**What to do:** Raise `variableAmountMin`, or have the site minimum lowered.

### The request maximum is more than the site maximum

**What was checked:** Whether `variableAmountMax` is at or below the maximum configured for your site.

**What to do:** Lower `variableAmountMax`, or have the site maximum raised.

## API access

Reaching this means authorisation, merchant site, merchant, third party provider, transaction reference, duplicate transaction reference, bank reference, transaction amount, country and currency, banking details, variable amount all passed.

### Merchant is not allowed to perform API transactions

**What was checked:** Whether your account may create payments over the API rather than only from the dashboard.

**What to do:** Nothing in the request will fix this. Contact support@ozow.com to have API access enabled.

## Banks

Reaching this means authorisation, merchant site, merchant, third party provider, transaction reference, duplicate transaction reference, bank reference, transaction amount, country and currency, banking details, variable amount, api access all passed.

### No banks found using country code {countryCode}

**What was checked:** Whether any bank is available for the country you specified.

**What to do:** Check the country code. If it is right, contact support@ozow.com.

## Hash check

The last check, which is worth knowing: reaching it means everything above was accepted, so a hash failure is never a symptom of a wrong site code, amount, currency or bank.

Reaching this means authorisation, merchant site, merchant, third party provider, transaction reference, duplicate transaction reference, bank reference, transaction amount, country and currency, banking details, variable amount, api access, banks all passed.

### The HashCheck value has failed

**What was checked:** Whether the `hashCheck` you sent matches the one Ozow computes from your request and your private key.

**What to do:** Concatenate the fields in the documented order, append your private key, lowercase the whole string and take its SHA512. The usual causes are the field order, an amount without two decimal places, and including a field that should be left out.

See [Generate the hash check](/integration-methods/apis/deprecated-integrations/redirect-to-ozow/#step-1-generate-the-hash-check).

See [Hash calculator](/integration-methods/apis/deprecated-integrations/hash-calculator/).