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	Invoice/Foreign Exchange Confirmation	REASON00076	Billing not received
Y			REASON00123	Foreign Exchange Confirmations not received
Y			REASON00081	Incorrect billing
Y			REASON00078	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			REASON00068	Payment pending approval
Y			REASON00120	Payment pending execution
Y			REASON00066	Pending limit review
Y			REASON00064	Proof of payment
N	TOPIC00023	Batch Upload	REASON00114	Beneficiary template
N			REASON00061	Technical Issues
N			REASON00057	Transaction
N	TOPIC00019	Beneficiary Template	REASON00110	Access archived data
N			REASON00046	Access all beneficiary
N			REASON00054	Beneficiary to Payment
N			REASON00045	Create Beneficiary
N			REASON00128	Modify a beneficiary
N			REASON00032	Technical Support
N	TOPIC00025	Complaints	REASON00062	Complaints
N	TOPIC00043		REASON00317	Currency requirement
N			REASON00131	New flow enquiry
N	TOPIC00027	Feedback	REASON00067	Feedback
N	TOPIC00002	Other	REASON00001	Other
N	TOPIC00046	Pay to StoneX	REASON00136	Direct Debit Setup
N			REASON00137	Invoice request
N			REASON00140	My account details
N			REASON00138	Pay first issues
N			REASON00139	Reimbursement updates
N			REASON00141	StoneX Account details
N	TOPIC00018	Payment Support	REASON00110	Access archived data
N			REASON00038	Amount/rate discrepancy
N			REASON00043	Audit request
N			REASON00088	Beneficiary to Payment
N			REASON00035	Cancel payment
N			REASON00109	Intermediary Bank request
N			REASON00036	Make a payment
N			REASON00107	Missing/Pending MT103
N			REASON00042	PayFirst support
N			REASON00108	Rate/value dates
N			REASON00032	Technical Support
N			REASON00041	Temporary limit increase
N	TOPIC00040	Technical SetUp	REASON00117	File upload
N			REASON00144	Other
N			REASON00143	SFTP
N			REASON00118	Technical issue
N			REASON00119	XMH
N			REASON00116	XML
N	TOPIC00021	Training required	REASON00049	Functionality
N			REASON00113	Role
N	TOPIC00024	User setup	REASON00063	Technical issues
N			REASON00058	Training required
N			REASON00059	User setup required

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"
}