Use cases

Card Payments Integration Guide with Flagright API

Let’s take an example of a card payment to see how the Flagright API can be seamlessly used as the compliance and anti-financial crime infrastructure for real-time transaction monitoring. This guide covers various card-related use cases, structured around three common real-world flows:

  • User to External Party (Outgoing): Funds leaving a user’s card to an external entity (e.g., merchant or third-party account).
  • External Party to User (Incoming): Funds entering a user’s account from an external card or source.
  • User to User (Internal): Transfers between users within the platform using cards.

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.

Prerequisites

Before using the Flagright API for real-time transaction monitoring of card 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 card-specific 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 card payment data:
    • Collect and format card payment details as required by the originPaymentDetails or destinationPaymentDetails object, such as cardFingerprint, cardBrand, cardLast4Digits etc.
    • Ensure compliance with payment standards (e.g., ISO 8583 for posDetails.entryMode) and include optional fields like 3dsDone or cardAuthenticated for enhanced fraud detection.

By completing these steps, you’ll be ready to integrate the Flagright API for real-time verification of card transactions, as demonstrated in the following sections.

Setting Up Entities

Business Onboarding

When a business entity joins your platform to send or receive card 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@aseantrade.sg"],
                "contactNumbers": ["+49 123456789"],
                "addresses": [
                    {
                        "addressLines": ["Klara-Franke Str 20"],
                        "city": "Berlin",
                        "country": "Germany",
                        "postcode": "10557",
                        "state": "Berlin"
                    }
                ]
            }
        }
    ]
}'

Consumer User Onboarding

For individual consumer users making or receiving card 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 '{
          "userId": "Id2345",
          "createdTimestamp": 1741654664000,
          "userDetails": {
            "name": {
              "firstName": "John",
              "lastName": "Wick"
            },
            "dateOfBirth": "1985-01-01",
            "countryOfResidence": "US",
            "countryOfNationality": "DE"
          },
          "legalDocuments": [
            {
              "documentType": "passport",
              "documentNumber": "Z9431P",
              "documentIssuedCountry": "DE",
              "documentIssuedDate": 1639939034000,
              "documentExpirationDate": 1839939034000
            }
          ],
          "contactDetails": {
            "emailIds": [
              "john.wick@gmail.com"
            ],
            "contactNumbers": [
              "+137112345432"
            ]
          }
        }'

Card transaction scenarios

Real-time transaction monitoring allows you to verify and make a risk assessment on card transactions before they are processed. This enables you to identify high-risk transactions, potential fraud, and regulatory compliance issues before funds are moved.

For any transaction type (deposit, withdrawal, transfer etc.), you would make an API call to the POST /transactions endpoint to verify the transaction before processing.

Below are sample payloads for the three flow types, with the use cases each covers.

1. User to External Party (Outgoing)

This payload represents funds leaving a user’s card to an external entity (e.g., a merchant). It uses originPaymentDetails.method: “CARD” for the sender’s card and includes merchantDetails for the recipient.

Use Cases Covered:

  • Payments (e.g., card purchases at external merchants, online or POS).
  • Withdrawals (e.g., ATM cash-outs to external networks; adapt by adding ATM details in tags and setting type: “WITHDRAWAL”).
  • Outgoing Transfers (e.g., sending from user card to external account).
curl -X POST https://sandbox.api.flagright.com/transactions \
     -H "x-api-key: O000" \
     -H "Content-Type: application/json" \
     -d '{
  "type": "PAYMENT",
  "transactionId": "d458e5971482",
  "timestamp": 1754006400000,
  "originAmountDetails": {
    "transactionAmount": 10001,
    "transactionCurrency": "USD",
    "country": "BG"
  },
  "destinationAmountDetails": {
    "transactionAmount": 10001,
    "transactionCurrency": "USD",
    "country": "US"
  },
  "originPaymentDetails": {
    "method": "CARD",
    "cardFingerprint": "fp_1a2",
    "emailId": "john.wick@gmail.com",
    "cardStatus": "ACTIVE",
    "cardIssuedCountry": "US",
    "transactionReferenceField": "REF_789456123",
    "3dsDone": true,
    "nameOnCard": {
      "firstName": "John",
      "lastName": "Wick"
    },
    "cardExpiry": {
      "month": 12,
      "year": 2027
    },
    "posDetails": {
      "entryMode": "7"
    },
    "cardLast4Digits": "2234",
    "cardBrand": "VISA",
    "cardFunding": "CREDIT",
    "cardAuthenticated": true,
    "cardTokenized": true,
    "cardPresent": true,
    "paymentChannel": "POS",
    "cardType": "PHYSICAL",
    "cardBalance": {
      "amountValue": 5000,
      "amountCurrency": "USD"
    },
    "networkProviderRiskScore": 15,
    "tags": [
      {
        "key": "externalTransactionId",
        "value": "22222444"
      }
    ]
  },
  "originUserId": "Id2345",
  "transactionState": "CREATED"
}'

2. External Party to User (Incoming)

This payload represents funds entering a user’s account from an external card. It uses originPaymentDetails.method as CARD for the external funding card and destinationPaymentDetails for the user’s receiving account.

Use Cases Covered:

  • Deposits (e.g., top-ups from external cards to user wallet/account).
  • Refunds (e.g., credits from external merchants to user; adapt with type: “REFUND”).
  • Incoming Transfers (e.g., receiving from external accounts to user card).
curl -X POST https://sandbox.api.flagright.com/transactions \
     -H "x-api-key: O000" \
     -H "Content-Type: application/json" \
     -d '{
  "type": "DEPOSIT",
  "transactionId": "d458e5971483",
  "timestamp": 1754006400000,
  "originAmountDetails": {
    "transactionAmount": 10001,
    "transactionCurrency": "USD",
    "country": "BG"
  },
  "originPaymentDetails": {
    "method": "CARD",
    "cardFingerprint": "fp_ext1",
    "emailId": "external.sender@email.com",
    "cardStatus": "ACTIVE",
    "cardIssuedCountry": "BG",
    "transactionReferenceField": "REF_EXT123",
    "3dsDone": true,
    "nameOnCard": {
      "firstName": "External",
      "lastName": "Sender"
    },
    "cardExpiry": {
      "month": 12,
      "year": 2027
    },
    "cardLast4Digits": "5678",
    "cardBrand": "MASTERCARD",
    "cardFunding": "DEBIT",
    "cardAuthenticated": true,
    "cardTokenized": false,
    "cardPresent": false,
    "paymentChannel": "ONLINE",
    "cardType": "PHYSICAL",
    "cardBalance": {
      "amountValue": 15000,
      "amountCurrency": "USD"
    },
    "networkProviderRiskScore": 25,
    "tags": [
      {
        "key": "externalTransactionId",
        "value": "EXT_99999"
      }
    ]
  },
  "destinationAmountDetails": {
    "transactionAmount": 10001,
    "transactionCurrency": "USD",
    "country": "US"
  },
  "destinationPaymentDetails": {
    "method": "GENERIC_BANK_ACCOUNT",
    "accountNumber": "1234567890",
    "accountType": "CHECKING",
    "bankName": "Example Bank",
    "bankCode": "EXBK",
    "country": "US",
    "name": "John Wick",
    "emailId": "john.wick@gmail.com",
    "paymentChannel": "ACH",
    "tags": [
      {
        "key": "internalAccountId",
        "value": "ACC_12345"
      }
    ]
  },
  "destinationUserId": "Id2345",
  "transactionState": "CREATED"
}'

Response Structure

The API response contains comprehensive risk assessment information, including:

  1. Transaction status (ALLOW, FLAG, SUSPEND, BLOCK)
  2. Risk scores and risk levels
  3. Executed rules with detailed information
  4. Specific rules that were triggered for the transaction

The response is consistent across all flow types. Here’s an example for the user to external party payload:

{
    "transactionId": "d458e5971482",
    "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": 1752772779269,
            "ruleHitMeta": {
                "hitDirections": [
                    "ORIGIN",
                    "DESTINATION"
                ]
            },
            "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": 1752772779247,
            "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": 1752772779269,
            "ruleHitMeta": {
                "hitDirections": [
                    "ORIGIN",
                    "DESTINATION"
                ]
            },
            "vars": [
                {
                    "direction": "ORIGIN",
                    "value": {
                        "TRANSACTION:originAmountDetails-transactionAmount": 10001
                    }
                }
            ],
            "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",
                    "DESTINATION"
                ]
            },
            "labels": [
                "UNEXPECTED_BEHAVIOR"
            ],
            "nature": "AML",
            "isShadow": false,
            "executedAt": 1752772779520
        },
        {
            "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": 1752772779520
        }
    ],
    "status": "SUSPEND",
    "riskScoreDetails": {
        "trsScore": 40,
        "trsRiskLevel": "MEDIUM",
        "originUserCraRiskLevel": "HIGH",
        "destinationUserCraRiskLevel": "VERY_HIGH",
        "originUserCraRiskScore": 63.724137931034484,
        "destinationUserCraRiskScore": 90
    }
}

Understanding the Response

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 Value
ruleIdUnique 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 transactiontrue
natureRule 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:

  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 card 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 card payments. 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.