SWIFT Developer Portal | Swift API Reference

APIs

Reference

Introduction

Welcome! This reference page lists our APIs and the detailed documentations pertained to each. Our APIs implement REST with standard HTTP codes, verbs and authentication methods and they are documented using the OpenAPI 3.0 standard. Read on to get more information about our API guidelines!

Authentication

OAuth 2.0 is an industry standard used to protect access to APIs. SWIFT OAuth Token API is used to issue tokens needed to access other SWIFT API products. Depending on the API product you are trying to access, you will be using one of the two types of OAuth, Password Grant Type or JWT Bearer Token Grant Type. Check the securitySchemes defined in the OpenAPI specification to find out which grant type and credential you should use for the API you want to consume.

Versions

SWIFT uses semantic versioning for our APIs. We will bump up the MAJOR version when a "breaking change" is made to the API, MINOR version number will be incremented when a functional "non-breaking change" is made to the API and "PATCH" version number will be incremented when a bug fix "non-breaking change" is made to the API.

We adopted the URI versioning approach where MAJOR version number is expected to be in the URL.

Errors

SWIFT uses industry best practices to handle errors. You can expect three outcomes when interacting with our APIs. HTTP status code 2XX indicates success, 4XX indicates an error due to information provided by the client application, 5XX indicates an error with the server.

Pagination

When making an API call to a resource like /payments/changed/transactions, the number of results returned can be very large. To make results easier to handle and to reduce latency and the amount of bandwidth consumed, results are paginated.

There are two pagination behaviors supported by SWIFT APIs. GPI APIs support maximum_number and next query parameters. If there are more resource objects to be fetched than permitted by maximum_number, a next token is returned to fetch the next set of resource objects. Other SWIFT APIs support limit and offset query parameters. If there are more resource objects to be fetched than permitted by limit, a next key is returned whose value is a subpath to be used in the subsequent request. Additional keys are also returned such as self, previous, first, last and pageof.

Now you have everything you need to know about our API guidelines, be sure to check out the next section Getting Started with a step-by-step guide on how to kick off your SWIFT API journey!

Getting Started

Step 1: Browse our APIs

SWIFT offers a range of API products that help remove the friction from global transactions. You can find the APIs in the API Catalogue and a number of API use cases in the API Playground to help you find the APIs that best suit your needs.

Step 2: Create your App

Creating your own application allows you to generate a set of credentials to access the API products in the sandbox and production environments.

Create an account
If you have an account on SWIFT.com, you can use it to sign in directly.
Create an App
We recommend one API product per App.

You are responsible for securing your credentials on your premises and within your client applications. Application credentials are exchanged via the Basic Authentication Scheme in the Authorization Header. You will find more information in the SWIFT OAuth Token API page.

Once you create an App, its status will be set to “Sandbox” and its credentials can be used to access API products in the sandbox environment. You can promote your application to the production environments when you are ready.

Step 3: Making calls to APIs in the Sandbox

You can try all API products in the freely accessible sandbox environment using the application credentials from the app you created and the sandbox credentials that are provided to you below. Sandbox APIs implement the same OpenAPI specifications used for Live APIs to ensure a similar integration experience. Please note that, for the moment, not all sandbox APIs cover the full set of business scenarios.

When generating an OAuth token to access the sandbox APIs, use the following sandbox credentials:

Sandbox License ID: sandbox-id
Sandbox License Secret: sandbox-key
Sandbox Self-signed Certificate: demo.jks

Find more information on how to use these credentials to generate an OAuth token in the SWIFT OAuth Token API page.

To help you get started quickly, check out the tutorial videos and postman collections that are embedded with sandbox URL, authentication, API requests and postman tests to help you test with the scenarios covered in the sandbox environment. You can download the postman collection via the Run in Postman button.

Step 4: Promote your App to live!

When you’re ready to use the APIs in the production environment, you can promote your App from the SWIFT Developer Portal.

To do this, you can choose one of the options listed below depending on the API product you have selected in your App.

If your app contains an API product (i.e. GPI API) that authenticates and authorises using OAuth - JWT bearer grant type:

Go to Contact Us
Choose Request to promote App as Subject from the dropdown list
Enter your app name and specify the environment (Pilot or Live) to which the app should be promoted
Click Submit

If your app contains an API product (i.e.KYC Registry API) that authenticates and authorises using OAuth - Password grant type:

Go to My Apps
Select the App you want to Promote
Click Promote App
Verify information in the pop up window
To confirm, click Promote

SDK

Build your application with SWIFT SDK to make coding easier. SWIFT SDK takes care of the lower-level plumbing including authentication, authorization, signing and error handling. In addition, it provides a number of value-added services such as schema validation, monitoring, end-to-end testing and ready to use API use cases. SWIFT SDK currently supports APIs for accessing customer credit transfer, instant payments, stop and recall, case resolution, cover payments, financial institution transfer, gpi for corporates, pay and trace, inbound payments, pre-validation, KYC Registry, SWIFTRef, SWIFTRef Automated Download, Banking Analytics and Compliance Analytics services.

Microgateway

Use SWIFT Microgateway to benefit from the full range of API-based services available on SWIFT. SWIFT Microgateway is a software product that allows firms to configure, manage, and monitor all API calls they make on the platform. In the future, the Microgateway will enable you to expose your own APIs on SWIFT, allowing you to offer your services to our unique community of more than 11,000 financial institutions located in over 200 countries.

GPI

Overview

APIs in this category are offered via the secure SWIFT network (MV-SIPN). Access to highly confidential GPI data requires API client to estabilish a secure session with the API service via the following options: SWIFT SDK and SWIFT Microgateway for API v4 or higher, gpi Connector for API v3 or lower.

gpi API

gpi v3 will be deprecated with the release of gpi v5. Find more information in gpi API release policy and versioning.

This set of APIs provide operations for financial institutions to access and update payment transaction information.

Try the APIs in the sandbox with Postman or clone the gpi v4 demo app.

SLVP API

The SWIFT for Low value cross-border payments (SLVP) API enables SLVP participants to provide status updates via API to the SWIFT gpi Tracker for their SLVP transactions.

g4C API

The API documentation provides detailed information on how to retrieve a corporate payment transaction using API.

gCase API

These APIs allow beneficiary and intermediary banks to manage case investigations quickly, reducing the number of manual queries.

Pre-Validation

Overview

APIs in this category are offered via the internet and the secure SWIFT network (MV-SIPN).

Payment Pre-validation

Payment Pre-validation Data Provider

Compliance

Overview

APIs in this category are offered via the internet.

SWIFT KYC Registry API

Check KYC Registry API Sandbox Guide to learn more about the sandbox.

Compliance Analytics API

The Compliance Analytics API allows you to programmatically access your Compliance Analytics data and automate your financial crime-related use cases.

RefData

Overview

APIs in this category are offered via the internet.

SWIFTRef API

The API documentation provides detailed information on how to retrieve reference data using APIs.

Business Intelligence

Overview

APIs in this category are offered via the internet.

Banking Analytics API

SWIFT Banking Analytics API enables institutions to retrieve their own SWIFT traffic data and the SWIFT totals, extending to the level of value and currency per market.

Banking Analytics Premium API

The Banking Analytics Premium API services will allow you to compare charging and other practices against the market, understand your sales performance in different markets and rank it over time, and finally use Letter of Credit confirmations and tenor data to assess your competitiveness in key markets.

Observer Analytics API

The Observer Analytics API enables institutions to access and integrate payments data enriched with Observer computation on speed, fees, end-to-end routing, gpi KPIs, and SWIFT Totals per market.

Notification Service

Notification API

The Notification API allows clients to subscribe and receive notifications to the SWIFT services they use via multiple delivery channel(s).