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

​
Authentication Errors

​
401 Unauthorized

Symptom: API returns 401 with “Bad or missing authorization data.” What to check:
  1. Verify the Authorization header uses the APIKEY prefix: Authorization: APIKEY your-key-here
  2. Confirm the API key is active. Use the Validate API Key endpoint to test.
  3. Check whether you are using a test key against the production environment (or vice versa).

​
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.

​
Transaction Failures

​
Transaction returns “Rejected”

Symptom: A charge or authorization returns a Rejected status. What to check:
  1. Read the GatewayDescription and AcquirerDescription 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 transactionId 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.

​
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. For POS integrations, set this explicitly in your Payment Gateway Account credentials. 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 are deleted after retrieval by default. If you need to retrieve a token multiple times, store it with the appropriate retention setting.
  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. Mock PSPs do not support 3D Secure. You must use a real gateway’s sandbox credentials for 3DS testing.
  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.

​
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 GatewayDescription and AcquirerDescription. 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.
Mock PSPs do not support 3D Secure, gateway tokenization, or real card validation. Graduate to a real gateway sandbox for testing these features.

​
Contact support with context

When reaching out to support, include:
  • Your myRef value and transactionId
  • The full API response (including GatewayDescription)
  • The gateway name and operation type
  • Whether you are using test or production credentials