# Payouts API errors

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

A rejected payout is an HTTP 200. The reason is in `payoutStatus.errorMessage` and there is no `payoutId`. Treat a payout as accepted only when `payoutId` is populated.

## Site and account

Before any of the request is looked at. These are about the site code you authorised with and what the account behind it may do.

### Request Denied: Could not retrieve merchant details for this site code

**What was checked:** Whether the site code resolves to a merchant.

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

### Request Denied: Could not retrieve active site details for this site code

**What was checked:** Whether the site behind that code is active.

**What to do:** Check the site code. The site may be deactivated: contact support@ozow.com.

### Request Denied: SiteCode provided during authorization is not authorized for this request

**What was checked:** Whether the site code you authorised with is the one this payout is for.

**What to do:** Send the payout against the site whose credentials you used. They have to be the same site.

### Request Denied: Merchant is not configured for Payouts

**What was checked:** Whether the account may send payouts at all.

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

### Please contact support to enable payout settings for your merchant profile

**What was checked:** Whether the account has payout settings configured.

**What to do:** Contact support@ozow.com, as the message says.

### Please contact support to enable payouts for your merchant profile

**What was checked:** Whether a payout provider is set up for the account.

**What to do:** Contact support@ozow.com.

### Merchant site does not have an existing float, Please contact support to enable a float for your merchant or site

**What was checked:** Whether the site has a float. Payouts are funded from it rather than from a payment.

**What to do:** Contact support@ozow.com to have a float created for this site.

## Amount

Reaching this means site and account all passed.

### Site code not found

**What was checked:** Whether the site's payout limits could be read. The site code did not resolve at this point.

**What to do:** Check the site code.

### Payout amount below minimum amount

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

**What to do:** Send more, or contact support@ozow.com to have it lowered.

### Payout amount exceeds maximum amount

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

**What to do:** Send less, or contact support@ozow.com to have it raised.

### Payout amount can only have up to 2 decimal places

**What was checked:** The precision of the amount. A payout is money, so a third decimal is not rounded, it is refused.

**What to do:** Round to two decimal places before sending.

### Payout amount exceeds maximum Bank EFT transaction amount limit

**What was checked:** The destination bank's own ceiling, which is not yours and not Ozow's.

**What to do:** Split the payout, or send it by RTC if the bank supports it.

### Insufficient float balance

**What was checked:** Whether the site's float covers the payout. Payouts are paid from the float, not from incoming payments.

**What to do:** Top up the float. See [Float top-up](/payment-products/settlements-and-float/float-top-up/).

## Banking details

Reaching this means site and account, amount all passed.

### You need to provide Banking Details or Identity Number to request a payout

**What was checked:** Whether the payout says where the money goes: an account, or an identity number for a verified lookup.

**What to do:** Send banking details, or an identity number.

### BankGroupId is required

**What was checked:** Whether the destination bank was named.

**What to do:** Send `bankGroupId`. The available banks come from [Get available banks](openapi:payouts-api#operation/get-getavailablebanks).

### Account number is required

**What was checked:** Whether an account number was sent with the banking details.

**What to do:** Send `accountNumber` alongside the bank and branch.

### Branch code is required

**What was checked:** Whether a branch code was sent with the banking details.

**What to do:** Send `branchCode`, which is the bank's universal branch code.

### Voucher payout should only use cellphone number

**What was checked:** Whether a voucher payout carried banking details. A voucher is collected with a phone and a pin, so an account number has no meaning on one.

**What to do:** Send only the cellphone number for a voucher payout.

### The details provided did not meet the banking validation , cannot accept payout request

**What was checked:** The account number and branch code against the bank, which is a real check rather than a format one.

**What to do:** Confirm the account details with the recipient. An account that does not exist at that branch fails here.

## Real-time clearing

Only reached when the payout asks for RTC.

Reaching this means site and account, amount, banking details all passed.

### Destination Bank is not RTC Participant

**What was checked:** Whether the destination bank settles in real time.

**What to do:** Send the payout without RTC, or to a bank that participates.

### RTC is not supported in the testing environment

**What was checked:** Nothing. Staging does not clear in real time.

**What to do:** Send `isRtc` as false when testing. The same payout works in production.

## Hash check

Anything you see after this means your hash was accepted.

Reaching this means site and account, amount, banking details, real-time clearing all passed.

### The Hash provided is not valid, cannot accept payout request

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

**What to do:** The amount goes in as cents rather than with decimals, and the fourth field is the customer bank reference.

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

## Payment to identity

Only reached when the payout names a person rather than an account.

Reaching this means site and account, amount, banking details, real-time clearing, hash check all passed.

### PaymentToId: IdentityNumber is required

**What was checked:** Whether an identity number came with the identity type.

**What to do:** Send both, or neither.

### PaymentToId: IdentityType is required

**What was checked:** Whether an identity type came with the identity number.

**What to do:** Send both, or neither.

### PaymentToId: IdentityType is unknown {identityType}

**What was checked:** Whether the identity type is one Ozow accepts.

**What to do:** Send a type Ozow recognises. A South African ID is the usual one.

### PaymentToId: Only supported for RTC transactions

**What was checked:** Whether the payout is RTC. Paying to an identity resolves an account in real time, so it cannot be done on a batched payout.

**What to do:** Send the payout as RTC, or send banking details instead.

## Duplicate

Reaching this means site and account, amount, banking details, real-time clearing, hash check, payment to identity all passed.

### Duplicate Payout found

**What was checked:** Whether this site has already sent a payout with the same details.

**What to do:** Use a new merchant reference. If the original really did fail, check its status before resending rather than resending blind.

## References

Reaching this means site and account, amount, banking details, real-time clearing, hash check, payment to identity, duplicate all passed.

### MerchantReference Cannot be null and cannot exceed 50 characters

**What was checked:** The reference you use to identify the payout.

**What to do:** Send one, of 50 characters or fewer.

### CustomerBankReference Cannot be null and cannot exceed 20 characters

**What was checked:** The reference the recipient sees on their statement, which their bank limits to 20 characters.

**What to do:** Send one, of 20 characters or fewer.

### {field} contains invalid characters: {characters}

**What was checked:** The characters in a reference. A bank rejects a payment instruction carrying any of them, so Ozow refuses it first.

**What to do:** Remove them. The message names the ones it found, and the full set is the ampersand, apostrophe, backslash, double quote, forward slash, percent and semicolon.

## Sending it on

Past every check. Nothing about the request was wrong, and the failure came after Ozow accepted it.

Reaching this means site and account, amount, banking details, real-time clearing, hash check, payment to identity, duplicate, references all passed.

### Oops! We are not able to process your payout request at the moment due to a technical error. Please try again later.

**What was checked:** Nothing. The payout was accepted and could not be sent on.

**What to do:** Retry. Check the payout's status before retrying, so a payout that did go through is not sent twice.