Create an investigation

This endpoint allows you to create new investigations (linked to an ongoing payment using fxId or enquiries with our client support team.

By providing the original fxId of the payment in the API request, you can start an investigation against an existing payment.

If you have a general enquiry, you can call the same endpoint without the fxId to create a general enquiry.

The API request needs to contain a valid Topic and Reason code. Please see below list of allowed Topic and Reason codes & where fxId is mandatory.

fxid Required?	Topic Code	Topic Description	Reason Code	Reason Description
Y	TOPIC00029	Cancel	REASON00077	Hold payment
Y			REASON00075	Incorrect amount
Y			REASON00070	Incorrect value date
Y			REASON00069	Incorrect account details
Y			REASON00074	Recall request
Y			REASON00122	Transaction duplicated
Y			REASON00072	Transaction made by mistake
Y	TOPIC00030	FEC	REASON00078	Foreign Exchange Confirmations not received
Y			REASON00123	Incorrect Foreign Exchange Confirmations
Y	TOPIC00028	Modify	REASON00075	Incorrect amount
Y			REASON00070	Incorrect value date
Y			REASON00069	Incorrect account details
Y	TOPIC00026	Payment Status	REASON00065	On hold with beneficiary bank
Y			REASON00121	Payment not debited
Y			REASON00071	Payment not received
Y			REASON00064	Proof of payment
Y	TOPIC00047	Payment Pending	REASON00066	Pending limit review
Y			REASON00068	Payment pending approval
Y			REASON00120	Payment pending execution
Y	TOPIC00014	Other	REASON00027	Other
N	TOPIC00048	Payment Support	REASON00144	Create a Payment
N			REASON00145	Create a Beneficiary
N			REASON00146	Linking Beneficiary to Payment
N			REASON00147	Explanation about Rates/ Value dates
N			REASON00148	Intermediary bank request
N			REASON00149	Amount/rate discrepancy
N			REASON00150	Access Archived Data
N			REASON00151	Temporary Limit Increase
N			REASON00152	Audit request
N			REASON00153	Technical Support
N	TOPIC00049	Training Required	REASON00154	Role (Drop down list)
N			REASON00155	Functionality (Drop down list)
N	TOPIC00023	Batch Upload	REASON00114	Beneficiary template
N			REASON00157	Upload issues
N			REASON00158	Unable to review Payments
N	TOPIC00019	Beneficiary Template	REASON00110	Access archived data
N			REASON00046	Access all beneficiary
N			REASON00054	Linking Beneficiary to Payment
N			REASON00045	Create Beneficiary
N			REASON00128	Modify a beneficiary
N			REASON00032	Technical Support
N	TOPIC00025	Complaints	REASON00062	Complaints
N	TOPIC00043	Currency Requirement	REASON00317	Currency requirement
N			REASON00131	New flow enquiry
N	TOPIC00027	Feedback	REASON00067	Feedback
N	TOPIC00014	Other	REASON00027	Other
N	TOPIC00046	Reimburse StoneX	REASON00136	Direct Debit Set up
N			REASON00137	Invoice request
N			REASON00138	Pay first issues
N			REASON00139	Reimbursement updates
N			REASON00141	StoneX Account details
N			REASON00156	Incorrect Billing
N	TOPIC00040	Technical Set-up	REASON00117	File upload
N			REASON00143	SFTP
N			REASON00118	Technical issue
N			REASON00119	API
N			REASON00116	XML
N	TOPIC00024	User setup	REASON00063	Technical issues
N			REASON00058	Training required
N			REASON00059	User setup support

Request

The following fields are available in the API request structure:

Field	Data Type	Required?	Description
fxId	String	N	Provide the unique `fxId` of the transaction against which you're raising the investigation. If your query is not related to an ongoing payment, you can leave this blank.
reasonCode	String	Y	Provide a valid reason code. See list above.
topicCode	String	Y	Provide a valid topic code. See list above.
description	String	Y	Please add details of the issue in this field.
additionalDetails	Object	N	Optional object to provide additional information with the investigation
> orderingInstitution	Object	N	Use this object to add details about ordering institution. Ordering Institution refers to the entity initiating the investigation on behalf of the sender of the payment.
> > name	String	N	Name of the ordering institution
> > contactInfo	Array of objects	N	Use this to add contact information about ordering institution
> > > firstName	String	N	First Name
> > > lastName	String	N	Last Name
> > > email	String	N	Email
> instructingInstitution	Object	N	Use this object to send the details of the instructing institution. Instructing institution refers to the entity managing liaison with StoneX.
> > name	String	N	Name of the instructing institution
> userInfo	Object	N	Use this object to send user details
> > createdBy	Object	N	Object to add details of the person who created the investigation
> > > contactInfo	Object	N	Object to add contact details of the person raising the investigation
> > > > firstName	String	N	First Name
> > > > lastName	String	N	Last Name
> > > > email	String	N	Email

Example request

Please see below a sample request code for creating a new investigation:

{
    "fxid": 1234567,
    "reasonCode": "REASON00077",
    "topicCode": "TOPIC00029",
    "description": "Please change the buy amount to 300",
    "additionalDetails": {
        "orderingInstitution": {
            "name": "First Bank",
            "contactInfo": [
                {
                    "firstName": "Adam",
                    "lastName": "Bird",
                    "email": "[email protected]"
                }
            ]
        },
        "instructingInstitution": {
            "name": "Aspire Bank Ltd"
        },
        "userInfo": {
            "createdBy": {
                "contactInfo": {
                    "firstName": "John",
                    "lastName": "Scott",
                    "email": "[email protected]"
                }
            }
        }
    }
}

Response

The response contains the details of the support ticket created along with supportTicketId. You can use this to track about the investigation going forward by calling the View Investigation endpoint.

Example response

If the investigation is created successfully, the response will contain a unique supportTicketId along with the status of the investigation.

You can use this supportTicketId to query about this investigation further.

{
    "supportTicketId": "CS5100280091",
    "createdBy": "John Scott",
    "createdDate": "2025-05-19T10:37:37.455Z",
    "fxId": "1234567",
    "topic": "Cancel",
    "reason": "Hold Payment",
    "status": "OPEN",
    "orderingInstitutionName": "FNBB Bank",
    "instructingInstitution": "Chase Bank Ltd",
    "messages": [
        {
            "createdBy": "John Scott",
            "createdDate": "2025-05-19T10:37:37.455Z",
            "comment": "Please change the buy amount to 300",
            "attachments": [],
            "orderingInstitutionName": "FNBB Bank",
            "instructingInstitution": "Chase Bank Ltd"
        }
    ]
}

Error Scenarios

If you provide an invalid reasonCode and topicCode combination that is not supported, the API will return an error as below:

{
    "title": "Bad Input",
    "status": 400,
    "detail": "Invalid Topic/reason/Description entered. Please refer to documentation for valid topic or reason or description.",
    "traceId": "00-8d3af76c927da98223de15ab9d37259c-092240d735f1922f-00",
    "errorCode": "INV00003"
}

Similarly, if you created an investigation with an invalid fxId, then you will receive the below error

{
    "title": "Bad Input",
    "status": 400,
    "detail": "Trade could not be found",
    "traceId": "00-2c8954514e40f8591987944c6b196ce5-7c96de0797b89fbb-00",
    "errorCode": "INS00001"
}

If you create an investigation but do not provide a description in the request, you will get the below error

{
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "Description": [
            "The Description field is required."
        ]
    },
    "traceId": "00-8959e49171803cce8dbd797610dec17a-b4ba3157ae3f3f3c-00"
}

If you create an investigation with a fxId which already has an ongoing investigation, you will get the below error

{
    "title": "Bad Input",
    "status": 400,
    "detail": "Investigation is already under progress for this FXID",
    "traceId": "00-935b6cc68d2aabf962846dbe8d34e780-fffe8827935918d3-00",
    "errorCode": "INV00007"
}

If you create an investigation with a fxId which is not yet in a 'executed' status, you will get the below error

{
    "title": "Bad Input",
    "status": 400,
    "detail": "Incorrect status of FXID. Please provide \"Executed\" FXID to create an investigation",
    "traceId": "00-6dd9f984ca604dfc5233ffe0203a3a22-b6535f14f7895cf1-00",
    "errorCode": "INV00008"
}