Payments API errors
Every rejection the Payments API can return, and what to do about it.
On this page50 sections
- Authorisation
- API key is missing or invalid.
- Site code is missing.
- API key is invalid.
- Unable to authorize site code {siteCode}.
- Authorization service unavailable.
- Merchant site
- There is no active merchantSite that exists with Site Code: '{siteCode}'
- Merchant
- There is no active merchant that exists with Site Code: '{siteCode}'
- Third party provider
- The Third Party providerId is invalid
- Transaction reference
- Transaction reference missing
- Duplicate transaction reference
- Duplicate transaction reference not allowed.
- Bank reference
- Bank reference missing
- Transaction amount
- Transaction amount cannot be less than 0.01
- Transaction amount exceeds Currency maximum amount allowed
- The amount is less than the minimum amount
- The amount is more than the maximum amount
- Merchant has a minimum transaction amount of {amount}
- Merchant has a maximum transaction amount of {amount}
- Country and currency
- Invalid country code
- Country provided not available
- Unsupported currency code
- Currency provided not available
- This country code is not supported by the merchant
- This currency is not supported for the merchant's country
- This request currency is not allowed for this country
- Banking details
- Merchant has not been activated for dynamic banking details
- When passing banking details, the following fields are required: BankAccount, BranchCode, BeneficiaryBankName and BankId
- Invalid bank ID
- Invalid bank account number
- Invalid branch code
- Beneficiary bank name contains invalid characters. Only alphanumeric characters and spaces are allowed
- Variable amount
- The _merchantSite is not set to allow variable amounts
- The request minimum is less than the site minimum
- The request maximum is more than the site maximum
- API access
- Merchant is not allowed to perform API transactions
- Banks
- No banks found using country code {countryCode}
- Hash check
- The HashCheck value has failed
Build with AI 4 packages
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.
- Migrate a payin from the Payments API to One APIEverything needed to move an existing redirect payin onto One API, with the legacy guide and its One API counterpart side by side.
- Migrate refunds from the Payments API to One APIEverything needed to move an existing refunds integration onto One API, with the legacy guide and its One API counterpart side by side.
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.
401 Unauthorized
- What was checked
Whether the request carried an
ApiKeyheader at all.- What to do
Send your API key in an
ApiKeyheader. It is not a bearer tokenBearer token An access token sent in theAuthorizationheader asAuthorization: Bearer <token>. Anyone holding the token can use it, which is why it belongs on your server and never in a browser or a mobile app.RFC 6750 and does not go inAuthorization.
Site code is missing.
401 Unauthorized
- What was checked
Whether a 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. could be found, in the request body, a
siteCodeparameter, aSiteCodeheader or the query string.- What to do
Send
siteCodein the request body.
API key is invalid.
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 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., and check you are not using staging credentials against production or the reverse.
Unable to authorize site code {siteCode}.
403 Forbidden
- 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 site that 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.. If it is right and this persists, the site may be deactivated: contact support@ozow.com.
Authorization service unavailable.
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 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 an active site.
- 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.. 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 you sent, and quoting it here is so that you can find this page from it.
Merchant
Reached only when 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. 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 you sent, and quoting it here is so that you can find this page from it.
Third party provider
Reaching this means authorisation, merchant site, merchant all passed.
The Third Party providerId is invalid
- What was checked
Whether the
thirdProviderIdyou 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
transactionReferencewas 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
bankReferencewas 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-2ISO 3166-1 alpha-2 The two-letter country codes published by the International Organization for Standardization, such as
ZAfor South Africa andGBfor the United Kingdom. Always uppercase.Wikipedia code. South Africa isZA, 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 codeISO 4217 The three-letter currency codes, such as
ZARfor the South African rand. Always uppercase.Wikipedia is one Ozow has, and is active.- What to do
Send an ISO 4217ISO 4217 The three-letter currency codes, such as
ZARfor the South African rand. Always uppercase.Wikipedia code. South African randZAR The ISO 4217 code for the South African rand, and the currency every amount on this site is in unless a page says otherwise. Amounts are decimal rand rather than cents, so100.00is one hundred rand. isZAR.
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,branchCodeorbankAccountNameon 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
bankIdis an identifier Ozow issues.- What to do
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 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.'s format.
- What to do
Send the 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. 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 you sent, and quoting it here is so that you can find this page from it.
The request minimum is less than the site minimum
- What was checked
Whether
variableAmountMinis 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
variableAmountMaxis 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 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., 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
hashCheckyou 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 SHA512SHA-512 A hashing algorithm. Ozow uses it to sign the values in a request or a notification so you can tell that they arrived unaltered and came from us. Hashing is one-way: the hash cannot be turned back into what produced it.Wikipedia. The usual causes are the field order, an amount without two decimal places, and including a field that should be left out.