SEPA/IBAN Payments

SEPA (Single Euro Payments Area) enables standardized euro-denominated payments across participating European countries using IBANs (International Bank Account Numbers). Platforms that process SEPA payments—such as payment service providers, digital banks, or financial infrastructure providers—must ensure these transactions meet regulatory compliance and anti-financial crime requirements.

This guide outlines how to use Flagright’s API to support compliance and monitoring for SEPA/IBAN payment flows. It covers entity onboarding, common transaction scenarios (e.g., consumer-to-consumer, business-to-consumer), response handling, best practices, and implementation flow. 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 SEPA payments, complete the following setup steps to ensure a smooth integration. These steps apply to both sandbox and production environments:

1. 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.

2. 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.

3. 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 SEPA transactions, as demonstrated in the following sections.

Setting up entities

Business Onboarding

When a business entity joins your platform to send or receive SEPA payments, create them using the Create Business User endpoint (POST /business/users). This sends user data for KYB and risk assessment.

curl -X POST https://sandbox.api.flagright.com/business/users 
    -H "x-api-key: <apiKey>" \\
    -H "Content-Type: application/json" \\
    -d '{
    "userId": "business_12345",
    "createdTimestamp": 1741654664000,
    "legalEntity": {
        "companyGeneralDetails": {
            "legalName": "EuroTrade GmbH",
            "businessIndustry": ["Retail"],
            "mainProductsServicesSold": ["Electronics"]
        },
        "companyFinancialDetails": {
            "expectedTransactionAmountPerMonth": {
                "amountValue": 50000,
                "amountCurrency": "EUR"
            }
        },
        "companyRegistrationDetails": {
            "registrationIdentifier": "DE12345678",
            "registrationCountry": "DE"
        }
    },
    "shareHolders": [
        {
            "generalDetails": {
                "name": {
                    "firstName": "Hans",
                    "lastName": "Schmidt"
                },
                "dateOfBirth": "1980-05-15",
                "countryOfResidence": "DE",
                "countryOfNationality": "DE"
            },
            "contactDetails": {
                "emailIds": ["hans@eurotrade.de"],
                "contactNumbers": ["+49 123456789"],
                "addresses": [
                    {
                        "addressLines": ["Hauptstrasse 123"],
                        "city": "Berlin",
                        "country": "Germany",
                        "postcode": "10115",
                        "state": "Berlin"
                    }
                ]
            }
        }
    ]
}'

Consumer User Onboarding

For individual consumer users making or receiving SEPA payments, create users via the Create Consumer User endpoint (POST /consumer/users). This handles KYC data.

curl -X POST https://sandbox.api.flagright.com/consumer/users
    -H "x-api-key: <apiKey>" \\
    -H "Content-Type: application/json" \\
    -d '{
  "createdTimestamp": 1754112000000,
  "userId": "96647cfd9e8fe66ee0f3362e011e34e8",
  "contactDetails": {
    "emailIds": [
      "alex@example.com"
    ],
    "contactNumbers": [
      "+447123456789"
    ],
    "websites": [
      "example.com"
    ]
  },
  "legalDocuments": [
    {
      "documentType": "passport",
      "documentNumber": "P1234567",
      "documentIssuedCountry": "GB",
      "documentIssuedDate": 1612843034000,
      "documentExpirationDate": 1739149034000,
      "nameOnDocument": {
        "firstName": "Alex",
        "middleName": "John",
        "lastName": "Smith"
      }
    }
  ],
  "userDetails": {
    "name": {
      "firstName": "Alex",
      "middleName": "John",
      "lastName": "Smith"
    },
    "dateOfBirth": "1985-07-15",
    "countryOfResidence": "GB",
    "countryOfNationality": "GB"
  }
}'

SEPA/IBAN Transaction Scenarios

Transactions represent value transfers (e.g., deposits, withdrawals). Use the Verify Transaction endpoint (POST /transactions) to monitor them before processing. Include timestamps in UNIX milliseconds, user IDs (omit for external parties), amounts in EUR, and IBAN/BIC details.

1. Incoming SEPA Transaction

For an incoming transfer from an external account to your account holder (e.g., deposit), omit originUserId and set destinationUserId to your user’s ID.

curl -X POST https://sandbox.api.flagright.com/transactions \
     -H "x-api-key: " \
     -H "Content-Type: application/json" \
     -d'{
    "transactionId": "sepa_trans_123456",
    "type": "DEPOSIT",
    "destinationUserId": "user_24680",
    "originAmountDetails": {
        "country": "BG",
        "transactionAmount": 15000,
        "transactionCurrency": "EUR"
    },
    "destinationAmountDetails": {
        "country": "ES",
        "transactionAmount": 15000,
        "transactionCurrency": "EUR"
    },
    "timestamp": 1741654664000,
    "originPaymentDetails": {
        "method": "IBAN",
        "IBAN": "BG80UNCR76301234567890",
        "BIC": "UNCRBGSFXXX",
        "bankName": "UniCredit Bulbank"
    },
    "destinationPaymentDetails": {
        "method": "IBAN",
        "IBAN": "ES9121000418450200051332",
        "BIC": "CAIXESBBXXX",
        "bankName": "La Caixa"
    }
}'

2. Outgoing SEPA Payment

For an outgoing transfer from your account holder to an external account (e.g., withdrawal), set originUserId to your user’s ID and omit destinationUserId.

curl -X POST https://sandbox.api.flagright.com/transactions \
     -H "x-api-key: " \
     -H "Content-Type: application/json" \
     -d '{
    "transactionId": "sepa_salary_789012",
    "type": "WITHDRAWAL",
    "originUserId": "business_12345",
    "originAmountDetails": {
        "country": "BG",
        "transactionAmount": 32000,
        "transactionCurrency": "EUR"
    },
    "destinationAmountDetails": {
        "country": "FR",
        "transactionAmount": 32000,
        "transactionCurrency": "EUR"
    },
    "timestamp": 1741654664000,
    "originPaymentDetails": {
        "method": "IBAN",
        "IBAN": "BG80UNCR76301234567890",
        "BIC": "UNCRBGSFXXX",
        "bankName": "UniCredit Bulbank"
    },
    "destinationPaymentDetails": {
        "method": "IBAN",
        "IBAN": "FR7630006000011234567890189",
        "BIC": "AGRIFRPP",
        "bankName": "Credit Agricole"
    }
}'

3. Cross-Border SEPA Payment to Non-Euro Country

For a transfer to a non-euro SEPA country (e.g., Sweden), set originUserId and omit destinationUserId for external recipients.

curl -X POST https://sandbox.api.flagright.com/transactions \
     -H "x-api-key: " \
     -H "Content-Type: application/json" \
     -d'{
    "transactionId": "sepa_crossborder_901234",
    "type": "TRANSFER",
    "originUserId": "user_67890",
    "originAmountDetails": {
        "country": "BG",
        "transactionAmount": 25000,
        "transactionCurrency": "EUR"
    },
    "destinationAmountDetails": {
        "country": "SE",
        "transactionAmount": 25000,
        "transactionCurrency": "EUR"
    },
    "timestamp": 1741654664000,
    "originPaymentDetails": {
        "method": "IBAN",
        "IBAN": "BG80UNCR76301234567890",
        "BIC": "UNCRBGSFXXX",
        "bankName": "UniCredit Bulbank"
    },
    "destinationPaymentDetails": {
        "method": "IBAN",
        "IBAN": "SE4550000000058398257466",
        "BIC": "ESSESESS",
        "bankName": "SEB"
    }
}'

Response Structure

Responses include JSON with risk assessment details. Key fields:

1. Transaction status (ALLOW, FLAG, SUSPEND, BLOCK)

2. riskScoreDetails for risk scores/levels

3. executedRules: All evaluated rules

4. hitRules: Triggered rules

Example response for an incoming transaction (aligned with the first scenario, assuming a high-risk origin country and large amount trigger):

{
    "transactionId": "sepa_trans_123456",
    "executedRules": [
        {
            "ruleId": "R-14",
            "ruleInstanceId": "R-14.1",
            "ruleName": "High risk country",
            "ruleDescription": "Transaction to or from a country that is designated as high risk. This rule uses a customizable list",
            "ruleAction": "SUSPEND",
            "ruleHit": true,
            "labels": [
                "UNEXPECTED_BEHAVIOR"
            ],
            "nature": "AML",
            "executedAt": 1754112000000,
            "ruleHitMeta": {
                "hitDirections": [
                    "ORIGIN"
                ]
            },
            "vars": [
                {
                    "direction": "ORIGIN",
                    "value": {
                        "TRANSACTION:originAmountDetails-country": "BG"
                    }
                }
            ],
            "isShadow": false
        },
        {
            "ruleId": "R-169",
            "ruleInstanceId": "R-169.4",
            "ruleName": "Tx’s counterparty screening",
            "ruleDescription": "Screening transaction’s counterparty for Sanctions/PEP/Adverse media",
            "ruleAction": "FLAG",
            "ruleHit": false,
            "labels": [],
            "nature": "SCREENING",
            "executedAt": 1754112000000,
            "isShadow": false
        },
        {
            "ruleId": "R-2",
            "ruleInstanceId": "R-2.1",
            "ruleName": "HK-2 Amount",
            "ruleDescription": "Transaction amount is >= 10000 in USD or equivalent",
            "ruleAction": "FLAG",
            "ruleHit": true,
            "labels": [
                "EDD_TRIGGER",
                "UNEXPECTED_BEHAVIOR"
            ],
            "nature": "AML",
            "executedAt": 1754112000000,
            "ruleHitMeta": {
                "hitDirections": [
                    "ORIGIN",
                    "DESTINATION"
                ]
            },
            "vars": [
                {
                    "direction": "ORIGIN",
                    "value": {
                        "TRANSACTION:originAmountDetails-transactionAmount": 15000
                    }
                }
            ],
            "isShadow": false
        }   
    ],
    "hitRules": [
        {
            "ruleId": "R-14",
            "ruleInstanceId": "R-14.1",
            "ruleName": "High risk country",
            "ruleDescription": "Transaction to or from a country that is designated as high risk. This rule uses a customizable list",
            "ruleAction": "SUSPEND",
            "ruleHitMeta": {
                "hitDirections": [
                    "ORIGIN"
                ]
            },
            "labels": [
                "UNEXPECTED_BEHAVIOR"
            ],
            "nature": "AML",
            "isShadow": false,
            "executedAt": 1754112000000
        },
        {
            "ruleId": "R-2",
            "ruleInstanceId": "R-2.1",
            "ruleName": "HK-2 Amount",
            "ruleDescription": "Transaction amount is >= 10000 in USD or equivalent",
            "ruleAction": "FLAG",
            "ruleHitMeta": {
                "hitDirections": [
                    "ORIGIN",
                    "DESTINATION"
                ]
            },
            "labels": [
                "EDD_TRIGGER",
                "UNEXPECTED_BEHAVIOR"
            ],
            "nature": "AML",
            "isShadow": false,
            "executedAt": 1754112000000
        }
    ],
    "status": "SUSPEND",
    "riskScoreDetails": {
        "trsScore": 40,
        "trsRiskLevel": "MEDIUM",
        "originUserCraRiskLevel": "HIGH",
        "destinationUserCraRiskLevel": "VERY_HIGH",
        "originUserCraRiskScore": 63.724137931034484,
        "destinationUserCraRiskScore": 90
    }
}

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 evaluated rules:

FieldDescriptionExample ValueruleIdUnique identifier”R-14”ruleNameConsole-defined name“High risk country”ruleDescriptionConsole-defined description”Transaction to or from a country that is designated as high risk”ruleActionAction if hit (FLAG, SUSPEND, BLOCK)“SUSPEND”ruleHitTriggered (true/false)truenatureCategory (e.g., AML, FRAUD, SCREENING)“AML”labelsTags for actions[“UNEXPECTED_BEHAVIOR”]

Hit Rules

The hitRules array lists only triggered rules. In the example, the “High risk country” rule hit due to the origin country (Bulgaria) being high-risk, and the amount rule hit for exceeding the threshold.

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:

1. Identify events and payloads.

2. Create an HTTPS endpoint on your server.

3. Handle requests by parsing events and returning 2xx status.

4. Deploy the endpoint publicly.

5. 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.

1. Pre-Transaction:

   • Call the Flagright Transactions API (POST /transactions) before executing the SEPA 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.

2. 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 SEPA 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)

On failures (e.g., 400 for invalid payload or 401 for invalid API key), check the response for error details. Default to SUSPEND or BLOCK for safety in production.