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