Swift India Interbank Messaging API enables secure, digitized message exchange between Indian banks over Swift India network. To learn more about this API, see Swift India Interbank Messaging API overview. In this section, you will find the technical implementation details on how to integrate with this API.
Refer to the Swift India Interbank Messaging API Reference to help you integrate the API.
Looking for a faster and easier way to integrate? Consider using one of the developer tools designed to simplify the consumption of API-based services available on the Swift platform. Build your application with Swift SDK to help you with lower-level application plumbing, which includes authentication, authorisation, signing and error handling. Alternatively, consider using to configure, monitor all API calls you make on Swift and capture inbound API requests. Finally, is an option that provides reference implementations so that you can create your own SDK or utilities.
Not sure which tool is right for you? Try the connectivity option selector to get recommendations from our expert. After you select a tool, try setting it up in the API sandbox (available over the Internet) to quickly get started.
The SWIFT API Gateway generates an X-SwiftContext HTTP header, which contains a signed JWT that encapsulates consolidated user session information. The JWT consists of a set of JOSE headers and claims that provide identity and context details for the request.
To ensure the authenticity and integrity of the information, Service Providers must validate both the JWT signature and its contents before processing the request. By verifying the signed JWT, Service Providers can confirm that the user context has not been tampered with and originates from a trusted source. The JWT payload contains the consolidated user information for the session, securely packaged within the signed token.
The signed JWT token is a JOSE (JavaScript Object Signing and Encryption) JWS (JavaScript Web Signature) structure, comprising the following JOSE headers and claims:
{JOSE Header}.{JOSE Payload}.{JOSE Signature} Before validating the JWT payload, Service Providers must verify the JOSE header parameters to ensure that the token was generated by a trusted issuer and signed using the expected cryptographic algorithm. The following JOSE header attributes must be validated:
| Parameter | Description | Validation Requirement |
|---|---|---|
| typ | Type of the signed and encoded object. | Must be JWT. Reject the token if any other value is present. |
| alg | Cryptographic algorithm used to sign the JWT. | Must be RS256. Reject tokens signed using any other algorithm. |
| x5c | X.509 certificate chain containing the signer's public certificate. | Extract the public certificate and validate it against the SWIFT PKI trust chain. The certificate must be trusted, valid, and used to verify the JWT signature. |
After successful header verification, Service Providers should validate the claims contained in the JWT.
| Claim | Validation Requirement |
|---|---|
| iss | Verify that the issuer matches the expected environment: |
| aud | Must contain the hostname of the Bank Service Provider (resource owner) API. Verify that the audience matches the Service Provider API hostname configured for the service. Requests containing unexpected audience value should be rejected. |
| exp | Expiration time. Verify that the token has not expired. Requests containing expired tokens should be rejected. |
| iat | Token issued time. Verify that the token issuance time is within an acceptable time range and is not later than the current system time. |
| sub | Subject DN of the PKI certificate used for establishing OAuth2.0 session. Optionally verify that the certificate subject corresponds to an expected customer or organization, if such validation is required by the service. |
| requesterBIC | BIC corresponding to the PKI certificate. Verify that the requesterBIC is authorized to access the requested resource or operation according to the Service Provider's business authorization rules. |
| jti | Token identifier to provide uniqueness in UUID format. |
The JWT is signed by SWIFT using a SWIFT PKI certificate. SWIFT will provide the corresponding public certificate in the x5c header attribute that Service Providers can use to verify the JWT signature.
Before trusting any information contained in the token, Service Providers should:
Successful signature verification confirms that:
Since the X-SwiftContext token is cached by the SWIFT API Gateway for the duration of a user's active session, Service Providers may receive the same JWT across multiple API requests within that session. As a result, claims that were previously unique to each generated token—such as jti (JWT ID) and iat (Issued At) — should no longer be considered unique on a per-request basis. These claim values may remain unchanged across multiple requests because the same signed JWT can be reused while it is retained in the gateway cache.
This validation process ensures that the identity and authorization context provided by SWIFT can be trusted while accommodating the reuse of cached tokens during their validity period.
The Pilot environment closely resembles the Live environment, and it is intended to fully qualify your API integration, follow the steps below to access the Pilot testing environment.
Place the order Swift India Interbank Messaging API Subscription and Change for Consumers for Pilot service on Swift.com.
Create a dedicated app for testing in the Pilot environment and select Swift India Interbank Messaging API from the list of API products. Inside the app are consumer-key and consumer-secret which are the application credentials used to identify the application calling the API. After creating the app, promote the app to the Pilot environment.
The Swift India Interbank Messaging API supports the use of Business certificates and Channel certificates when signing the JWT in the authorisation API call. After creating the certificate, assign the RBAC role swift.messaging.api.in!p to the certificate.
This step should be completed by a security officerClick to learn more about SWIFTNet PKI Security Officer registration in the Knowledge Centre..
After completing the steps above, you now have the credentials you need to access the Swift India Interbank Messaging API in the Pilot environment. Refer to Authentication to learn how to use the credentials you created above to start testing your integration with this API in Pilot.
After successfully testing the Swift India Interbank Messaging API in Pilot, follow the steps below to start using this API in Live.
Place the order Swift India Interbank Messaging API Subscription and Change for Consumers for Live service on Swift.com.
Promote the app you created to the Live environment or create a new app for the Live environment. If you decided to create a new app, select Swift India Interbank Messaging API from the list of API products. After the app is created, promote the app to the Live environment.
You should promote the app to Pilot first and then Live.
Follow the same process for creating the certificate for Pilot testing. The Swift India Interbank Messaging API supports the use of Business certificates and Channel certificates when signing the JWT in the authorisation API call. After the certificate is created, assign the RBAC role swift.messaging.api.in to the certificate for Live.
This step should be completed by a security officerClick to learn more about SWIFTNet PKI Security Officer registration in the Knowledge Centre..
Swap out the credentials you used for Pilot with Live credentials and start using the Swift India Interbank Messaging API in your Live applications. When in doubt, refer to Authentication to learn how to use your Live credentials to access this API in Live.
Place the order Swift India Interbank Messaging API Subscription and Change for Data Providers for Pilot service on Swift.com.
We recommend the following to be performed by the technical development team in your company.
Refer to the steps defined in Web Server Configurations for Data Providers to deploy your API service in the Pilot environment.
Make sure your application or the application provided by your software vendor can:
After successfully testing the Swift India Interbank Messaging API in Pilot with your API clients, follow the steps below to start providing the API in Live.
Place the order Swift India Interbank Messaging API Subscription and Change for Data Providers for Live service on Swift.com. Complete the order details by providing your BIC and implementation date from dropdowns.
Refer to the steps defined in Web Server Configurations for Data Providers to deploy your API service in the Live environment.
Once the Live service is provisioned, you can complete additional testing with your API clients to ensure you get the expected results in the Live environment.