SWIFT Payments Integration Guide with Flagright API
In the cross-border payments landscape, SWIFT transfers remain a core method for moving funds across jurisdictions and currencies. Financial institutions, fintechs, and payment service providers must ensure that such transfers are continuously monitored for compliance, AML risk, and fraud prevention. This guide demonstrates how to use Flagright’s real-time API infrastructure to implement robust compliance workflows for both inbound and outbound SWIFT payments, using a generic payments provider as the baseline integration model.
The integration connects your User Onboarding (KYC/KYB) system and Core Transaction Processing system to Flagright’s endpoints, ensuring secure data exchange via REST API and webhooks.
For full API details, refer to Flagright’s API Reference.
Prerequisites
Before using the Flagright API for real-time transaction monitoring of SWIFT payments, complete the following setup steps to ensure a smooth integration. These steps apply to both sandbox and production environments:
-
Security and authentication
-
Get the API key in the Flagright console
-
Include the API key in the x-api-key header of all requests, as shown in the example below.
-
All API requests must use HTTPS; plain HTTP calls will fail. Authenticate requests with an API key retrieved from the Flagright console’s developer settings page. Store the key securely in a secrets manager or digital vault, as it can only be retrieved twice.
-
Set up /consumer/users, /business/users, /transactions, and /events endpoints in your systems. Refer to https://docs.flagright.com/api-reference/introduction/getting-started for setup.
-
-
Set up Rules and Risk factor configurations:
-
Configure your Risk factors in the Flagright console to define behaviors for transaction monitoring (e.g., high-risk country checks, amount thresholds, or fraud detection).
-
Rules like “High risk country” or “Transaction amount >= 10000 USD” (as shown in the example response) must be set up to trigger appropriate actions (ALLOW, FLAG, SUSPEND, BLOCK).
-
Contact your Customer Success Manager or refer to the Rules and Risk factors configuration guide in the Knowledge base for customization.
-
-
Prepare payment data:
-
Collect and format payment details as required by the originPaymentDetails or destinationPaymentDetails object.
-
Ensure compliance with payment standards.
-
By completing these steps, you’ll be ready to integrate the Flagright API for real-time verification of SWIFT transactions, as demonstrated in the following sections.
Setting Up Entities
Business Onboarding
Business users—entities initiating or receiving SWIFT transactions—are represented as Business entity in the Flagright API. Create them using the Create Business User endpoint (POST /business/users). This handles KYB data.
Consumer User Onboarding
Consumer users—individuals who are initiating or receiving SWIFT transactions—are represented as Consumer entity in the Flagright API. Create them using the Create Consumer User endpoint (POST /consumer/users). This handles KYC data.
SWIFT Transaction Scenarios
For SWIFT payments, there are typically two types of transactions. Use the Verify Transaction endpoint (POST /transactions) to monitor them before processing. Include timestamps in UNIX milliseconds, user IDs (omit for external parties), amounts/currencies, and SWIFT details (e.g., BIC/SWIFT code, account number).
1. Outbound SWIFT Transfer
An outbound SWIFT transfer is when a user initiates a transfer from their account to an external beneficiary, typically in another country.
For outbound transfers, the origin payment method is typically a bank account or wallet belonging to your user, and the destination payment method is the SWIFT details of the beneficiary. In this case, the originUserId would be the userId of your customer initiating the transfer.
The destinationUserId typically would be empty since the beneficiary is not your customer. If you perform KYC on the beneficiary and have information on them, you can pass in the consumer userId as the destinationUserId.
2. Inbound SWIFT Transfer
An inbound SWIFT transfer is when your user receives a payment from an external sender, typically from another country.
For inbound transfers, the destination payment method is typically the bank account or wallet of your user, and the origin payment method is the SWIFT details of the sender. In this case, the destinationUserId would be the userId of your customer receiving the transfer.
The originUserId typically would be empty since the sender is not your customer. If you perform KYC on the sender and have information on them, you can pass in the consumer userId as the originUserId.
Response Structure
The API response contains comprehensive risk assessment information, including:
-
Transaction status (ALLOW, FLAG, SUSPEND, BLOCK)
-
Risk scores and risk levels
-
Executed rules with detailed information
-
Specific rules that were triggered for the transaction
The response is consistent across all flow types. Here’s an example for the outbound transfer payload (aligned with the first scenario, assuming a high-risk origin country and large amount trigger):
Here’s an example for the outbound transaction payload (aligned with the first scenario, assuming a high-risk origin country and large amount trigger):
Understanding the Response
Transaction Status
The status field in the response indicates the action you should take for the transaction:
-
ALLOW: The transaction is considered safe and can be processed
-
FLAG: The transaction can be processed but has been flagged for review under one or more alerts.
-
SUSPEND: The transaction should be temporarily suspended pending further verification. This status typically requires manual investigation (e.g., via the Flagright console) and subsequent approval (to proceed) or block. Set up webhooks to receive real-time notifications for SUSPEND events, enabling automated alerts for your compliance team. For details on configuring webhooks, refer to the webhooks section of the API docs.
-
BLOCK: The transaction should be blocked as it poses high risk.
The statuses can be configured in the Flagright console and have a hierarchy: BLOCK > SUSPEND > FLAG > ALLOW. The highest-priority action from hit rules determines the final status. In this example, the status is SUSPEND because the high-risk country rule which triggers the action SUSPEND has a higher priority than the second rule that was hit which triggers the action FLAG.
Risk Scores
The riskScoreDetails section provides comprehensive risk assessment information:
-
trsScore: Transaction Risk Score on a scale of 0-100 (40 in this example, indicating MEDIUM risk)
-
trsRiskLevel: Risk level categorization (VERY_LOW, LOW, MEDIUM, HIGH, VERY_HIGH)
-
originUserCraRiskLevel/Score: Risk assessment for the sending user
-
destinationUserCraRiskLevel/Score: Risk assessment for the receiving user
Rule Execution
The executedRules array lists all rules that were evaluated for the transaction:
FieldDescriptionExample ValueruleIdUnique rule identifier”R-14”ruleNameRule name as entered via Flagright Console UI“High risk country”ruleDescriptionRule description as entered via Flagright Console UI”Transaction to or from a country that is designated as high risk”ruleActionRecommended action if hit”SUSPEND”ruleHitWhether the rule was triggered for this transactiontruenatureRule category (e.g., AML, FRAUD, SCREENING)“AML”labelsContextual tags which can be used to trigger other actions[“UNEXPECTED_BEHAVIOR”]
Hit Rules
The hitRules array contains only the rules that were triggered for the transaction. In our example, the “High risk country” rule was triggered because the origin country (Bulgaria) is marked as high-risk in the system’s configuration.
Updating Entities and Transactions
Use the Create Transaction Event endpoint (POST /events/transactions) to update transaction states (e.g., “SUCCESSFUL”, “REJECTED”) post-verification. Transaction events encapsulate changes in status (e.g., from “CREATED” by default to other states).
For user updates (e.g., status changes), use user events endpoints. User events for consumers capture significant changes like account creation, modification, or verification status updates. Business events focus on activities like account setups, transaction monitoring for compliance, or changes in business operation details.
These events are crucial for tracking user engagement and compliance, and can trigger notifications or automated workflows.
Webhook Integration
Webhooks notify your system of events from Flagright (e.g., user/transaction state changes, new alerts, case closures). Setup steps:
-
Identify events and payloads.
-
Create an HTTPS endpoint on your server.
-
Handle requests by parsing events and returning 2xx status.
-
Deploy the endpoint publicly.
-
Register the URL in the Flagright console and select events.
Verify webhook signatures using HMAC-SHA256 with your signing secret (from console) and the request body. This ensures authenticity.
Data and Implementation Flow
Data flows via API from your systems to Flagright (e.g., user/transaction data) for processing, with responses guiding actions. Webhooks flow from Flagright to your systems for operational updates triggered by console actions, such as rule hits, status changes, or alert creations.
-
Pre-Transaction:
-
Call the Flagright Transactions API (POST /transactions) before executing the SWIFT payment to send transaction details and receive real-time risk assessment.
-
Review the response: The status field indicates the action (hierarchy: BLOCK > SUSPEND > FLAG > ALLOW). For SUSPEND or BLOCK, hold or decline the payment; for ALLOW or FLAG, proceed while noting any flags for review.
-
Process approved transactions (ALLOW/FLAG) in your core system.
-
-
Post-Transaction:
-
For approved transactions, update the status (e.g., “SUCCESSFUL” or “REJECTED”) via the Transaction Events API (POST /events/transactions) to complete lifecycle tracking.
-
Report any failed, rejected, or post-approval changes back to Flagright through events for ongoing monitoring and compliance.
-
This flow ensures seamless integration, maintaining regulatory compliance while enabling efficient SWIFT payments across borders. Use webhooks (as detailed in the Webhook Integration section) for real-time notifications on post-transaction events, such as SUSPEND resolutions or alert closures, to close the operational loop.
Error Handling
API response codes include:
-
200: Successful
-
400: Bad request (invalid payload)
-
401: Unauthorized (invalid API key)
-
403: Forbidden (wrong authentication)
-
429: Too many requests (rate limit reached)
-
500: Server error (contact Flagright support)
If the API call fails (e.g., 400 Bad Request for invalid payload or 401 Unauthorized for invalid API key), check the response for error details. Default to SUSPEND or BLOCK for safety in production.