API Reference
HomeGuidesAPI ReferenceChangelog

Introduction

Welcome to the StoneX Payments API Developer Portal! This guide provides essential information to help you effectively utilize our RESTful API, which uses JSON payloads for smooth data exchange. Here, you'll find everything you need to integrate with our API, which offers real-time FX rates and facilitates trade executions for payment distribution.

Below is an overview of the key features and functionalities of our API, as well as best
practices for application integration.


API Versioning

Our API is regularly updated to introduce new features, enhance functionality, and fix bugs. Major updates that involve breaking changes will increment the version number. Non-breaking updates include:

  • Adding new resources
  • Introducing new optional request parameters
  • Expanding response attributes
  • Modifying attribute order in responses (JSON’s unordered nature)
  • Extending or altering opaque strings, like IDs and error messages
  • Introducing new webhook events
  • Renaming existing API fields

Key Features

  • Ease of Use: Adheres to RESTful principles, ensuring a straightforward experience with standard HTTP methods (GET, POST, PUT, DELETE).
  • Data Format: Utilizes JSON for all data exchanges, ensuring broad compatibility and ease of data manipulation.
  • Security: All requests must be made over HTTPS to guarantee encrypted communication. Authentication tokens are required to verify requesters and authorize access.
  • Comprehensive Documentation: Detailed guides are provided for each endpoint, including parameters, request/response formats, and examples.

Formatting Standards

  • Currency Codes: Follow ISO 4217 standards (e.g., USD, EUR, JPY).
  • Country Codes: Use ISO 3166 two-letter codes (e.g., US, NP, AU).
  • Dates and Timestamps: Adhere to ISO 8601 and use UTC unless otherwise specified (e.g., 2024-05-22 16:48:01 UTC).

Base URLs


Requests and Responses

  • HTTPS and TLS 1.3: Use TLS 1.3 for all API requests to ensure security. Avoid older SSL versions due to lower security standards.
  • Headers:
    • Content-Type: Set to application/json to match the API’s expected data format.
    • Authorization: Include a valid Bearer token
    • X-Client-Id: Optional field for partners booking on behalf of our clients

Response Codes

Our API uses standard HTTP response codes to indicate the status of your requests:

  • 200: Success
  • 201: Resource successfully created (POST requests)
  • 202: Request accepted, but processing is not complete
  • 400: Error due to missing or incorrect information
  • 401: Unauthorized (invalid or expired token)
  • 404: Resource not found
  • 429: Rate limit exceeded
  • 500: Server error (could be due to expired rate quotes, etc.)
  • 503: Server unavailable or under maintenance