Community FX API
Previous page Request For Information API Reference
Next pageAuthentication
Community FX API is the pre-payment FX quoting interface between Debtor Agent (DA) banks and Gateway Intermediary (GI) banks. DA banks call this API to obtain a locked FX rate from a GI before constructing the pacs.008 payment message. The API returns rates, fees, delivery estimates, and instrument options so that DA banks can present a complete cost summary to the debtor before authorisation.
In this section you will find the technical implementation details for integrating with Community FX API as a Consumer (DA bank) or as a Provider (GI bank).
Refer to the Community FX API Reference to help you integrate this API.
Consider using one of the developer tools designed to simplify integration with API-based services on the Swift platform.
Not sure which tool is right for you? Try the connectivity option selector for a recommendation.
The Community FX API Sandbox returns static sample responses and does not contain application logic. Use it to:
You can view, fork or download the Postman collection which includes authentication API calls and sample Community FX API calls. Also refer to access sandbox where dedicated sandbox credentials are provided. To start testing in the sandbox, create an app and select "Community FX API".
The Pilot environment aims to test production like transactions against a real counterparty, and it is intended to fully qualify your API integration. Follow the steps below to access the Community FX API Pilot testing environment.
Place the order for Community FX API for Providers on Swift.com. Provide your BIC and implementation date in the order details.
Your technical team should complete the following:
Endpoints your service must implement:
| Method | Paths | Your service must |
|---|---|---|
| POST | /quotes | Accept quote requests. Return one or more FxQuote objects with locked rates, fees conversion_fee, delivery estimates, and a time-to-live. Return at most 20 quotes per request when instrument_type=all. |
| GET | /quotes/{quote_id} | Return a previously issued quote by its ID. Reflect current status ( active or expired). Set ttl_seconds to 0 for expired quotes. |
| GET | /corridors | Return corridor records matching the caller's filters ( source_currency, destination_currency, destination_country, instrument_type). Support offset/ limit pagination. |
| GET | /corridors/{corridor_id} | Return a single corridor record by its unique ID. |
Key implementation requirements:
Refer to Web Server Configurations for Data Providers to deploy your API service in the Pilot environment.
Confirm that your service can:
After successful Pilot testing with your DA bank consumers, follow these steps.
Place the order for Community FX API for Providers on Swift.com. Provide your BIC and implementation date in the order details.
Refer to Web Server Configurations for Data Providers to deploy your API service in the Live environment.
Once the Live service is provisioned, complete additional testing with your DA bank consumers to verify expected results in the Live environment.
The Pilot environment tests production-like transactions against a real GI counterparty and is intended to fully qualify your integration.
Place the order for Community FX API for Consumenrs on Swift.com. Provide your BIC and implementation date in the order details.
Create a dedicated app for the Pilot environment and select Community FX API from the list of API products. The app contains a consumer-key and consumer-secret which identify your application when calling the API. After creating the app, promote it to the Pilot environment.
Community FX API supports Business certificates and Channel certificates when signing the JWT in the authorisation API call. After creating the certificate, assign the RBAC role swift.fxcommunity.api!p to the certificate for Pilot.
This step must be done by a security officerAlliance Lite2 Customer Security Officer. Click to learn more on Swift.com..
You now have the credentials to access Community FX API in Pilot. Refer to Authentication for details on obtaining and using access tokens.
Pilot base URL: https://api-test.swiftnet.sipn.swift.com/swift/community-fx/v1
A recommended first test sequence:
Agree with your GI counterparty on acceptance criteria. At minimum, your application should request quotes, retrieve them, handle expired quotes, and process error responses 400, 401, 403, 404, 429, 503, 504).
After successful Pilot testing, follow these steps to use Community FX API in Live.
Place the order for Community FX API for Consumers on Swift.com.
Promote your Pilot app to the Live environment, or create a new app and select Community FX API. After creating or promoting the app, ensure it is active in the Live environment.
You must promote the app to Pilot first, then Live.
Follow the same certificate creation process used for Pilot. Assign the RBAC role swift.fxcommunity.api to the certificate for Live.
This step must be done by a security officerAlliance Lite2 Customer Security Officer. Click to learn more on Swift.com..
Swap Pilot credentials for Live credentials and start using Community FX API in your Live applications. Refer to Authentication for credential configuration.