1. Guides
CrossFX Payment APIs
  • Guides
    • CrossFX API Documentation
    • Support & Contact
    • API Basics
    • Authentication Guide
    • FX Rates
      • FX Rates Guide
    • Corridors
      • Supported Corridors Guide
    • Banks
      • Fetching Banks List Guide
      • Fetching Bank Branches Guide
    • Sanctions
      • Sanctions Screening Guide
    • Beneficiaries
      • Create Beneficiary Guide
      • Get Beneficiary Guide
    • Transfers
      • Generate Quote Guide
      • Confirm Transfer Guide
      • Get Transfer Status Guide
    • Crypto Deposit Address
      • Crypto Deposit Address Guide
    • Payments
      • Initiate Deposit Guide
      • Initiate Payout Guide
    • Webhooks
      • Webhooks Guide
      • Webhook Subscriptions Guide
      • Webhook Events Guide
      • Webhook Delivery Attempts Guide
    • Sandbox
      • Sandbox Data & Testing Guide
  1. Guides

API Basics

CROSSFX API · FOUNDATIONS
The rules every endpoint inherits.
Base URLs, authentication, response shapes, pagination, errors and retry behaviour in one place.
Every endpoint page assumes these rules and documents only what is specific to that operation.
OAuth 2.0JSONPaginationErrors & retries

At a glance#

Environment
Configure two URLs
Keep the API base URL and token base URL separate in your client, even though Sandbox serves both from the same host.
Authentication
OAuth 2.0
Exchange client credentials for an access token, then send `Authorization: Bearer <access_token>`.
Responses
HTTP status is the outcome
Successful responses do not share a common `data`, `success`, or `message` envelope.
Errors
Keep the error_id
Every platform error carries an `error_id` that identifies the request in CrossFX logs.

Base URLs#

Configure the API and token endpoints independently in your client. Sandbox serves both from the same host; Production separates them.
SANDBOX
One host for every path
API BASE URL
https://sandbox-api.crossfx.com/m1/1294314-1293362-default
The token endpoint is also served from this base. The Sandbox realm is sandbox.
PRODUCTION
API and authentication are separate
API BASE URL
https://api.crossfx.com
TOKEN ENDPOINT
https://sso.crossfx.com/realms/prod/protocol/openid-connect/token
Every path in the API Reference is relative to the API base URL for your environment.
PATH RULES
The API version is part of the path: /api/v1/.... It is never sent as a header.
The token path is /realms/{realm}/protocol/openid-connect/token.

Authentication#

CrossFX uses the OAuth 2.0 client-credentials grant.
01 · CREDENTIALS
Client ID + secret
Your application credentials
→
02 · TOKEN
Access token
Refresh before expires_in elapses
→
03 · API CALLS
Bearer authentication
Authorization: Bearer <access_token>
One access token authenticates the whole API.

401 and 403 mean different things#

401 · Unauthorized
Authentication failed
A missing, malformed, or expired token returns:

`{ "message": "Unauthorized" }`

**Action:** Request a new token and retry.
403 · AUTHORIZATION_FAILED
Authentication succeeded, permission did not
The token is valid, but the client does not hold permission for the operation.

**Action:** Do not retry. Contact support to confirm your integration's permissions.
Authentication Guide
The grant, token response and every error the token endpoint returns.
Get Access Token
POST /realms/{realm}/protocol/openid-connect/token

Request and response shapes#

The API uses JSON consistently, but there is deliberately no universal response wrapper.
Requests
JSON by default
Send `Content-Type: application/json` with a JSON body.

The token endpoint is the exception and takes form-encoded parameters.

Query parameters carry lookup filters; request bodies carry everything else.
Successful responses
Use the HTTP status
A single-resource response is the resource itself at the top level.

Do not unwrap `data` and do not look for `success` or `message` to confirm the outcome.
Types
Preserve API types
Amounts, rates and fees are decimal strings.

Timestamps are ISO-8601 UTC.

Status and enum values are lowercase and should be matched exactly.
NULL & OPTIONAL OBJECTS
An optional object such as a transfer's deposit or payout leg is null until it exists. Some nested objects are omitted from the response altogether rather than being returned as null.
APIs
Per-endpoint request and response schemas, with a console to call them from.
CrossFX API Documentation
The transfer, deposit and payout objects, and the order the calls run in.

Searching, filtering, and pagination#

Searchable resources follow a common contract. The resource's own API Reference page defines which filters, searchable fields and sort keys it supports.
SEARCH COLLECTION
POST {resource}/search
Filters, pagination, free-text search and sorting all go in the request body.
FETCH ONE
GET {resource}/{id}
Fetches a single resource by its identifier.
NOT PAGINATED
GET {resource}
This is never the paginated form.
Modified at 2026-09-11 12:03:51
Previous
Support & Contact
Next
Authentication Guide
Built with