E2E API Payments Guide

Once your connection is set up and you are ready to make payments, you can simply follow the steps below to make payments with the StoneX Payment APIs.

Let's take an example where you need to pay an invoice of USD 2250 to a supplier in Brazil.

Step 1: Request a Quote

You will first need to call the Quote API to request a rate. The response provides you with the rate, buy amount, expiry time, value date, and a quote ID.

Request:

{
  "sellCurrency": "USD",
  "buyCurrency": "BRL",
  "sellAmount": 2250 
}

Response:

{
    "quoteId": "ecf8294c-145a-4ca0-b622-cec77c9ff210",
    "sellCurrency": "USD",
    "buyCurrency": "BRL",
    "sellAmount": 2250,
    "buyAmount": 13191.98,
    "rate": 5.8631,
    "fee": 0,
    "createdTime": "2025-01-16T10:34:47.6867711Z",
    "quoteExpiry": "2025-01-17T10:38:07.3830956Z",
    "valueDate": "2025-01-17"
}

Step 2: Book the Trade

Once you have the quoteId from the Quote API response, you are now ready to book the trade. You will need to provide a valid quoteId to call the Book Trade API to confirm the trade booking. Make sure your quoteId hasn't expired otherwise you'll need to request another quoteId before booking the trade.

The response provides a fxId which is the unique StoneX identifier for this payment. You can use this fxId to provide payment instructions, track payment or request cancellation using the other APIs.

Request:

{
  "quoteId": "ecf8294c-145a-4ca0-b622-cec77c9ff210"
}

Response:

{
    "isSuccess": true,
    "buyAmount": 13191.98,
    "sellAmount": 2250,
    "buyCurrency": "BRL",
    "sellCurrency": "USD",
    "tradeStatus": "PENDING",
    "rate": 5.8631,
    "tradeDate": "2025-01-16",
    "quoteId": "ecf8294c-145a-4ca0-b622-cec77c9ff210",
    "fxId": 4847182,
    "fee": 0
}

Step 3: Validate Payment Instruction

After you've booked a trade and are ready to provide us with payment instructions, you should use our Payment Validation API to validate your payment instruction. Your payment instructions will need to follow a standard JSON format as you can see below. The full payment instruction format can be found on the Instruct API page. However, each currency has different rules which means for some currencies like BRL, you will need to provide fields like postalCode, taxId, emailaddress which are not mandatory for other currencies. In order to check what's required for a particular currency, you can call the Currency Requirement API which lists all the mandatory fields needed for the payment instruction.

You can also refer to our detailed guide on How to use Payment Rules.

Once you have created the payment instruction JSON with all the required values, you can use the Validation API to validate if everything is correct. If there are any missing/incorrect values in your payment instruction request, you will receive an error in the response highlighting what is wrong with your payment instruction.

In the below request, we have populated all mandatory fields for a payment to Brazil such as taxId, emailaddress and fullname, so the Validation API returns the status as "Complete". This means you are now ready to submit the Payment Instructions.

Request:

{
    
    "fxid": 4847182,
   

    "creditor": {
      "name": "Organic Foods Inc.",
      "address": {
      "buildingNo": "517/205",
      "buildingName": null,
      "floor": "13",
      "street": "Avenida Visconde De Albuquerque",
      "city": "Rio De Janeiro",
      "district": "RJ",
      "postalCode": "22450-003",
      "state": null,
      "countryCode": "BR"
      },
     
      "partytype": "Business",
      "taxid": "78945465121001",
      "contactdetails": {
        "firstname": "Daniele",
        "lastname": "Santos",
        "emailaddress": "[email protected]",
        "telephone": {
          "countrycode": "55",
          "phonenumber": "05574654564"
        },
        "mobilephone": null,
        "fullname": "Daniele Santos"
      }
    },

    "creditorcountrycode": "BR",
    "clientBuyCurrency": "BRL",
    "creditoraccountname": "Organic Foods Inc.",
    "creditoraccountnumber": "BR789744212132012145544545222",

    "creditoragent": {
      "routingcode": "DABEBRSXXXX"
    },
    
    "purposeofpayment": {
      "unstructedinfo": "Invoice no 2025/111/03"
    }
  }

Resposne:

{
    "status": "Complete",
    "invalidRules": []
}

Error Response:

If you don't provide a mandatory value such as taxId in the payment instruction, the Validation API response looks like below. You will need to fix the error before you can submit the instruction.

{
    "status": "Incomplete",
    "invalidRules": [
        {
            "fieldLabelIdentifier": "BeneficiaryTaxID",
            "fieldName": "Beneficiary Tax ID",
            "ruleName": "MANDATORY",
            "fieldValue": "",
            "errorMessage": "Beneficiary Tax ID is mandatory.",
            "validationStatus": "Invalid"
        }
    ]
}

Step 4: Submit Payment Instruction

Once the payment instruction is successfully validated, you are now ready to submit your payment instruction via the Instruct API.

The response will include the details of the instructed payment like buyAmount, sellAmount, rate, tradeStatus, valueDate, fxId.

Once we receive your payment instruction, our systems will initiate the transfer to your recipient. You can check the status of your payment using the Get Status API.

Request:

 {
    
    "fxid": 4847182,
   

    "creditor": {
      "name": "Organic Foods Inc.",
      "address": {
      "buildingNo": "517/205",
      "buildingName": null,
      "floor": "13",
      "street": "Avenida Visconde De Albuquerque",
      "city": "Rio De Janeiro",
      "district": "RJ",
      "postalCode": "22450-003",
      "state": null,
      "countryCode": "BR"
      },
     
      "partytype": "Business",
      "taxid": "78945465121001",
      "contactdetails": {
        "firstname": "Daniele",
        "lastname": "Santos",
        "emailaddress": "[email protected]",
        "telephone": {
          "countrycode": "55",
          "phonenumber": "05574654564"
        },
        "mobilephone": null,
        "fullname": "Daniele Santos"
      }
    },

    "creditorcountrycode": "BR",
    "clientBuyCurrency": "BRL",
    "creditoraccountname": "Organic Foods Inc.",
    "creditoraccountnumber": "BR789744212132012145544545222",

    "creditoragent": {
      "routingcode": "DABEBRSXXXX"
    },
    
    "purposeofpayment": {
      "unstructedinfo": "Invoice no 2025/111/03"
    }
  }

Response:

{
    "createdDate": "2025-01-16T00:00:00Z",
    "tradeResponse": {
        "isSuccess": true,
        "buyAmount": 13191.98,
        "sellAmount": 2250,
        "buyCurrency": "BRL",
        "sellCurrency": "USD",
        "tradeStatus": "EXECUTED",
        "rate": 5.8631,
        "tradeDate": "2025-01-16",
        "quoteId": "ecf8294c-145a-4ca0-b622-cec77c9ff210",
        "fxId": 4847182,
        "fee": 0
    },
    "valueDate": "2025-01-17"
}