openapi: 3.0.3
info:
  title: StoneX Payments API
  description: >-
    The StoneX Payments REST API enables cross-border payment processing in
    140+ currencies with local currency acceptance and settlement. Uses Bearer
    token authentication over HTTPS with TLS 1.3. ISO standards are used
    throughout: ISO 4217 currency codes, ISO 3166 country codes, ISO 8601 timestamps.
  version: '1.0'
  contact:
    url: https://docs.payments.stonex.io/
servers:
  - url: https://fx-api.payments.stonex.com
    description: StoneX Payments Production
  - url: https://api.sandbox.payments.stonex.com
    description: StoneX Payments Sandbox (UAT)
tags:
  - name: Authentication
    description: Token management for API access.
  - name: Payments
    description: Payment execution and management.
  - name: FX Rates
    description: Foreign exchange rate queries.
paths:
  /auth/token:
    post:
      operationId: getAuthToken
      summary: Get Authentication Token
      description: >-
        Exchange client credentials for a JWT access token. The generated
        access_token has a lifetime of 10 hours and must be passed as a
        Bearer token in the Authorization header for all subsequent requests.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - client_id
                - client_secret
              properties:
                client_id:
                  type: string
                  description: API client ID provided by StoneX upon account setup.
                client_secret:
                  type: string
                  description: API client secret provided by StoneX.
      responses:
        '200':
          description: Authentication token returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Invalid request parameters.
        '401':
          description: Invalid client credentials.
  /payments:
    post:
      operationId: createPayment
      summary: Create Payment
      description: >-
        Initiate a cross-border payment in local currency. Supports 140+
        currencies and local settlement options globally.
      tags:
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
      responses:
        '201':
          description: Payment created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: Invalid payment request.
        '401':
          description: Unauthorized.
        '429':
          description: Rate limit exceeded.
    get:
      operationId: listPayments
      summary: List Payments
      description: Retrieve a list of payments with optional filtering.
      tags:
        - Payments
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [pending, processing, completed, failed, cancelled]
          description: Filter payments by status.
        - name: currency
          in: query
          required: false
          schema:
            type: string
          description: Filter by payment currency (ISO 4217).
        - name: from_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Start of date range filter (ISO 8601).
        - name: to_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: End of date range filter (ISO 8601).
        - name: page
          in: query
          required: false
          schema:
            type: integer
          description: Page number for pagination.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
          description: Number of results per page.
      responses:
        '200':
          description: Payments list returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentList'
        '401':
          description: Unauthorized.
  /payments/{paymentId}:
    get:
      operationId: getPayment
      summary: Get Payment
      description: Retrieve details of a specific payment by ID.
      tags:
        - Payments
      parameters:
        - name: paymentId
          in: path
          required: true
          schema:
            type: string
          description: Unique payment identifier.
      responses:
        '200':
          description: Payment details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          description: Unauthorized.
        '404':
          description: Payment not found.
  /rates:
    get:
      operationId: getFxRates
      summary: Get FX Rates
      description: >-
        Get indicative foreign exchange rates for supported currency pairs.
      tags:
        - FX Rates
      parameters:
        - name: sell_currency
          in: query
          required: true
          schema:
            type: string
          description: Source currency (ISO 4217 code).
        - name: buy_currency
          in: query
          required: true
          schema:
            type: string
          description: Target currency (ISO 4217 code).
        - name: amount
          in: query
          required: false
          schema:
            type: number
          description: Amount to convert.
      responses:
        '200':
          description: FX rate returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxRate'
        '401':
          description: Unauthorized.
        '404':
          description: Currency pair not supported.
components:
  schemas:
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: JWT Bearer access token.
        token_type:
          type: string
          description: Token type (Bearer).
        expires_in:
          type: integer
          description: Token expiry in seconds (36000 = 10 hours).
    CreatePaymentRequest:
      type: object
      required:
        - amount
        - sell_currency
        - buy_currency
        - beneficiary
      properties:
        amount:
          type: number
          description: Payment amount.
        sell_currency:
          type: string
          description: Source currency code (ISO 4217).
        buy_currency:
          type: string
          description: Destination currency code (ISO 4217).
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'
        payment_reference:
          type: string
          description: Reference for the payment.
        value_date:
          type: string
          format: date
          description: Desired value date for the payment.
    Payment:
      type: object
      properties:
        id:
          type: string
          description: Unique payment identifier.
        status:
          type: string
          enum: [pending, processing, completed, failed, cancelled]
          description: Payment status.
        amount:
          type: number
          description: Payment amount.
        sell_currency:
          type: string
          description: Source currency (ISO 4217).
        buy_currency:
          type: string
          description: Destination currency (ISO 4217).
        exchange_rate:
          type: number
          description: Applied exchange rate.
        buy_amount:
          type: number
          description: Amount received in the destination currency.
        payment_reference:
          type: string
          description: Payment reference.
        created_at:
          type: string
          format: date-time
          description: Payment creation timestamp.
        value_date:
          type: string
          format: date
          description: Settlement value date.
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'
    PaymentList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        total:
          type: integer
          description: Total number of payments matching the filter.
        page:
          type: integer
          description: Current page number.
        page_size:
          type: integer
          description: Number of results per page.
    Beneficiary:
      type: object
      required:
        - name
        - country
        - account_number
        - bank_code
      properties:
        name:
          type: string
          description: Beneficiary name.
        country:
          type: string
          description: Beneficiary country (ISO 3166-1 alpha-2).
        account_number:
          type: string
          description: Beneficiary bank account number or IBAN.
        bank_code:
          type: string
          description: Bank routing code (BIC/SWIFT, ABA, sort code, etc.).
        address:
          type: string
          description: Beneficiary address.
    FxRate:
      type: object
      properties:
        sell_currency:
          type: string
          description: Source currency code.
        buy_currency:
          type: string
          description: Destination currency code.
        rate:
          type: number
          description: Indicative exchange rate.
        timestamp:
          type: string
          format: date-time
          description: Rate timestamp.
        sell_amount:
          type: number
          description: Source amount (if provided).
        buy_amount:
          type: number
          description: Equivalent destination amount.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: JWT token obtained from the /auth/token endpoint. Valid for 10 hours.
security:
  - BearerAuth: []