Troubleshooting

Common issues and how to resolve them. If your problem is not covered here, check the Support page.

​

Authentication Errors

​

401 Unauthorized

Symptom: The API returns 401 with an empty body. curl -s prints nothing, and in JavaScript res.json() throws a parse error. Check the HTTP status before parsing the body. What to check:

1. Verify you are sending the API key in the X-Api-Key header: X-Api-Key: your-key-here
2. Confirm the API key is active. Use the Validate API Key endpoint to test.

​

403 “The user cannot make Live operations”

Symptom: Starting a Payments Library session with mode set to LIVE returns 403 with this message. Cause: The API key belongs to a sandbox account. Sandbox and live are separate Orchestra accounts, and a sandbox account can only run test transactions. Use the API key of your live account. See Testing & Going Live.

​

409 Conflict on credential operations

Symptom: Storing or updating a Payment Gateway Account returns 409. What to check:

1. The paymentGatewayAccountName may already exist. List your accounts with List Payment Gateway Accounts to confirm.
2. If you intend to replace existing credentials, the PUT endpoint overwrites by design. Ensure you are sending the full credential set.

​

429 Too Many Requests

Cause: Your account has reached the usage limit of its plan for the current period. The limit applies to the whole account, not to a single user or API key. What to do: Check your usage in the portal under Operations > Usage. To raise the limit, contact support.

​

Transaction Failures

​

Transaction returns “Rejected”

Symptom: A charge or authorization returns a Rejected status. What to check:

1. Read the gatewayResultDescription and gatewayResultSubDescription fields in the response. These contain the gateway’s reason for the rejection (e.g., insufficient funds, invalid card, do-not-honor).
2. If using test cards, confirm you are using the mock PSPs or the gateway’s own sandbox credentials.
3. Check Gateway-Specific Requirements for the gateway you are using. Some gateways require specific parameters (e.g., AMEX requires myRef with 6+ characters).

​

Transaction times out

Symptom: The API call takes too long and times out, or returns a timeout error. What to do:

1. Do not retry the charge immediately. The original transaction may still be processing at the gateway.
2. Use the Transaction Status endpoint with the refTransId from your original request to check the outcome.
3. Only retry after confirming the original transaction failed.

See the timeout handling pattern for a complete code example.

​

Payment succeeded on a backup gateway

Symptom: You sent fallback accounts and the payment succeeded, but not on your primary gateway. What to do: With fallback accounts, the response comes from the gateway that processed the payment. Check gatewayName and gatewayReference, and send any capture, void or refund to that account. See Which Gateway Processed the Payment.

​

Gateway returns “FatalFailure”

Symptom: Transaction returns FatalFailure status. What to check:

1. This typically means the gateway configuration is wrong (invalid credentials, disabled account, unsupported operation).
2. Verify your gateway credentials are correct using List Payment Gateway Accounts.
3. Confirm the gateway supports the operation you are attempting. For example, AMEX does not support direct Charge or Refund operations (use PreAuth + Capture instead).
4. If using multi-gateway failover, Orchestra automatically tries the next gateway in your list.

​

Gateway-Specific Issues

​

AMEX: “Bad Data” on charge

AMEX requires the myRef parameter with at least 6 characters. Only the first 6 characters are used as the trace number.

​

Pesopay: duplicate transaction error

Pesopay requires myRef to be unique per transaction. Reusing a reference value causes a rejection.

​

First Data / Gateline: connection refused

These gateways require a client certificate for authentication. Verify that paymentGatewayCertName is set and the certificate is configured in your account.

​

Adyen: unexpected test/live behavior

The ShopperInteraction credential defaults to Ecommerce. Keep it set to Ecommerce, including when your Adyen merchant account is also used for point-of-sale. For the full list of gateway-specific requirements, see Gateway-Specific Requirements.

​

Card and Token Issues

​

Invalid card number

Symptom: Tokenization fails with a card validation error. What to check:

1. The card number must pass the Luhn algorithm. Use the Luhn Validation tool to verify.
2. Card number must be 12-19 digits with no spaces or separators.
3. Use the Brand Lookup tool to confirm the card brand is supported by your gateway.

​

Token not found

Symptom: A string token operation returns 404. What to check:

1. String tokens persist until you delete them; a 404 means the token ID is wrong, not expired.
2. Confirm the token ID is correct and belongs to the authenticated API key.

​

Payments Library Issues

​

Session token invalid

Symptom: Library operations fail with “Session token is invalid.” What to check:

1. Session tokens are single-use. A new session must be created for each payment attempt.
2. Ensure the Authorization: Bearer <token> header is set correctly in library API calls.
3. Verify the session was created with the correct mode (LIVE vs TEST). Sandbox accounts cannot create LIVE sessions.

​

3D Secure not triggering

What to check:

1. The mock PSPs support 3D Secure, with the exception of the OTP mock. If you are testing against the OTP mock, switch to another mock or to a real gateway’s sandbox credentials.
2. Ensure your gateway account has 3DS enabled on the gateway’s side.
3. The Payments Library handles 3DS automatically when the gateway requires it. If you are using the REST API directly, see the 3D Secure guide.

​

3D Secure fails with “An unexpected error occurred”

Symptom: Transactions on a CardPay eWallet account with Perform 3Ds? enabled fail, and the gateway returns no response. What to check:

1. Most often this means the account has 3DS enabled but no 3DS merchant details. Open the CardPay eWallet account in the portal and confirm that I Have 3DS Merchant Details is ticked, that Merchant Requestor Id Suffix and Merchant Url are filled in, and that the table below contains a row for each card brand you process.
2. Orchestra has no default 3DS merchant, so 3DS enabled with missing details always fails. See 3DS Merchant Details for what to request from your PSP or acquirer.
3. If the details are present, confirm the acquirer BIN and MID are the ones your acquiring bank issued for 3D Secure, not your PSP API credentials.

​

Scheduled Payments Issues

​

Contract is Active but no payment ran

What to check: Check that the template’s payment gateway account, and its client certificate if one is set, still exist. A contract whose template account or certificate is missing is skipped.

​

Contract stopped advancing

What to check: Check the contract’s status. Paused, Cancelled and Completed contracts do not run. See Scheduled Payments.

​

Debugging Tips

​

Include myRef in every request

Set a unique myRef value on every transaction. This makes it easy to trace transactions in gateway dashboards and when contacting support.

​

Check the response body

Orchestra returns the gateway’s own response in gatewayResultDescription and gatewayResultSubDescription. These fields contain the most specific error information and are the first place to look when a transaction fails.

​

Test with mock PSPs first

The mock PSPs let you test your integration without external gateway accounts. They support Charge, PreAuth, Capture, Refund, and Void operations with predictable responses.

​

Contact support with context

When reaching out to support, include:

• Your myRef value and refTransId
• The full API response (including gatewayResultDescription)
• The gateway name and operation type
• Whether you are using test or production credentials

​

Related