Add delivery instructions to a trade

The Instruct API allows you to submit payment delivery instructions for trades already booked with our system. You will need to include a valid fxId in the request when providing delivery instructions for a trade.

Request

The request body to provide delivery instructions is split into various mandatory and optional objects.

Field Name	Data Type	Required	Description
fxId	String	Yes	Unique `fxId` provided by StoneX when booking the trade
clientReference	String	No	Optional field to provide an external reference for the payment
tradeBooking	Object	No	This object is required only if `fxID` is not provided. If you have added `fxId`, leave this blank.
debtor	Object	No	Information about the payer (debtor).
creditor	Object	Yes	Information about the payee (creditor)
creditorAccountName	String	No	Account Name of the creditor. Check payment rules to confirm if needed.
creditorAccountNumber	String	Yes	Account Number of the creditor.
creditorAccountType	String	No	Account Type of the creditor. Check payment rules to confirm if needed.
creditorAccountNumberType	String	No	Type of account number
creditorCountryCode	String	No	Country the creditor account is present in
clientBuyCurrency	String	No	Currency the debtor has purchased
debtorAccountNumber	String	No	Account number of the debtor
purposeOfPayment	Object	No	Payment purpose code. Check payment rules to confirm if needed
> structuredInfo	Array of strings	No	Provide purpose of payment as code here. See payment rules to find out accepted values
> unstructuredInfo	String	No	Provide unstructured payment purpose here.
initiatingParty	Object	No	Identifies the entity initiating the payment.
instructingAgent	Object	No	The financial institution sending the payment instruction.
orderingInstitution	Object	No	The institution ordering the payment on behalf of the debtor.
ultimateCreditor	Object	No	The final recipient of the payment, distinct from the creditor.
creditorAgent	Object	Yes	Financial institution responsible for the creditor’s account. Check payment rules to confirm which fields in this object are required.
intermediaryAgents	Array of objects	No	List of intermediary agents involved in the payment transfer. You can provide multiple intermediaries by adding more than one object.
ultimateDebtor	Object	No	Identifies the ultimate debtor for payment

Object Details:

This is a list of fields you should provide when passing any of the above objects in the request parameter:

instructingAgent
orderingInstitution
creditorAgent
intermediaryAgents

Field Name	Data Type	Description
routingCode	String	Bank code. Check payment rules to confirm if required.
routingCodeType	String	Routing code type. Check payment rules to confirm if required.
name	String	Name of the Bank/Institution
address	Object	Address details in structured format
> buildingNo	String	Building number
> buildingName	String	Building name
> floor	String	Floor
> street	String	Street name. Check payment rules to confirm if required.
> city	String	City name. Check payment rules to confirm if required.
> district	String	District name
> postalcode	String	Post code
> state	String	State name
> countryCode	String	2-digit ISO code of the country
> addressLines	Array of strings	Use this to provide unstructured address
accountName	String	Name of the account
accountNumber	String	Bank’s Account Number/IBAN. Check payment rules to confirm if required.
branchCode	String	Bank Branch code. Check payment rules to confirm if required.
branchName	String	Name of the branch. Check payment rules to confirm if required.
branchNumber	String	Branch Number
otherRoutingCode	String	Any other bank code. Check payment rules to confirm if required.
taxId	String	Bank’s Tax identifier. Check payment rules to confirm if required.
additionalBankCode	String	Additional bank code

This is a list of fields you should provide when passing any of the following objects in the request parameter:

ultimateDebtor
ultimateCreditor
creditor
debtor

Field Name	Data Type	Description
name	String	Provide the name in this field. Check payment rules to confirm if required.
address	Object	Provide structured address in this object.
> buildingNo	String	Building number
> buildingName	String	Building name
> floor	String	Floor
> street	String	Street name. Check payment rules to confirm if required.
> city	String	City name. Check payment rules to confirm if required.
> district	String	District name. Check payment rules to confirm if required.
> postalcode	String	Post code. Check payment rules to confirm if required.
> state	String	State name. Check payment rules to confirm if required.
> countryCode	String	ISO country code. Check payment rules to confirm if required.
> addressLines	Array of strings	Provide unstructured address details here
identification	String	Identification details
countryOfResidence	String	ISO country code (ex - AU, KE). Check payment rules to confirm if required.
partyType	String	Entity type (ex - personal, business)
taxId	String	Tax Identification details. Check payment requirements to confirm if needed.
registrationIdentification	String	Registration Identification details
taxType	String	Tax Identity type
otherRoutingCode	String	Other routing code
contactDetails	Object	Use this object to provide structured contact details
> firstName	String	First Name
> lastName	String	Last Name
> emailAddress	String	Email. Check payment rules to confirm if required.
> telephone	Object	Telephone details
> > countrycode	String	Country code (ex- +44)
> > phonenumber	String	Phone Number. Check payment rules to confirm if required.
> mobilephone	Object	Mobile details
> > countrycode	String	Country code (ex- +49)
> > phonenumber	String	Mobile number
fullname	String	Full name. Check payment requirements to confirm if needed

initiatingParty Object Details

This object is required only for white label platform, not needed for direct API clients

Field Name	Data Type	Description
orgId	String	Provide the client's mnemonic ID generated by StoneX in this field
extOrgId	String	Provide your external reference for the client here
address	String	Provide address in this object
> buildingNo	String	Building number
> buildingName	String	Building name
> floor	String	Floor
> street	String	Street name
> city	String	City
> district	String	District
> postalcode	String	Post code
> state	String	State
> countryCode	String	Country Code
> addressLines	Array of strings	Unstructured address can be added here
name	String	Name of the initiating party

tradeBooking Object Details:

This object is only required when you are passing trade and payment details together i.e. you do not have a fxId already.

Field Name	Data Type	Description
quoteID	String	Provide `quoteId` if using this endpoint to book trade and provide instructions together.
clientReference	String	External client reference for the payment

Full Request Object

Below is the example of all the parameters you can pass in the request. Before providing instructions, check the payment rules to confirm which fields are required and what value are allowed.

If any mandatory fields for a payment are missing, or any other invalid values are provided in the request, the API will return errors highlighting the same.

{
  "fxId": 0,
  "tradeBooking": {
    "quoteId": "string",
    "clientReference": "string"
  },
  
  "intermediaryAgents": [
    {
      "routingCode": "string",
      "routingCodeType": "string",
      "name": "string",
      "address": {
        "buildingNo": "string",
        "buildingName": "string",
        "floor": "string",
        "street": "string",
        "city": "string",
        "district": "string",
        "postalCode": "string",
        "state": "string",
        "countryCode": "string",
        "addressLines": [
          "string"
        ]
      },
      "accountName": "string",
      "accountNumber": "string",
      "branchCode": "string",
      "branchName": "string",
      "branchNumber": "string",
      "otherRoutingCode": "string",
      "taxId": "string",
      "additionalBankCode": "string",
      "recordKey": "string"
    }
  ],
  
  "clientReference": "string",
  
  "creditor": {
    "name": "string",
    "address": {
      "buildingNo": "string",
      "buildingName": "string",
      "floor": "string",
      "street": "string",
      "city": "string",
      "district": "string",
      "postalCode": "string",
      "state": "string",
      "countryCode": "string",
      "addressLines": [
        "string"
      ]
    },
    "identification": "string",
    "countryOfResidence": "string",
    "partyType": "string",
    "taxId": "string",
    "registrationIdentification": "string",
    "taxType": "string",
    "otherRoutingCode": "string",
    "contactDetails": {
      "firstName": "string",
      "lastName": "string",
      "emailAddress": "string",
      "telephone": {
        "countrycode": "string",
        "phonenumber": "string"
      },
      "mobilephone": {
        "countrycode": "string",
        "phonenumber": "string"
      },
      "fullName": "string"
    }
  },
  
  "ultimateCreditor": {
    "name": "string",
    "address": {
      "buildingNo": "string",
      "buildingName": "string",
      "floor": "string",
      "street": "string",
      "city": "string",
      "district": "string",
      "postalCode": "string",
      "state": "string",
      "countryCode": "string",
      "addressLines": [
        "string"
      ]
    },
    "identification": "string",
    "countryOfResidence": "string",
    "partyType": "string",
    "taxId": "string",
    "registrationIdentification": "string",
    "taxType": "string",
    "otherRoutingCode": "string",
    "contactDetails": {
      "firstName": "string",
      "lastName": "string",
      "emailAddress": "string",
      "telephone": {
        "countrycode": "string",
        "phonenumber": "string"
      },
      "mobilephone": {
        "countrycode": "string",
        "phonenumber": "string"
      },
      "fullName": "string"
    }
  },
  
  "creditorAccountName": "string",
  "creditorAccountNumber": "string",
  "creditorAccountType": "string",
  "creditorAccountNumberType": "string",
  
  "creditorAgent": {
    "routingCode": "string",
    "routingCodeType": "string",
    "name": "string",
    "address": {
      "buildingNo": "string",
      "buildingName": "string",
      "floor": "string",
      "street": "string",
      "city": "string",
      "district": "string",
      "postalCode": "string",
      "state": "string",
      "countryCode": "string",
      "addressLines": [
        "string"
      ]
    },
    "accountName": "string",
    "accountNumber": "string",
    "branchCode": "string",
    "branchName": "string",
    "branchNumber": "string",
    "otherRoutingCode": "string",
    "taxId": "string",
    "additionalBankCode": "string",
    "recordKey": "string"
  },
  
  "debtorAccountNumber": "string",
  
  "debtor": {
    "name": "string",
    "address": {
      "buildingNo": "string",
      "buildingName": "string",
      "floor": "string",
      "street": "string",
      "city": "string",
      "district": "string",
      "postalCode": "string",
      "state": "string",
      "countryCode": "string",
      "addressLines": [
        "string"
      ]
    },
    "identification": "string",
    "countryOfResidence": "string",
    "partyType": "string",
    "taxId": "string",
    "registrationIdentification": "string",
    "taxType": "string",
    "otherRoutingCode": "string",
    "contactDetails": {
      "firstName": "string",
      "lastName": "string",
      "emailAddress": "string",
      "telephone": {
        "countrycode": "string",
        "phonenumber": "string"
      },
      "mobilephone": {
        "countrycode": "string",
        "phonenumber": "string"
      }
    }
  },
  
  "ultimateDebtor": {
    "name": "string",
    "address": {
      "buildingNo": "string",
      "buildingName": "string",
      "floor": "string",
      "street": "string",
      "city": "string",
      "district": "string",
      "postalCode": "string",
      "state": "string",
      "countryCode": "string",
      "addressLines": [
        "string"
      ]
    },
    "identification": "string",
    "countryOfResidence": "string",
    "partyType": "string",
    "taxId": "string",
    "registrationIdentification": "string",
    "taxType": "string",
    "otherRoutingCode": "string",
    "contactDetails": {
      "firstName": "string",
      "lastName": "string",
      "emailAddress": "string",
      "telephone": {
        "countrycode": "string",
        "phonenumber": "string"
      },
      "mobilephone": {
        "countrycode": "string",
        "phonenumber": "string"
      }
    }
  },
  
  "orderingInstitution": {
    "routingCode": "string",
    "routingCodeType": "string",
    "name": "string",
    "address": {
      "buildingNo": "string",
      "buildingName": "string",
      "floor": "string",
      "street": "string",
      "city": "string",
      "district": "string",
      "postalCode": "string",
      "state": "string",
      "countryCode": "string",
      "addressLines": [
        "string"
      ]
    },
    "accountName": "string",
    "accountNumber": "string",
    "branchCode": "string",
    "branchName": "string",
    "branchNumber": "string",
    "otherRoutingCode": "string",
    "taxId": "string",
    "additionalBankCode": "string",
    "recordKey": "string"
  },
  
  "purposeOfPayment": {
    "structuredInfo": [
      "string"
    ],
    "unstructedInfo": "string"
  },
  
  "creditorCountryCode": "string",
  
  "instructingAgent": {
    "routingCode": "string",
    "routingCodeType": "string",
    "name": "string",
    "address": {
      "buildingNo": "string",
      "buildingName": "string",
      "floor": "string",
      "street": "string",
      "city": "string",
      "district": "string",
      "postalCode": "string",
      "state": "string",
      "countryCode": "string",
      "addressLines": [
        "string"
      ]
    },
    "accountName": "string",
    "accountNumber": "string",
    "branchCode": "string",
    "branchName": "string",
    "branchNumber": "string",
    "otherRoutingCode": "string",
    "taxId": "string",
    "additionalBankCode": "string",
    "recordKey": "string"
  },
  
  "initiatingParty": {
    "orgId": "string",
    "extOrgId": "string",
    "address": {
      "buildingNo": "string",
      "buildingName": "string",
      "floor": "string",
      "street": "string",
      "city": "string",
      "district": "string",
      "postalCode": "string",
      "state": "string",
      "countryCode": "string",
      "addressLines": [
        "string"
      ]
    },
    "name": "string"
  },
 
  "clientBuyCurrency": "string",
  "doddFrank": true
}

Response

Once a payment instruction is linked to the trade, the following values will be returned in the API response:

Field Name	Type	Description
createdDate	DateTime	Date & time when instruction was created
tradeResponse	Object	Object containing the details of the payment
> message	String	Additional message related to payment
> errorcode	String	Error codes if any
> isSuccess	boolean	true or false (true - instruction was accepted & linked to trade)
> buyAmount	number	Amount you're buying
> sellAmount	number	Amount you're selling
> buyCurrency	String	Currency you're buying (Ex- INR, KES)
> sellCurrency	String	Currency you're selling (Ex- USD, GBP)
> tradeStatus	String	Status of the trade
> rate	number	Rate for the trade
> tradeDate	Date (yyyy-mm-dd)	Date trade was executed
> quoteId	String	Unique quote ID used by StoneX to book the trade
> fxId	String	Unique FX ID used by StoneX to book the trade
> fee	number	Any fee charge for the payment (always in sell currency)
valueDate	Date (yyyy-mm-dd)	Value Date of the payment

Success Example

{
    "createdDate": "2024-10-14T00:00:00Z",
    "tradeResponse": {
        "message": null,
        "errorCode": null,
        "isSuccess": true,
        "buyAmount": 8244.07,
        "sellAmount": 100,
        "buyCurrency": "INR",
        "sellCurrency": "USD",
        "tradeStatus": "EXECUTED",
        "rate": 82.4407,
        "tradeDate": "2024-10-14",
        "quoteId": "2538c92a-2d02-43d3-9adc-118312de7a76",
        "fxId": 4763401,
        "fee": 0
    },
    "valueDate": "2024-10-16"
}

Failure Example 1 - Invalid Bank Code and ISO Country Code

{
    "status": "Incomplete",
    "invalidRules": [
        {
            "fieldLabelIdentifier": "IFSCCode",
            "fieldName": "Bank Code",
            "ruleName": "FORMAT BANKCODE",
            "fieldValue": "ABCD0000985",
            "errorMessage": "IFSC Code must have a valid bank code format",
            "validationStatus": "Invalid"
        },
        {
            "fieldLabelIdentifier": "BeneficiaryCountryofResidence",
            "fieldName": "Beneficiary Address Country",
            "ruleName": "ISO COUNTRY CODE",
            "fieldValue": "AB",
            "errorMessage": "Beneficiary Country of Residence must have a valid ISO Country Code (2 letters)",
            "validationStatus": "Invalid"
        }
    ]
}

Failure Example 2 - Mandatory field missing

{
    "status": "Incomplete",
    "invalidRules": [
        {
            "fieldLabelIdentifier": "BeneficiaryAccountName",
            "fieldName": "Account Name",
            "ruleName": "MANDATORY",
            "fieldValue": "",
            "errorMessage": "Beneficiary Account Name is mandatory.",
            "validationStatus": "Invalid"
        }
    ]
}

Failure Example 3 - FxId is already instructed

{
    "title": "Bad Input",
    "status": 400,
    "detail": "FxId is already instructed",
    "traceId": "00-a74be65e2c34f3c41dee4af2f2f00ee3-9f11c7019893e941-00",
    "errorCode": "INS00008"
}