The Payment Order API simplifies the payment workflow by allowing clients to book an FX trade and submit payment instructions in a single API request.

Traditionally, clients would need to:

• Request a quote
• Book the trade
• Provide payment instructions using a separate API call

The Payment Order API combines these steps into a single operation, reducing integration complexity and enabling faster straight-through processing.

Upon successful submission, StoneX validates the payment details, books the trade, and creates the associated payment instruction. The response includes the StoneX fxid together with trade details such as rate, value date, and currency amounts.

Benefits:

• Reduced Integration Complexity: Execute trade booking and payment instruction submission through a single endpoint, eliminating the need for multiple API calls.
• Real-Time Validation: Payment instructions are validated against StoneX currency rules before the payment is accepted, helping reduce repair rates and rejected payments
• Faster Time to Market: Build a complete payment workflow with fewer API calls and less orchestration logic.
• End-to-End Traceability: Every successful request returns a unique StoneX FXID which can subsequently be used for tracking, webhooks, investigations, cancellations and reporting.

Typical Use-Cases:

• Supplier payments
• Accounts payable automation
• Treasury and ERP integrations
• Marketplace payouts
• FinTech payment orchestration
• High-volume cross-border payment workflows

Request Body:

This API allows clients to either skip the Quote/Trade APIs or get a Quote ID and then skip the Trade booking call.

• In order to use this with a quoteId, you will need to call the Get a Quote API first and then you can call this API with a valid quoteId, amount, currencies and payment instructions.
• To use this without a quoteId , you can just provide the amount and currencies along with payment instructions and we will do the rest in the background.

Example Request:

{
    "quoteId": "d39c5848-fd52-4180-89ee-97ffe9456048",
    "sellAmount": 50,
    "clientBuyCurrency": "KES",
    "clientSellCurrency": "GBP",
    "clientReference": "Invoice-12345",
 
    
    "debtor": {
        "name": "ABC Pvt Limited",
        "address": {
            "buildingNo": "123",
            "buildingName": "ABC",
            "floor": "1st Floor",
            "street": "Street1",
            "city": "London",
            "district": "string",
            "postalCode": "string",
            "state": "London",
            "countryCode": "GB"
        },
        "identification": "23459876"
    },

    "creditor": {
        "name": "Steve Smith",
        "address": {
            "street": "Vivtoria Road",
            "city": "Nairobi",
            "district": "RJ",
            "postalCode": "22450",
            "countryCode": "KE"
        },
        "CountryofResidence": "KE"
    },
    "creditorAccountNumber": "12345678",
    "creditorAccountName": "Steve Smith",
    "creditorCountryCode": "KE",
    "creditorAgent": {
        "routingCode": "KCOOKENAXXX"
    },

    "purposeOfPayment": {
        "unstructedInfo": "Invoice Payment",
                "structuredInfo":[
           "BUSB" 
        ]
    }
}

Response

One you submit the request, this API will validate the payment instruction, get a quote, book the trade and link the payment. The following fields are returned in the response.

{
    "createdDate": "2026-07-31T00:00:00Z",
    "tradeResponse": {
        "isSuccess": true,
        "buyAmount": 8600.01,
        "sellAmount": 50,
        "buyCurrency": "KES",
        "sellCurrency": "GBP",
        "tradeStatus": "EXECUTED",
        "rate": 172.0002,
        "tradeDate": "2026-07-31",
        "quoteId": "d39c5848-fd52-4180-89ee-97ffe9456048",
        "fxId": 8788301,
        "fee": 0
    },
    "valueDate": "2026-08-04"
}