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	Required?	Description
fxId	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	Y	Provide a valid reason code. See list above.
topicCode	Y	Provide a valid topic code. See list above.
description	Y	Please add details of the issue in this field.

Example request

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

{
  "fxid": 12345678,
  "reasonCode": "REASON000736",
  "topicCode": "TOPIC00030",
  "description": "Please provide updates on this payment urgently"
}

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 Invetigation endpoint.

Example response

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

{
    "supportTicketId": "string",
    "createdBy": "StoneX Payments",
    "createdDate": "2025-02-27T12:41:53.687Z",
    "fxId": 12345678,
    "topic": "Invoice/Foreign Exchange Confirmation",
    "reason": "Billing not received",
    "status": "OPEN",
    "messages": [
        {
            "createdBy": "StoneX Payments",
            "createdDate": "2025-02-27T12:41:53.687Z",
            "comment": "Please provide updates on this payment urgently",
            "attachments": []
        }
    ]
}

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