Skip to main content
Use this page when a boarding request fails, returns unexpected results, or you are not sure what went wrong. Find your problem below and follow the steps to resolve it.

Before you troubleshoot

Before you troubleshoot a specific error, run through these checks:
  • Confirm you are using the correct environment (production or cert). See Environments and URLs.
  • Verify your credentials: OAuth token (Boarding API) or SFTP credentials (XML).
  • Check that your acquirer ID matches the value Fexco provided during onboarding.
  • Confirm the request or file matches the documented format for your boarding method.

File and request issues

No merchants in the file are processed. The response file is empty or not generated.Common causes
  • A required XML element is missing or empty.
  • Elements appear in the wrong order.
  • A special character like & is used without an XML entity reference (use & instead).
  • A data field exceeds the maximum length defined in the XSD.
  • The xsi:schemaLocation attribute is missing from the root element.
  • The encoding declaration is missing or incorrect.
How to fix
  1. Validate the file against the Boarding File Upload XSD.
  2. Fix each error the validator reports.
  3. Re-validate until the file passes with no errors.
  4. Upload the corrected file to your SFTP directory.
This only applies to XML submissions. Boarding API requests do not have file-level rejection.
The file or batch was accepted, but some merchants failed. Other merchants in the same submission were processed normally.What you are seeing
  • XML: the response file shows 400 in the Status Code column for the failed merchants.
  • Boarding API: the summary endpoint shows FAILED in the status field for the failed merchants.
Common causes
  • Merchant already exists (duplicate ID).
  • Template not found (wrong fileGroupId, templateId, or rate margin name).
  • Unknown acquirer ID.
  • Invalid or missing required fields.
How to fix
  1. Check the error code on the failed merchant.
  2. Fix the data for the failed merchants only.
  3. Resubmit only the failed merchants. Do not resubmit merchants that succeeded, as this causes duplicate errors.
The merchant was created, updated, or deactivated, but the response includes warning codes.What you are seeing
  • XML: the response file shows 200 in the Status Code column, but the Warning List column is not empty.
  • Boarding API: the summary endpoint shows COMPLETED_WITH_WARNINGS in the status field.
What this meansWarnings do not block the operation. The merchant was processed, but part of the submitted data may not have been applied as expected. For example, a terminal ID you tried to add may already exist, or an account manager name did not match.How to fix
  1. Look up the warning code in the response file.
  2. Decide if the warning affects your intended result.
  3. If you need to change a rate margin or base currency on an existing originator, delete the originator and add a new one with the correct values.
You submitted a request but did not receive a response or confirmation file.Boarding API
  1. Poll Get boarding status. The batch may still be processing.
  2. If polling returns no result after 1 hour, contact your Fexco project manager with the boardingId.
XML
  1. Check your SFTP Outgoing folder for a response file. Processing normally takes up to 30 minutes. Large files may take up to approximately 1 hour.
  2. Confirm the file was uploaded to the correct SFTP directory (Incoming folder).
  3. Verify the file follows the naming convention. Files with incorrect names may not be picked up.
  4. If no response file appears after 1 hour, contact your Fexco project manager with the file name and upload timestamp.

Authentication and connection issues

Your boarding request is rejected before any data is processed.Common causes
  • OAuth token is invalid or has expired. Use the expires_in value returned in the token response to determine when it expires.
  • The Authorization header is missing or incorrectly formatted.
  • The x-acquirer-id header does not match your acquirer code.
How to fix
  1. Request a new OAuth token. See OAuth authentication.
  2. Check that the Authorization header uses the format Bearer YOUR_ACCESS_TOKEN with a space after Bearer.
  3. Verify the x-acquirer-id header matches the acquirer code Fexco provided during onboarding.
The server recognized your credentials but rejected the request.Common causes
  • Your credentials do not have permission for this operation.
  • The acquirer ID does not match your OAuth token.
How to fix
  1. Verify the x-acquirer-id header matches the acquirer associated with your OAuth credentials.
  2. Contact your Fexco project manager to confirm your credentials have the correct permissions.
You cannot connect to the Fexco SFTP server to upload or download files.Common causes
  • SFTP credentials are incorrect.
  • Your IP address is not whitelisted.
  • You are connecting to the wrong SFTP server.
How to fix
  1. Confirm your SFTP username and password (or SSH key) are correct.
  2. Verify your outbound IP address is whitelisted with Fexco. See Security setup.
  3. Check that you are connecting to the correct SFTP server for your environment.
  4. If the issue persists, contact your Fexco project manager with your IP address and the error message.

Server errors

A 500 status code (XML) or error code 19 (all methods) means an unexpected server-side error occurred. This is not caused by your data.How to fixDo not resubmit the same request until the issue is confirmed resolved. Contact your Fexco project manager with:
  • The request ID or boarding ID.
  • The timestamp of the request.
  • The file name (for XML submissions).
  • The full error response, if available.

Merchant state issues

You are trying to update a merchant but receive error code 9 (merchant is inactive).Why this happensThe merchant was previously deactivated. Updates cannot be applied to inactive merchants.How to fixReactivate the merchant through Fexco Merchant Operations before submitting the update.
You are trying to create a merchant but receive error code 6.Why this happensA merchant with this ID is already in the system. Each merchant ID must be unique within your acquirer.How to fix
  • If you want to change the existing merchant, submit an update (XML only) instead of a create. See Update a boarded merchant.
  • If you want to create a new merchant, use a different merchant ID.

Still having issues?

If you have worked through the steps above and the issue persists, contact your Fexco project manager with:
  • Your acquirer ID.
  • The boarding method you are using (Boarding API or XML).
  • The environment (production or cert).
  • The request ID, boarding ID, or file name.
  • The timestamp of the request.
  • The full error or warning response.