Ozow Hub

Payouts API errors

Every rejection the Payouts API can return, and what to do about it.

On this page40 sections
Build with AI 1 package

A build package is every page for one task, with the API operations they use. Copy the prompt into a coding assistant, or hand it the package itself: slim links to each page, full inlines all of them in one document.

  • Send a payoutEverything needed to pay money out to a customer's bank account or voucher with the Payouts API, including how to exercise the failure paths before going live.
    View package

A rejected payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. 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 codeSite code The unique code for a site registered under a merchant. A site is a place to transact: a website, or a branch of a store. A merchant can have several, and each transaction names the one it belongs to, so sending the wrong code files the payment against the wrong place. 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 codeSite code The unique code for a site registered under a merchant. A site is a place to transact: a website, or a branch of a store. A merchant can have several, and each transaction names the one it belongs to, so sending the wrong code files the payment against the wrong place. resolves to a merchant.

What to do

Check the site codeSite code The unique code for a site registered under a merchant. A site is a place to transact: a website, or a branch of a store. A merchant can have several, and each transaction names the one it belongs to, so sending the wrong code files the payment against the wrong place.. 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 codeSite code The unique code for a site registered under a merchant. A site is a place to transact: a website, or a branch of a store. A merchant can have several, and each transaction names the one it belongs to, so sending the wrong code files the payment against the wrong place.. 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 codeSite code The unique code for a site registered under a merchant. A site is a place to transact: a website, or a branch of a store. A merchant can have several, and each transaction names the one it belongs to, so sending the wrong code files the payment against the wrong place. you authorised with is the one this payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. is for.

What to do

Send the payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. 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 payoutsPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. at all.

What to do

Nothing in the request will fix this. Contact support@ozow.com to have payoutsPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. enabled.

Please contact support to enable payout settings for your merchant profile

What was checked

Whether the account has payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. 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 payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. 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 floatFloat The balance held with Ozow that payouts and refunds are paid out of. Both draw on it, and neither will process while it is empty. Payins do not need one, so if you only take payments you never meet it.. PayoutsPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. are funded from it rather than from a payment.

What to do

Contact support@ozow.com to have a floatFloat The balance held with Ozow that payouts and refunds are paid out of. Both draw on it, and neither will process while it is empty. Payins do not need one, so if you only take payments you never meet it. created for this site.

Amount

Reaching this means site and account all passed.

Site code not found

What was checked

Whether the site's payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. limits could be read. The site codeSite code The unique code for a site registered under a merchant. A site is a place to transact: a website, or a branch of a store. A merchant can have several, and each transaction names the one it belongs to, so sending the wrong code files the payment against the wrong place. did not resolve at this point.

What to do

Check the site codeSite code The unique code for a site registered under a merchant. A site is a place to transact: a website, or a branch of a store. A merchant can have several, and each transaction names the one it belongs to, so sending the wrong code files the payment against the wrong place..

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 payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. 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 payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first., or send it by RTCReal-Time Clearing Payments that clear immediately rather than waiting for a batch. A batch run settles at set times through the day; a Real-Time Clearing payment moves the funds between the two bank accounts as it is made, so the recipient can rely on them straight away.PayInc if the bank supports it.

Insufficient float balance

What was checked

Whether the site's floatFloat The balance held with Ozow that payouts and refunds are paid out of. Both draw on it, and neither will process while it is empty. Payins do not need one, so if you only take payments you never meet it. covers the payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first.. Payouts are paid from the float, not from incoming payments.

What to do

Top up the floatFloat The balance held with Ozow that payouts and refunds are paid out of. Both draw on it, and neither will process while it is empty. Payins do not need one, so if you only take payments you never meet it.. See 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 payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. 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.

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 codeBranch code The six-digit number identifying a South African bank branch, the equivalent of a sort code or a routing number elsewhere. Each bank publishes one universal branch code that works for every account it holds, which is the one to use unless you have been given another. was sent with the banking details.

What to do

Send branchCode, which is the bank's universal branch codeBranch code The six-digit number identifying a South African bank branch, the equivalent of a sort code or a routing number elsewhere. Each bank publishes one universal branch code that works for every account it holds, which is the one to use unless you have been given another..

Voucher payout should only use cellphone number

What was checked

Whether a voucher payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. 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 payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first..

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

What was checked

The account number and branch codeBranch code The six-digit number identifying a South African bank branch, the equivalent of a sort code or a routing number elsewhere. Each bank publishes one universal branch code that works for every account it holds, which is the one to use unless you have been given another. 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 payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. asks for RTCReal-Time Clearing Payments that clear immediately rather than waiting for a batch. A batch run settles at set times through the day; a Real-Time Clearing payment moves the funds between the two bank accounts as it is made, so the recipient can rely on them straight away.PayInc.

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 payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. without RTCReal-Time Clearing Payments that clear immediately rather than waiting for a batch. A batch run settles at set times through the day; a Real-Time Clearing payment moves the funds between the two bank accounts as it is made, so the recipient can rely on them straight away.PayInc, or to a bank that participates.

RTC is not supported in the testing environment

What was checked

Nothing. Staging does not clearClearing Moving funds between two banks so the recipient can rely on them. It is a separate step from a payment being approved: a payment can succeed and the money still be in transit. Real-Time Clearing is the immediate version. in real time.

What to do

Send isRtc as false when testing. The same payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. 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 payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. 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.

Payment to identity

Only reached when the payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. 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 payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. is RTCReal-Time Clearing Payments that clear immediately rather than waiting for a batch. A batch run settles at set times through the day; a Real-Time Clearing payment moves the funds between the two bank accounts as it is made, so the recipient can rely on them straight away.PayInc. Paying to an identity resolves an account in real time, so it cannot be done on a batched payout.

What to do

Send the payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. as RTCReal-Time Clearing Payments that clear immediately rather than waiting for a batch. A batch run settles at set times through the day; a Real-Time Clearing payment moves the funds between the two bank accounts as it is made, so the recipient can rely on them straight away.PayInc, 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 payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. 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 payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first..

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 payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. was accepted and could not be sent on.

What to do

Retry. Check the payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first.'s status before retrying, so a payout that did go through is not sent twice.