200 - Success Response With a Failed Transaction (HPP Invoices Only)

In specific scenarios, particularly with Hosted Payment Page (HPP) invoice flows, the API might return a 200 OK response even though the subsequent transaction is expected to fail. When this occurs, the hppUrl returned in the response will include /transaction-failed:

https://hpp.getorbital.io/payment/deposit/transaction-failed

This indicates that while the invoice itself was successfully created, the payer will be directed to a failure screen if they attempt to proceed with the payment.

Causes:

You've included an unsupported or disallowed currency for your account.
You provided a targetAmount without setting a validtargetCurrency, or vice versa.
Required Travel Rule fields (such as firstName, registeredName, or identificationType) are missing.

What to Do:

Carefully review the request parameters to ensure you are only using accepted values and supported currencies.
If your account requires Travel Rule compliance (e.g., for EU payers), ensure that all required identity fields are filled in correctly.

📘
This particular scenario is exclusive to HPP invoice flows. While the invoice creation itself is successful, the underlying payment transaction will not be completed.

400 - Validation & Client Errors

These errors occur when the request is malformed, missing required fields, or contains invalid values

Payins - Validation Errors

These are common validation errors you may encounter when creating invoices

Error Message	Cause	Solution
`Missing required field: externalId`	The `externalId` field was omitted.	Add a unique string to the `externalId` field.
`duplicate externalId`	You reused a previously submitted `externalId`.	Generate a new unique `externalId` for every transaction. Do not reuse IDs from previous attempts, even if the previous one failed or timed out.
`The selected currency is invalid.`	You used a value in the `currency` field that isn’t supported.	Check the `currency` parameter and ensure it uses one of the accepted values listed in the parameter description.
`The targetCurrency is not supported.`	The `targetCurrency` value you included is not accepted by the endpoint. This usually happens when you provide a crypto like ETH or BTC, or use a fiat currency that isn't supported	Use only accepted fiat currencies: `USD`, `EUR`, or `GBP` for the `targetCurrency` field.
`The selected cashierCurrency is invalid.`	You passed an invalid or unsupported value for `cashierCurrency`.	Check the `cashierCurrency` parameter in your request and use only accepted display currencies listed in the dropdown for your request.
`The selected mainCurrency is invalid.`	The blockchain network doesn’t match the stable coin.	For `USDT` and `USDC`, make sure your selected network is one of the accepted combinations.
`The currency field is required.`	`currency` was not included in the request.	Always include the `currency` field when you're converting funds. It defines the actual asset being debited from the payer.
`targetCurrency - No correct currency for amount`	This usually appears when: – `targetCurrency` is provided without a matching `targetAmount` `– or`targetAmount`is included without`targetCurrency ` – or both are missing but a conversion is implicitly expected	Always pair `targetCurrency` with `targetAmount`. If you're not doing a conversion, remove both.

Payout - Validation Errors

These are common validation errors you may encounter when initiating a payout/withdrawal.

Error Message / Title	Cause	How to Fix It
`The externalId field is required.`	You didn’t include the `externalId` field in your request. This field uniquely identifies each payout.	Provide a unique `externalId` string in your request body.
`duplicate externalId`	The `externalId` you provided has already been used in a previous payout.	Generate a new unique `externalId` for every transaction. Do not reuse IDs from previous attempts, even if the previous one failed or timed out.
`The address field is required`	You didn’t provide the `address` where the funds should be sent. This field is mandatory.	Include the receiver’s valid crypto wallet address in your request body. This field is mandatory for all payouts.
`Address not valid`	The `address` provided is not a valid wallet address format or doesn't match the expected pattern for the chosen blockchain network.	Verify the wallet `address` format carefully. Ensure it precisely matches the expected pattern for the chosen `targetCurrency` .
`balance too low`	Your merchant wallet doesn't have enough balance in the selected `sourceCurrency` to process the payout.	Top up your account and then retry the payout. Also take note of the minimum transaction amount that applies to each cryptocurrency.
`The selected sourceCurrency is invalid`	The `sourceCurrency` value you provided isn’t supported or is misspelled.	Review the `sourceCurrency` parameter and use only the supported crypto and fiat currencies listed.
`The selected targetCurrency is invalid`	The `targetCurrency` isn’t accepted for payouts, either because it's not supported or because it’s a fiat currency (which isn’t allowed for withdrawals).	`targetCurrency` supports only the cryptocurrencies listed in the parameter description. Fiat currencies are not allowed for payouts.

Travel Rule Validation Errors

These errors indicate issues with mandatory data provided for Travel Rule (TR) compliance.

Error Message / Title	Cause	Solution
`Travel rule validation failed`	One or more required fields are missing or invalid.	Check the `invalidParams` list for the missing fields. Field requirements depend on both the Travel Rule entity (`PPOU` or `PPDL`) and whether the payer is an individual or a corporate.
`identificationType is invalid. Accepted values are: ...`	The value for `identificationType` does not match what’s allowed for the selected combination of PPOU/PPDL and individual/corporate.	Use a valid identification values for the selected entity (PPOU or `PPDL`) and payer type (Individual or Corporate) based on `identificationType` type you choose.
`firstName is required`, `lastName is required`, `registeredName is required......`	Missing required fields for TR	Add the missing required fields listed to ensure your payload is complete.

Binance Identity Validation

Error Message / Title	Cause	Solution
`Payee not found.`	This occurs during Binance payer verification and it indicates that the Binance Pay ID, email, or wallet address is invalid.	Confirm and re-enter a valid Binance Pay ID or email.
`account not found`	This occurs during Binance receiver verification and it indicates that the Binance account ID doesn’t exist.	Ensure the account exists and is associated with the provided ID.

401 – Incorrect API Key Provided

This error indicates that the API key you're using in your request is invalid.

Causes:

Your server’s IP address might not be added to the Allow List under your account settings.
There's a typo or an extra space in the key.
The key you're using has been deleted, deactivated, or expired.

What to do:

Double-check that you're using the correct API key for your specific environment (test vs. live).
Ensure the key is added correctly to the Authorization header of your request.
If you're unsure, generate a new key and update your integration accordingly.

403 - Forbidden

This error indicates that the endpoint path you are trying to access is incorrect or does not exist in the API.

Causes:

Typos in the route (e.g., /crypto/deposit/invoices instead of /crypto/deposit/invoice).
Calling a route that no longer exists or has been removed.

What to do:

Refer to the documentation and verify the exact endpoint path (e.g., /crypto/deposit/invoice).

404 - Bad Request

This error signifies that the server was unable to process your request because it was not well-formed, usually due to syntax errors.

Causes:

Malformed JSON body (e.g., missing commas, brackets, or quotes).
Sending an empty body when the endpoint expects structured input.
Invalid formatting sent by your code or an API client like Postman.

What to do:

Use a JSON validator to check the syntax of your request body.
Ensure your request body is not empty, unless the endpoint explicitly allows it.
Always set the Content-Type header to application/json and send valid JSON.
Review sample payloads in the API documentation and replicate their structure precisely.

500 – Internal Server Error

This means something went wrong on the server side while processing your request. In most cases, this is not a client error, but there are a few common triggers:

Causes:

An externalId that was already used in a previous request was re-submitted.
You’re using a currency that isn’t enabled or allowed for your account.
An unhandled exception or downstream failure occurred during processing.

What to do:

Ensure you're using a unique externalId for each request
Confirm your account is fully configured and approved for the action you're trying to perform
Check that the currency, network, and entity combinations are valid and supported under your account

If the issue persists, contact support with the full request payload and error instance ID to help us investigate further