DEV Community: Rapyd

AI for Regulatory Compliance in Payments

mcduffin — Wed, 11 Mar 2026 18:30:37 +0000

By: Manish Hatwalne

Rapyd Protect is an AI-powered fraud detection service built into Rapyd's payment platform. It monitors transactions in real time across bank transfers, cards, and e-wallets, using machine learning (ML) models to identify suspicious patterns and potential compliance violations.

For developers building payment applications, regulatory compliance requirements like Anti-Money Laundering (AML) monitoring, suspicious activity reporting, and transaction screening can be difficult to implement. Rapyd Protect addresses these challenges through automated checks, ML-based risk scoring, and configurable review workflows. When a transaction triggers compliance (or fraud) concerns, the system automatically quarantines it and notifies your application via webhook, helping you maintain audit trails for regulatory purposes.

In this article, you'll learn how to use Rapyd Protect's fraud rules for compliance monitoring. You'll see how ML flags high-risk transactions for you review, and how to implement review workflows that meet regulatory requirements.

Rapyd Protect and Regulatory Compliance

Payment systems operate under multiple regulatory frameworks designed to prevent financial crime and protect consumers. AML regulations require monitoring for suspicious transaction patterns that could indicate money laundering or terrorist financing. Know Your Customer (KYC) and Know Your Business (KYB) rules mandate identity verification for individuals and companies conducting transactions. The Payment Services Directive 2 (PSD2) in Europe enforces Strong Customer Authentication and secure communication standards, while the General Data Protection Regulation (GDPR) governs how personal data is collected and processed. Regional frameworks like the California Consumer Privacy Act (CCPA) and Brazil's Lei Geral de Proteção de Dados (LGPD) add additional layers of compliance requirements based on geographic location.

Rapyd Protect handles these compliance challenges using ML models that analyze transaction data in real time by evaluating each transaction against patterns learned from Rapyd's global payment network, identifying anomalies that may indicate compliance violations. These models consider multiple factors including transaction velocity, geographic origin, payment amounts, and behavioral patterns. Based on this analysis, the system assigns risk scores to each transaction. When a transaction exceeds acceptable risk thresholds or matches suspicious activity patterns, Rapyd Protect automatically halts it and places it in quarantine for review.

This approach detects compliance issues that static rules alone might miss. The system adapts to emerging fraud trends and regulatory risks as they develop, giving you continuous protection without constant manual updates.

When Rapyd Protect quarantines a transaction, it communicates the status through a series of webhooks sent to your application. These webhooks provide the detailed information you need to maintain compliance audit trails, update transaction statuses, and communicate with customers about delayed payments.

How Machine Learning Benefits Compliance Monitoring

Rapyd Protect's machine learning capabilities handle a challenge that's impossible to solve manually: analyzing massive amounts of transaction data in real time spotting suspicious patterns that human compliance officers would miss.

The Rapyd Protect ML system runs 24/7, analyzing transaction ledgers even when your compliance teams are offline. This constant surveillance is critical for meeting regulatory requirements. Each transaction creates a ledger entry with detailed information like the payment amount, parties involved, geographic locations, timestamps, and payment methods. The ML models scan these ledgers for discrepancies and anomalies, comparing new transactions against historical patterns to catch deviations that might signal compliance violations.

A major advantage of Rapyd's machine learning approach is its ability to spot subtle patterns in vast datasets.The system can detect small changes in transaction timing, gradual increases in payment amounts, or unusual connections between seemingly unrelated accounts. These patterns often indicate attempts to evade detection. Activities that look normal individually may reveal suspicious intent when analyzed collectively. The Velocity Engine tracks purchase frequency and usage patterns across multiple timeframes, flagging sudden spikes in transaction velocity or suspicious pattern shifts that need investigation.

When the ML models identify a potential compliance issue, they don't just flag the transaction. They also provide context that helps human reviewers make informed decisions. The system analyzes patterns across your entire payment network, correlating data from multiple sources to build a complete risk profile for each flagged transaction.

This gives your compliance officers much greater reach. Each team member can effectively monitor far more transactions than manual review would allow. The system catches regulatory violations quickly, creating a stronger defense against financial crime. And because the ML models adapt to new threats automatically, your payment application stays compliant even as regulations and fraud tactics evolve. This means less ongoing maintenance work for your team.

The diagram below illustrates how Rapyd Protect's machine learning engine evaluates each transaction and determines the appropriate compliance action:

Setting Up Compliance Review Workflows with Rapyd

When Rapyd Protect identifies a transaction that requires investigation, it automatically halts the payment flow and places it in quarantine. This quarantine system serves as a critical checkpoint for regulatory compliance (or fraud detection), ensuring that potentially problematic transactions receive proper scrutiny before processing. It's built directly into Rapyd's payment infrastructure and communicates transaction status changes through a standardized webhook system (calling your predefined URL with a payload) that you can integrate into your application.

Rapyd Protect uses four distinct quarantine webhooks:

The Quarantine Under Review webhook triggers immediately when a transaction is placed in quarantine, providing your application with the transaction details and the reason for the hold. This notification allows you to update your system's transaction status, inform customers about the delay, and route the case to appropriate compliance personnel for investigation. The webhook payload includes essential information needed for compliance tracking and customer communication.

After a compliance officer reviews the quarantined transaction, Rapyd Protect sends one of three resolution webhooks:

The Quarantine Released webhook indicates that the transaction has been approved and will proceed to completion.
The Quarantine Declined webhook signals that the transaction has been rejected due to compliance (or fraud) concerns and will not be processed.
In cases where a transaction is approved but encounters technical issues during release, the Quarantine Release Failed webhook notifies your application that manual intervention may be required to resolve the processing error.

The manual review process must take place within a 7-day window. During this time, compliance officers should examine quarantined transactions against regulatory requirements. They should evaluate customer transaction history, geographic risk indicators, and regulatory alignment before making approval or decline decisions. This timeframe balances thorough compliance scrutiny with maintaining reasonable payment processing speeds.

For developers, integrating this workflow requires proper webhook handling within your application architecture. When receiving a Quarantine Under Review webhook, you should update the transaction status in your database, trigger customer notifications about the delay, and route case details to your compliance dashboard for tracking. The webhook payload contains identifiers that correlate the quarantined transaction with your original payment request, ensuring accurate status updates across your system.

A typical webhook payload looks like this for a QUARANTINE_UNDER_REVIEW event:

{
    "id": "wh_540b8a22cd77283ec2a721362e4de32d",
    "data": {
        "token": "qm_a5169383ddd6f0e04f716601dbc7375e",
        "target_tokens": [
            "payout_71987d8e65a4e7a68a5ea000e1984a24"
            ],
        "limits": null,
        "reason": "compliance",
        "source": "compliance",
        "status": "HLD",
        "created_at": 1646532379,
        "error_code": null,
        "updated_at": 1646532379,
        "action_type": "create_payout",
        "resolved_at": 0,
        "action_flow_id": "6a8840f9-5ebd-423c-8eab-b397b5ef81f1",
        "duplicated_action_flow_id": null
    },
    "type": "QUARANTINE_UNDER_REVIEW",
    "status": "NEW",
    "created_at": 1646532379,
    "extended_timestamp": 1646532379934,
    "trigger_operation_id": "f0c9ecbf-a238-4fa9-b0d5-a00aa3e322e6"
}

These webhooks allow you to build compliant payment applications with proper audit trails. Each webhook provides timestamped records of compliance decisions, creating an immutable log of when transactions were flagged, who reviewed them, and what actions were taken. This documentation is essential for regulatory examinations. By storing webhook data, your application can maintain a complete compliance history that demonstrates due diligence in monitoring suspicious transactions.

Did you know? Rapyd Protect also allows developers to create custom fraud rules that complement ML-based detection, so you can configure business-specific compliance checks like geographic restrictions or transaction amount thresholds. For detailed guidance, see this article about Enhancing Payment Fraud Detection with Rapyd Protect.

Benefits Of Automated Compliance Monitoring With Rapyd Protect

When you integrate Rapyd's payment APIs, compliance monitoring through machine learning and rule-based detection automatically applies to every transaction your application processes. This automation makes it possible to keep pace with evolving regulations and emerging fraud patterns. As regulatory bodies like FinCEN update AML requirements or new compliance risks emerge, Rapyd updates its machine learning models and detection logic without requiring changes to your application code. Your payment system continues meeting current compliance standards through automatic model updates informed by Rapyd's global transaction network and regulatory monitoring.

The webhook system makes integration easy. Instead of constantly polling for transaction statuses or building complex compliance logic into your application, you simply respond to webhook events when compliance attention is needed. For example, you can automatically trigger emails to specific compliance team members based on the type of webhook event received. This keeps your compliance monitoring separate from your core business logic. Rapyd's infrastructure handles the regulatory monitoring work while your application focuses on what matters most: payment processing and customer experience.

The following screenshot shows Under Review transactions detected by the Rapyd Protect system:

Every quarantined transaction, compliance decision, and status change generates logged records accessible through your Rapyd account. These automated logs provide the audit trails required during regulatory examinations, documenting your payment system's compliance monitoring activities without manual record-keeping. The logs capture timestamps, decision rationale, and transaction details that demonstrate adherence to AML regulations and other compliance frameworks.

Conclusion

Rapyd Protect transforms regulatory compliance by combining machine learning risk assessment with configurable workflows and real-time webhooks. The platform helps you build payment applications that meet complex regulatory requirements without constant manual oversight. The system monitors transactions continuously, flags compliance issues automatically, and maintains the audit trails necessary for regulatory examinations.

For developers, this means faster time to market and reduced compliance overhead. Enterprise-grade compliance monitoring is built directly into Rapyd's infrastructure with no additional integration required. As regulations evolve, Rapyd Protect adapts automatically, keeping your applications aligned with current standards.

If you're looking to automate compliance monitoring in your payment application, sign up for the Rapyd trial account and start using Rapyd Protect to experience AI-powered regulatory compliance firsthand.

Boosting Authorization Rates: Partnering Strategies and Intelligent Retries

Drew Harris — Tue, 09 Dec 2025 18:13:02 +0000

By: Adeyinka Adegbenro

Authorization rates measure the ratio of successful payments to total attempts. For instance, if a merchant processes one hundred payments and seventy of them are successful, the authorization rate is 70 percent. This metric directly impacts revenue, customer satisfaction, and operational efficiency. High authorization rates mean more revenue captured, while poor rates can signal system issues, like failed authentication, unreliable processors, or friction in the payment flow.

In this article, you'll learn about the different stages of a payment and where declines typically happen. You'll also learn about strategies that can help boost your approval rates, including smart retries using merchant advice codes, implementing artificial intelligence (AI) optimizations, and working with unified platforms like Rapyd.

Understanding the Payment Authorization Funnel

Before you can boost authorization rates, you need to understand how money moves from the customer to the merchant. Each stage is a potential point of failure. Understanding the moving parts helps you anticipate the kinds of authorization errors that may take place at different stages and how to respond strategically.

Stages of an Online Payment

The lifecycle of an online payment begins when a customer submits their card details on the merchant's application. That triggers an authorization request that is securely transmitted through a payment gateway (API) to a payment processor. The payment gateway and payment processor are often the same provider. Rapyd provides both services through one unified solution.

Next, the payment processor may initiate a 3-D Secure (3DS) flow if required. During this step, the issuer may perform additional checks, like one-time passwords (OTPs) or biometric prompts. Once authentication is complete, the authorization request is then routed through a card network, like Visa, Verve, or Mastercard. The network, in turn, forwards the authorization request to the customer's issuing bank. Based on various signals, such as available balance, fraud checks, and card validity, the issuing bank ultimately decides whether to receive or reject the payment. The decision travels back through the same route to the merchant, where the result is displayed to the customer.

Declines and Visibility into the Funnel

Declines can happen at any stage in the payment process, from network outages and expired cards to incorrect PINs or CVVs, fraud alerts, or insufficient funds. However, not all declines are created equal.

A soft decline is temporary (eg network timeouts, insufficient funds) and may succeed on retry. A hard decline (eg stolen card, invalid number, wrong PIN) usually can't be resolved on retry. Developers need visibility into this funnel to know when and how to respond.

For example, if a large portion of subscription payments fail due to expired cards, a retry will not be effective, but a card updater or reminder system may. This insight helps developers spot decline patterns and come up with strategies to prevent losing customers you've already spent money acquiring.

Implementing Smart Retry Logic with MACs

Merchant Advice Codes (MAC) are response indicators issued by banks or card networks that provide specific guidance when a transaction is declined. These responses usually follow a failed payment authorization attempt. The code helps the merchant determine whether the decline is temporary, permanent, or correctable. It can indicate whether to retry the transaction, prompt the customer for more information, or stop further attempts. By adhering to these codes, merchants can avoid needless retries and prevent damaging their authorization rates.

The following are some common MACs and their meaning:

MAC	Meaning
01	Updated Information needed
24	Retry in the next hour
30	Retry after ten days
43	Card reported stolen
55	Invalid PIN
7903	Do not retry
7921	Do not honor

The examples in this guide are primarily sourced from Mastercard's MAC since MACs were first introduced by Mastercard. It's important to understand the meaning of each code and how to respond effectively. For example, if the code indicates Do not retry, attempting the transaction again may trigger fraud alerts, chargebacks, fines, blacklisting, and reputational damage. You may forfeit any products or services that have already been delivered to the customer.

A code like Retry in the next hour suggests that the issue is temporary (eg the spending limit has been reached or the cardholder's bank is temporarily unavailable). Some codes may point to missing or invalid data (in cases of an expired card or missing CVV), and if stronger customer authentication is required, merchants can prompt users to reenter or update their payment details or even go through a 3DS check. For subscription-based businesses, a card updater service may help avoid some of these errors entirely by refreshing card information automatically.

Retrying only when it is appropriate increases your success rate without triggering issuer penalties or risking chargebacks. MAC-aware retry logic helps maintain healthy issuer relationships, reduce failed attempts, and improve overall conversion rates.

It's important to note that MACs are not standardized across all issuers or payment processors. Different card issuers may return different codes for similar situations or none at all. In some cases, the MAC hints only at the problem without giving the full picture. It may even advise a retry, but that doesn't guarantee a successful retry.

MACs should be used as part of a broader diagnostic strategy that includes logging, analytics, and close coordination with your payment provider.

Using AI to Predict and Optimize Authorization Outcomes

Like so many other areas, AI is revolutionizing payments by enabling faster, smarter decision-making. For instance, when it comes to payment optimization, AI can detect patterns in payment behavior and adapt in real time by analyzing historical transaction data to do the following:

Identify high-risk combinations that are likely to be declined
Recommend the best time or method to retry a failed payment
Predict fraud and proactively block transactions that are likely to be flagged and rejected

AI models automate analysis and continuous learning, leading to the discovery of emerging patterns in your data. This helps improve authorization rates and payment efficiency.

Use Case: Training Models on Transaction Data

A common method for training AI models to predict authorization outcomes involves using a combination of historical and real-time transaction metadata. Here are some useful features:

Transaction amount
Card bank identification number (BIN)
Geolocation
Timestamp
Network quality

With enough data, you can train a model to predict success probability for each available payment route or method. This makes it possible to implement smart routing. For any incoming payment, the system calculates the route with the highest likelihood of approval and uses it. On failure, the system retries the transaction through the next most optimal route. This approach helps merchants increase authorization rates while reducing unnecessary retries.

How a Data-Driven Approach Boosts Success Rates

AI enables the following intelligent mechanisms within payment systems:

Data enrichment augments payment requests by adding personally identifiable information (PII) that issuers have historically valued in approval decisions (eg device information, geolocation). Issuers are more likely to make better approval decisions when they have more contextual information about the cardholder.
Dynamic retry automates retries based on an evidence-based understanding of MACs or with a different payment service provider.
Smart filtering filters out avoidable declines (eg expired cards, duplicate payment submissions, fraud risk payments, bot activity, brute-force attempts with card PINs).
Smart routing selects the most promising processor most likely to approve a transaction, based on historical approval patterns.
Insight generation uncovers patterns and root causes for declines, helping teams prioritize improvements.

While AI has the ability to transform fraud detection, it's not without its challenges. Building, training, updating, and fine-tuning these models is complex work that demands massive data sets and serious computing power. Get the balance wrong, and you either block good customers (false positives) or let fraudsters slip through (false negatives).

Then there's the regulatory maze. Data protection laws like the General Data Protection Regulation (GDPR) put strict limits on how you store non-anonymized customer data. Models must be designed to comply with these regulations by anonymizing and encrypting personal data.

However, here's the thing: despite these challenges, AI makes payment systems more resilient and efficient—it's worth the effort. Even simple rule-based models can help small teams get started. You don't need a data science team or deep machine learning (ML) infrastructure to benefit from intelligent logic. Small teams can still improve success rates by implementing smart rule-based decision engines that handle MACs, flag common fraud indicators, or set retry thresholds. Over time, these systems can evolve into more sophisticated ML pipelines as resources and data maturity grow.

Partnering with a Unified Payments Platform

A unified payments platform offers end-to-end payment services, like acquisition, issuance, payouts, and digital wallets under a single provider. Instead of relying on multiple services for each step of the payment funnel, businesses can streamline operations, reduce costs, and ship faster by working with a unified solution.

One major advantage of unified payment platforms is full-stack orchestration. Since these platforms manage both the acquiring and issuing sides of the payment flow, they have more access to granular data, such as issuer response data and fraud signals. This gives them better intelligence about what issuer response codes actually mean and how to act on them.

For instance, platforms that issue their own cards or wallets can facilitate internal transactions with less friction, leading to faster approvals, lower fees, and fewer declines. While merchants can't control which card the customers use, partnering with a unified platform significantly improves the likelihood of successful payment outcomes.

Rapyd supports payments, payouts, wallets, and card issuing under one umbrella. Even without ML support, the detailed issuer responses and metadata returned by Rapyd can serve as input for custom retry logic or AI decision models. This allows teams to improve retry outcomes without manually aggregating insights from multiple payment service providers.

Sample Project: Payment Retry Orchestrator with MAC Logic

This section walks you through a simple Node.js project that simulates multiple payment attempts and failure scenarios using MACs to guide retry behavior. The logic randomly fails some transactions and returns a corresponding MAC, which the orchestrator uses to decide what to do next: retry, prompt for a new method, or stop.

If you prefer local development, you can clone the sample project on GitHub by running the following:

git clone https://github.com/Rapyd-Samples/rapyd-payment-retry-orchestrator

cd payment-retry-orchestrator

You can also run this project instantly in your browser via StackBlitz, with no setup required.

The main components include the following:

index.js is the entry point of the project. It runs a batch of transactions using runBatch and handles each one using processTransaction, which simulates the payment, receives a MAC, and applies the appropriate retry logic.
simulator.js contains the simulateTransaction function, which randomly decides whether a transaction succeeds or fails. On failure, it returns a randomly selected MAC.
macLogic.js defines the function interpretMAC to translate a MAC to an action. The MAC_RULES object provides a sample set of MACs to action mappings (eg retry, prompt, or halt).
dashboard.js includes a report function that summarizes the outcome of all transactions that have run. It tracks metrics like total attempts, retries triggered, user prompts, and halted transactions.
README.md provides setup instructions and ideas for extending the project with ML-powered predictions.

To run the simulator, in either your terminal or the StackBlitz terminal, execute the following:

node index.js

You should see the logs of each declined transaction and their corresponding meaning. After all the transactions have run, you'll see a summary report of all transactions:

The goal isn't to replicate a full production-grade payment system. But as a foundation, you can extend with more advanced logic with payment orchestrator platforms like Rapyd, or even with predictive AI models.

Conclusion

Declined payments are more than just lost revenue; they are pointers. By interpreting them and understanding the authorization funnel, developers can turn failed transactions into opportunities for recovery.

With the right tools, you can go further than reactive retries. Rule-based retry strategies, AI-driven optimizations, and unified payment orchestration platforms like Rapyd can help you make smarter decisions at scale. Developers who take decline codes seriously as data points, rather than as dead ends, build smarter, anti-fragile systems that improve success rates and customer satisfaction.

Mastering 3DS: Balancing Security, UX, and Authentication Rates

mcduffin — Tue, 11 Nov 2025 09:00:00 +0000

By: Adeyinka Adegbenro

3-D Secure (3DS) is an authentication protocol that adds an extra layer of security for card payments. It helps verify that the legitimate owner of a card is the one making the purchase. It also often serves as a mechanism to fulfill Strong Customer Authentication (SCA), particularly in regions subject to regulations like the revised Payment Services Directive (PSD2), which mandates at least two forms of customer authentication.

While 3DS facilitates two-factor authentication for online payments, it's designed to assess risk. This means not every payment requires an explicit challenge. Low-risk transactions can be completed through a frictionless flow without extra customer input. The protocol is meant to gauge if further security is needed for a specific transaction, and if so, the customer may be asked to input a PIN or a one-time password (OTP) sent to their device.

The challenge when integrating 3DS into a payment flow is creating a balance between security, user experience, and high authorization rates. While 3DS can enhance security, it can also introduce friction that leads to user abandonment and lower approval rates if not implemented carefully.

In this article, you'll go through the process of implementing 3DS and learn how to strike the balance between security, user experience, and authentication rates.

Understanding the 3DS Flow: Frictionless vs. Challenge

The original 3DS protocol, 3-D Secure 1 (3DS1), was designed to protect merchants from fraudulent chargebacks by verifying cardholder identity, but it frequently led to significant user friction. Mobile browser incompatibility, slow authentication page loads, and a perceived lack of necessity often led to transaction abandonment.

Recognizing these challenges, 3-D Secure 2 (3DS2) leveraged a broader range of data to enable more accurate risk assessment and a smoother mobile experience. It introduced two main authentication paths: the frictionless flow and the challenge flow. In the frictionless flow, transactions can be approved without requiring any additional input from the cardholder. This occurs when a transaction is deemed low-risk through real-time risk-based analysis (RBA). On the flip side, if the RBA identifies a transaction as potentially high-risk, a challenge flow is initiated, prompting the user for further verification, such as an OTP, biometric authentication, or a PIN.

Choosing between a frictionless or challenge flow depends on numerous data points at the time of the transaction by both merchants and issuers. These data points can include device information, transaction amount, customer status (new or existing), transactional history, and geolocation. For instance, if a new card is used by a customer with no prior transaction history or an existing card is used on an unfamiliar device, the risk can be elevated, leading to a 3DS challenge. However, a customer with a card on file and a history of successful, non-fraudulent transactions can trigger a low-risk assessment, allowing the transaction to proceed via the frictionless flow, bypassing explicit 3DS authentication.

Developers should strive to minimize challenge flows and maximize frictionless outcomes by transmitting rich contextual data alongside payment information. The richer the data, the more accurately issuers can assess the customer's true risk profile. This not only aids in satisfying issuer rules and regulatory requirements but also reduces checkout friction and improves conversion rates.

Balancing Security and User Experience

Minimizing challenge flows and maximizing frictionless outcomes keeps customers happy while still preventing fraud. In this section, you will learn strategies you can use to strike that balance when implementing 3DS.

Using 3DS Exemptions to Reduce Friction

3DS exemptions are specific provisions under regulations like PSD2 that allow certain transactions to bypass active cardholder authentication. These exemptions are primarily designed to reduce friction and enhance the user experience for lower-risk transactions.

Here are some common exemption types:

Low-Value Transactions

Developers can request a low-value exemption (LVE) for payments less than or equal to €30 (or its equivalent after currency conversion). This exemption applies as long as the cumulative sum of previous transactions by the same cardholder, since their last SCA, does not exceed a certain threshold (eg €100) or the number of consecutive low-value transactions does not exceed five, depending on the issuer's enforcement policy.

To programmatically request this exemption, depending on your Payment Service Provider's (PSP) API, you can set an exemption indicator. For example, with some APIs, you set payment_method_options.sca_exemption to LowValue.

Transaction Risk Analysis

Through transaction risk analysis (TRA), merchants or their payment providers can request a 3DS exemption for transactions they've internally assessed as low-risk. This exemption is useful for promoting customer retention by ensuring known or trusted customers are not subjected to unnecessary authentication. Merchants must analyze a transaction's risk profile and confirm it as low-risk through their internal systems before requesting a TRA exemption.

For instance, a $20 USD order from a long-time customer using the same known device, IP address, and billing address, with no history of chargebacks, would be a strong candidate. The merchant would then flag this as low-risk and request the exemption via TRA. Programmatically, this can involve setting payment_method_options.sca_exemption to TransactionRiskAnalysis.

Credentials on File

Credentials on File (CoF) exemptions apply when charging a stored card from a returning customer. This typically involves the merchant or PSP securely storing a customer's card details for future payments, such as recurring subscriptions, top-ups, or one-click reorders. There are two primary types of CoF transactions:

Merchant-initiated transactions (MIT): This is for payments like a Netflix subscription, where the user is not actively present at the time of payment. The transaction is inherently exempt from SCA.
Customer-initiated transactions (CIT): When a customer with their card on file chooses to reorder with a single click, they may qualify for a frictionless flow, provided the transaction meets other low-risk criteria.

While other exemptions, such as trusted beneficiaries, exist, they often require direct customer action (eg whitelisting a merchant on their issuer's platform) and are less directly controlled by the merchant. This article focuses on merchant-initiated strategies.

Properly utilizing the exemptions mentioned here helps maximize frictionless flows and leads to a more seamless customer experience and faster payment approvals. However, note that requesting an exemption does not guarantee a frictionless flow. The issuer ultimately retains the right to override the exemption and mandate a challenge if they deem the transaction high risk.

Fine-Tuning the Challenge Indicator

Challenge indicators are optional parameters that merchants send to issuing banks to influence whether a transaction should undergo additional authentication (a challenge flow). This parameter is typically included within the payment request to your PSP. While specific implementations may vary between PSPs, a common representation can look like this:

"3DRequestorChallengeInd": "02"

Following are some common challenge indicators:

Challenge Indicator Value	Meaning	Use Case
01	No preference	You let the issuer decide
02	No challenge requested	You want a frictionless flow
03	Challenge requested (merchant preference)	You prefer a challenge flow (eg suspicious activity, first-time user, new device)
04	Challenge requested (mandate)	You need a challenge flow as required by law (regulations the merchant is bound by or internal business rule)

It's important to note that issuers make the final decision. Even if you request a frictionless flow (02), the issuer may still challenge the transaction based on their risk analysis.

While requesting a challenge (03 or 04) can reduce fraud and liability, doing so unnecessarily may negatively impact your conversion rates. In contrast, strategically using 02 for low-risk transactions can improve authorization rates, but applying it too broadly to transactions that should have been challenged may lead to more chargebacks or soft declines.

A good starting point is to default to 01 (no preference) or 02 (no challenge requested) and adjust your strategy based on observation, user behavior, and fraud risk.

Passing More PII Means Fewer Challenges

Personally identifiable information (PII) comprises any data that can identify a specific individual. In the context of 3DS transactions, passing more PII can significantly increase the likelihood of a frictionless flow and improve the authentication experience for users.

Issuing banks heavily rely on the RBA to determine whether a 3DS transaction should proceed via a frictionless flow or require a challenge. The more context an issuer receives, the more accurately its risk engine (often powered by artificial intelligence (AI) / machine learning (ML) models) can assess the legitimacy of a transaction.

Merchants can significantly increase the likelihood of a frictionless flow by including a rich set of PII and other contextual data in their 3DS requests. When the issuing bank receives this detailed information, its RBA model can confidently look for signals of legitimacy and fraud, such as the following: Is this a known device? Is there a history of fraudulent activity associated with this IP address, email, or card? Is the transaction amount unusually high?

The more detailed PII the merchant provides, the better the RBA model performs, leading to more confident risk scoring and, ultimately, higher rates of frictionless authentication.

Here are some examples of valuable PII and metadata to include:

Email address
Phone number
Billing address
Device fingerprint
Browser metadata

Developers should make every effort to provide as much optional customer metadata as possible in their 3DS requests to ensure the best outcomes and maximize frictionless flows.

Handling 3DS Failures and Soft Declines

It's important to understand that a 3DS failure is not always the same as a final payment authorization decline. 3DS failures in online payments typically occur when a cardholder fails to correctly authenticate their transaction due to incorrect information input or because of technical issues within the authentication process itself. These outcomes can generally be categorized into two main types: hard declines and soft declines.

Hard Declines

Hard declines are final rejections of a payment where retrying the transaction is unlikely to succeed. Common scenarios include the following: the card not being enrolled in 3DS, the authentication explicitly rejected by the cardholder, or the issuer refusing to honor the transaction due to a card issue (eg lost, stolen, or account closed).

For hard declines, it's best not to retry to avoid potential chargebacks or issuer penalties. For example, if a payment declines with a code like 63 - Cardholder not Enrolled, you should return a clear message to the customer, such as "Your card is not enrolled in secure authentication. Please use a different payment method."

Soft Declines

Soft declines are usually not final and present an opportunity for retry. For instance, a merchant may initially attempt a frictionless flow for a payment, but the issuer can soft decline the transaction, requesting SCA on retry.

When faced with soft declines, issuers may require merchants to retry soft declined transactions with 3DS within a specific timeframe, often indicated by a Merchant Advice Code (MAC). MACs are signals sent by card networks like Mastercard in response to a declined transaction. They help merchants understand whether to retry a transaction or not.

Developers should build logic to handle these soft declines gracefully by retrying the same transaction but adjusting parameters to force a challenge on the second attempt (eg by setting the 3DS challenge indicator appropriately, which is platform dependent).

MACs are typically returned in the response of a failed 3DS transaction. These codes provide crucial guidance on the next steps to take. Here are a few examples of common MAC and their meanings:

MAC	Meaning	What to Do
62	Restricted card	Do not retry the transaction
65	Exceeds withdrawal count limit	Retry with a 3DS challenge
70	Contact card issuer	Retry is not advised; may indicate final failure
91	Authentication not available; 3DS service down	Retry later or through different processor

Keep in mind that the codes can vary slightly depending on the payment processor. Always consult your provider's specific documentation. Decoding the MAC after a 3DS request has failed is essential for guiding developers to handle declines gracefully and optimize their payment flows.

Leveraging AI to Optimize 3DS Strategy

AI and ML offer a powerful avenue for optimizing your 3DS strategy. By combining data analysis and continuous learning, AI can help merchants and payment providers make smarter, adaptive decisions across the entire authentication funnel.

AI/ML can provide value in the following ways:

Exemption prediction: AI can analyze historical transaction data, issuer behavior, transaction context, and user history to predict when an exemption (like TRA or LVE) is most likely to succeed or even when to avoid requesting an exemption entirely to avoid soft declines. For example, if an AI model learns that a specific issuer frequently declines TRA exemptions after 10 PM, it can dynamically adjust future attempts during that timeframe.
Dynamic challenge indicator selection: Instead of relying on static, hard-coded values for the 3DS challenge indicator, an AI algorithm can analyze real-time data points, such as device information, customer behavior, and transaction amount, to assess the risk level of each payment. This assessment informs the selection of the most appropriate challenge indicator (eg no_challenge_requested for low-risk, challenge_requested for high-risk). This approach helps developers better align with issuer policies, reduce friction for low-risk transactions, and avoid unnecessary declines due to mismatched challenge expectations.
PII level tuning: AI/ML can learn which specific PII and contextual data are most valued by different issuers. Some issuers can heavily weigh device data, while others prioritize email, IP location, or account tenure. An AI model can dynamically adjust the depth and type of information sent with each transaction to improve trust scores and increase the likelihood of frictionless flow.

These AI-driven optimizations thrive on real transaction feedback loops. Models continuously learn from outcomes, such as successes, declines, and fraud flags, to identify evolving risk patterns and refine their logic over time. This approach ensures that authentication strategies are constantly improving based on real-time transactions and customer context, rather than static rules.

The benefits of integrating AI into your 3DS strategy include higher conversion rates, effective fraud management, improved issuer alignment, and more frictionless flows.

Sample Project: 3DS Optimization Playground

To help developers visualize the concepts of 3DS optimization, this section explores a simple web-based simulator called the 3DS Optimization Playground. This application demonstrates how various parameters, such as transaction amount, CoF status, challenge indicators, and the presence of PII, can influence the outcome of a 3DS flow. All the source code is available on GitHub.

The simulator.html file is designed to run directly in a web browser without requiring a server-side component. Here's a brief explanation of its key components:

DOM element selection: The logic starts by selecting all the necessary HTML elements using document.getElementById and storing them in constants for easy access:

const amountInput = document.getElementById('amount');
        const cofStatusSelect = document.getElementById('cofStatus');
        const challengeIndicatorSelect = document.getElementById('challengeIndicator');
        const piiPresenceCheckbox = document.getElementById('piiPresence');
        const aiModelToggle = document.getElementById('aiModelToggle');
        const simulateBtn = document.getElementById('simulateBtn');
        const outputSection = document.getElementById('outputSection');
        const outcomeSpan = document.getElementById('outcome');
        const frictionlessRateSpan = document.getElementById('frictionlessRate');
        const challengeRateSpan = document.getElementById('challengeRate');
        const failureRateSpan = document.getElementById('failureRate');
        const exemptionReasonDiv = document.getElementById('exemptionReason');
        const failureReasonDiv = document.getElementById('failureReason');

Global rates for AI model persistence: The currentFrictionlessRate, currentChallengeRate, and currentFailureRate variables are the base rates that define the probabilities of friction, challenge, and failure occurring in 3DS. They also get tuned in real time after every transaction so that the AI model simulator simulates a cumulative effect on the rates over time.
Event listener: The simulateBtn.addEventListener('click', simulate3DS) line attaches an event listener to the "Simulate 3DS Flow" button in the UI. When the button is clicked, the simulate3DS function is called.
simulate3DS function: This is the main function that performs the simulation.
- Input retrieval: The function initially reads the current value of all input fields (amount, cofStatus, challengeIndicator, piiPresence, aiModelToggle).
- Initialization: This sets up variables to store the outcome and any specific reasons for the current run in variable outcome, exemptionReason, and failureReason.
- Exemption evaluation: The next part of the function (lines 314–343) determines if the transaction is eligible for various 3DS exemptions (TRA, LVE, recurring payments). It sets exemptionApplied and exemptionReason according to the exemption triggered.
- ACS random challenge logic: Access Control Server (ACS) in payments is a system operated by the issuer to verify the cardholder's identity. In the function, the ACS code block (lines 346–352) implements a one-in-four chance for the ACS to mandate a challenge if no exemption applies and the challenge indicator is "no preference" or "no challenge".
- Outcome determination: Based on the combination of the challenge indicator, exemption eligibility, and the ACS-mandated challenge, the code block determines the final outcome of the 3DS flow (e.g., "Frictionless (Exempted)", "Challenge (Mandated)", "Frictionless", "Failure").
- AI model impact (simplified): If the "Enable AI model" toggle is enabled, this section simulates how an AI may auto-tune parameters. It heuristically adjusts the global frictionless, challenge, and failure rates to favor more frictionless outcomes, demonstrating the concept of optimization.
- Rate normalization: Ensure the sum of frictionless, challenge, and failure rates always adds up to 100 percent to maintain probability consistency.
- Display results: Updates the application's output section with the calculated outcome and rates. It also displays the exemptionReason or failureReason if applicable.

Test Cases for the 3DS Simulator

The following scenarios are designed to help you visualize the logic in the simulation. Open simulator.html with your preferred (modern) browser to play around with it. For each test case, enter the specified input values and click the Simulate 3DS Flow button to see the expected outcome.

Low-Value Exemption

This test case demonstrates a transaction that is automatically exempted from a challenge because the transaction value is low.

Inputs

Transaction amount: $25.00
CoF status: Not CoF
Challenge indicator: No Preference
PII present?: Unchecked
Enable AI model: Unchecked

Expected Outcome

Outcome: Frictionless (Exempted)
Exemption/optimization info: Low Value Exemption (LVE): Transaction amount is below the low value threshold.

The simulator's logic checks for the LVE initially. Since the amount is less than or equal to $30 USD, the transaction is immediately classified as frictionless without any further checks:

CoF Exemption

This scenario shows how a recurring payment from a trusted customer can be exempted from a challenge, even with a higher transaction amount.

Inputs

Transaction amount: $75.00
CoF status: Merchant Initiated Transaction (MIT)
Challenge indicator: No Preference
PII present?: Unchecked
Enable AI model: Unchecked

Expected Outcome

Outcome: Frictionless (Exempted)
Exemption/optimization info: Recurring Payments/MIT Exemption: Transaction is a CoF payment.

The simulator prioritizes CoF transactions as a valid exemption reason. Even though the amount is above the LVE threshold, the cofStatus of merchant-initiated signals a recurring payment, which is considered low-risk and therefore frictionless:

Challenge Mandated

This demonstrates a scenario where a challenge is unavoidable, regardless of other factors, because it has been explicitly requested.

Inputs

Transaction amount: $15.00
CoF status: Not CoF
Challenge indicator: Challenge Mandated
PII present?: Checked
Enable AI model: Unchecked

Expected Outcome

Outcome: Challenge (Mandated)
Exemption/optimization info: No message

The Challenge (Mandated) indicator acts as an override. It bypasses all exemption logic and forces a challenge, which is useful for transactions deemed high-risk by the merchant or when required by regulations:

AI Model Tuning

This test highlights the dynamic nature of the AI model. You have to run this simulation with the AI toggle checked multiple times to see the effect.

Inputs

Transaction amount: $100.00
CoF status: Not CoF
Challenge indicator: No Preference
PII present?: Checked
Enable AI model: Checked

Expected Outcome

Outcome: Over multiple runs, the Frictionless Rate gradually increases, and the Challenge Rate and Failure Rate decrease with each successful frictionless or challenged outcome.
Exemption/optimization info: If a frictionless outcome occurs without an exemption, the message is AI Model Optimization: Transaction identified as low risk for frictionless flow.

With the AI model enabled, it learns from each transaction outcome by adjusting the underlying success rates:

Conclusion

When implementing 3DS, it's easy to become focused on the enhanced security that additional authentication layers provide, inadvertently overlooking the friction that comes with it. A balance must be struck: merchants who lean too heavily toward either extreme risk, rampant insecurity, and fraud in their payment funnel, or those who suffer from high abandonment rates due to excess customer friction.

In this article, you learned how to achieve the optimal balance between security and a great user experience. You saw strategies, like 3DS exemptions, challenge indicator parameters, data enrichment in payment requests using PII, and 3DS failure management, and you learned how to harness the power of AI and ML models for 3DS optimization.

Mastering Dispute Resolution with Mastercard Collaboration

mcduffin — Tue, 28 Oct 2025 16:44:29 +0000

By: Vivek Kumar Maskara

As a security measure, card issuers allow their users to dispute a transaction in case of fraud, theft, or other legitimate scenarios. When a customer disputes a transaction, you, as the merchant, need to act fast to review the dispute before it escalates into a chargeback, which refers to a forced reversal of funds initiated by the cardholder's bank. If your chargeback ratio rises too high, you could face penalties or even lose your ability to receive card payments altogether.

Rapid Dispute Resolution (RDR) enables merchants to automate their dispute response with predefined rules that allow instant review and automatic refunds for certain scenarios. Rapyd is an all-in-one payment platform that integrates directly with Visa and Mastercard acquirers, helping merchants improve their authorization rates and act against chargebacks.

In this article, you'll learn how to use the Rapyd API to automatically resolve low-value Mastercard transaction disputes.

Understand Dispute Resolution with Mastercard Collaboration

RDR is a fully automated dispute management solution for merchants that was initially championed by Visa in collaboration with Verifi. Mastercard Collaboration offers a similar capability for Mastercard-issued cards, enabling merchants to resolve disputes before a chargeback can occur. The following diagram illustrates the dispute resolution flow with Mastercard Collaboration:

Collaboration alerts the merchant as soon as the transaction is disputed, allowing merchants to review the cardholder complaint and issue a refund if needed. If the merchant refunds the transaction, a chargeback is no longer needed, and Mastercard marks the dispute as resolved. If the refund is not processed, the dispute advances to the chargeback step, and the Collaboration process is completed.

As a merchant receiving payments through multiple payment methods, including Visa and Mastercard, integrating with multiple dispute resolution solutions can be challenging. Rapyd simplifies this by offering direct integration with both Visa and Mastercard, enabling seamless dispute resolution implementation within your application:

Rapyd lets merchants define automatic refund rules using the Client Portal to determine the conditions under which an automatic refund should be issued. When Rapyd receives a dispute notification from Mastercard Collaboration, it evaluates the merchant-defined rules, and if the criteria are met, it issues an automatic refund without merchant intervention. Otherwise, it notifies the merchant by sending a PAYMENT_DISPUTE_CREATED webhook event, and the merchant can perform additional checks before deciding the outcome.

Implement Mastercard Dispute Resolution with Rapyd

In this tutorial, you'll create an Express application that makes a Mastercard card payment request using Rapyd APIs and listens to webhook events for dispute resolution. By the end of the tutorial, you'll learn how to do the following:

Make a signed Rapyd API request for payment and disputes.
Set up a webhook that listens to payment and dispute creation events and lets you take custom actions.
Send an email to the merchant notifying them about the dispute details.

Prepare Prerequisites

Before starting, you need to complete the following actions:

Sign up for a Rapyd account.
Set up your Rapyd account.
Install Node.js 18.0 or above on your development machine.
Install and set up ngrok.

This tutorial uses this starter code from GitHub that has a barebones Node.js app set up. To follow along, clone the GitHub repo and switch to the starter branch by following these steps:

git clone https://github.com/Rapyd-Samples/dispute-resolution-mastercard
cd rapyd-payments
git checkout starter

Let's go over the structure of the codebase:

The package.json file defines the Express project dependencies and the npm start script.
The src directory contains the main source code, including the index.js entry point, which initializes the Express server by creating a new instance of the App.
The src/services/rapyd.utilities.js file defines methods to make a signed HTTPS request to Rapyd servers. It defines the makeRequest method that takes the HTTP method type, url, and body as parameters, and it returns the Rapyd API response to the caller. This method uses the sign method to sign the payload before making the REST API call. If you want to learn more about the signing process, check out this Rapyd guide.

Set Up Your Rapyd Access Key and Secret Key

Notice that the source contains .env.example, which is a sample environment file. Rename the file to .env and replace the values for RAPYD_API_KEY and RAPYD_SECRET_KEY with your credentials, which you can access on the Rapyd Client Portal:

RAPYD_API_KEY=<REPLACE_WITH_RAPYD_ACCESS_KEY>
RAPYD_SECRET_KEY=<REPLACE_WITH_RAPYD_SECRET_KEY>
BASERAPYDAPIURL=https://sandboxapi.rapyd.net

Install Dependencies and Run the App

After familiarizing yourself with the code, install the npm dependencies by executing the following command:

npm install

You can now run the starter code to verify your setup. Execute the following command to run the app:

npm run start

Your output looks like this:

App initialized
🚀 Server running on http://localhost:8000

Since the .env file defines the application port as 8000, the server starts running on this port. You can open a new terminal window and use curl to verify that the default endpoint is accessible by executing the following:

curl -i http://localhost:8000/api

Your output looks like this:

Welcome to the Rapyd Payment API

Now that the starter code is set up, you can proceed to integrate Rapyd payment and dispute resolution APIs.

Integrate Rapyd APIs to Receive Payments

This section explains how to integrate Rapyd APIs to receive payments, retrieve dispute status, and issue refunds. For this tutorial, the Node.js application doesn't define strict request schemas and simply relays the request payload to Rapyd. You'll integrate the following Rapyd APIs:

POST v1/payments/ to create a new card payment
GET v1/payments/ to retrieve details of a payment
GET v1/payments/ to retrieve details of a payment
POST v1/refunds to create a refund (Note that this tutorial doesn't directly use the refund endpoint, but the integration details are covered here for completeness.)
GET v1/disputes/{disputeID} to retrieve details of a dispute

Before starting the integration, refer to the linked API docs earlier for details about the request parameters.

You can utilize the makeRequest method defined in the starter code to send a signed request to Rapyd servers. To integrate the APIs, update the src/services/rapyd.service.js file with the following code snippet:

import { makeRequest } from './rapyd.utilities.js';

class RapydService {
  static async createPayment(paymentData) {
    const url = '/v1/payments';
    return makeRequest('POST', url, paymentData);
  }

  static async getPaymentStatus(paymentId) {
    const url = `/v1/payments/${paymentId}`;
    return makeRequest('GET', url);
  }

  static async refundPayment(refundData) {
    const url = '/v1/refunds';
    return makeRequest('POST', url, refundData);
  }

  static async getDisputeById(disputeId) {
    const url = `/v1/disputes/${disputeId}`;
    return makeRequest('GET', url);
  }
}

export default RapydService;

The newly defined methods relay the request payload to the makeRequest method and return the response received from it. Next, you need to update the controller to use the service methods for payment, disputes, and refunds. Update the src/controllers/payment.controller.js with the following code snippet:

import RapydService from '../services/rapyd.service.js';

class PaymentController {
  static async createPayment(req, res, next) {
    try {
      const payment = await RapydService.createPayment(req.body);
      res.status(201).json({ success: true, data: payment });
    } catch (error) {
      next(error);
    }
  }

  static async getPaymentStatus(req, res, next) {
    try {
      const paymentStatus = await RapydService.getPaymentStatus(req.params.id);
      res.status(200).json({ success: true, data: paymentStatus });
    } catch (error) {
      next(error);
    }
  }

  static async refundPayment(req, res, next) {
    try {
      const refund = await RapydService.refundPayment(req.body);
      res.status(200).json({ success: true, data: refund });
    } catch (error) {
      next(error);
    }
  }

  static async getDisputeById(req, res, next) {
    try {
      const dispute = await RapydService.getDisputeById(req.params.id);
      res.status(200).json({ success: true, data: dispute });
    } catch (error) {
      next(error);
    }
  }
}

export const { createPayment,
  getPaymentStatus,
  refundPayment,
  getDisputeById } = PaymentController;
export default PaymentController;

In this code snippet, every controller method parses the req object and utilizes the RapydService methods to define createPayment, getPaymentStatus, refundPayment, and getDisputeById methods. If the RapydService throws an error, the controller method catches the error and returns a next(error) API error response.

Update the src/routes.js file to define the new API routes:

// Add this import statement
import {
    createPayment,
    getPaymentStatus,
    refundPayment,
    getDisputeById
} from './controllers/payment.controller.js';

// Add payment routes
router.post('/payment', createPayment);
router.post('/payment/:id/refund', refundPayment);
router.get('/status/:id', getPaymentStatus);
router.get('/disputes/:id', getDisputeById);

After these routes are added, the Express application can be used to create card payments and check their status.

Test Payment Integration

Now that you've added the payment endpoints in the Node.js application, you can test payments using Mastercard sandbox cards. Execute the following curl command that uses one of the sandbox cards to create a payment:

curl --location 'http://localhost:8000/api/payment' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 26.51,
    "currency": "ZAR",
    "merchant_reference_id": "042620221450",
    "payment_method": {
        "type": "gb_mastercard_card",
        "fields": {
            "number": "5102589999999913",
            "expiration_month": "11",
            "expiration_year": "26",
            "cvv": "123",
            "name": "John Doe"
        }
    },
    "ewallets": [
        {
            "ewallet": "<YOUR_RAPYD_EWALLET_ID>",
            "percentage": 100
        }
    ],
    "metadata": {
        "merchant_defined": "created"
    },
    "capture": true,
    "payment_method_options": {
        "3d_required": false
    }
}'

Make sure to replace <YOUR_RAPYD_EWALLET_ID> with a Rapyd Wallet ID. You can create a new wallet or retrieve an existing wallet ID using the Rapyd Developer Portal. Refer to the Create Payment API reference to learn more about the request payload.

After you execute the curl command, you should receive a success response with payment details and status:

{
  "success": true,
  "data": {
    "statusCode": 200,
    ...
    "body": {
      ...
      "data": {
        "id": "payment_1e8c9b2cf200882954bfe49fa550476c",
        "amount": 26.51,
        "original_amount": 26.51,
        ...
        "customer_token": "cus_33ea7f84366b2b092a2c210faa5c31b1",
        "payment_method": null,
        ...
      }
    }
  }
}

You can also check the payment details using the Collect > Payments page on the Rapyd Client Portal. Similarly, you can test other API endpoints by grabbing sample payloads from the API docs.

Set Up a Webhook to Notify the Merchant About Disputes

Now that you have the payment integration set up, you can create a webhook to listen to Rapyd payment and dispute events, and send an email with dispute details to the merchant.

Configure Email Service

In this tutorial, you'll learn how to send emails using Nodemailer, but in a real-world application, you can perform other custom actions upon receiving a webhook event.

To start, install the nodemailer npm package by executing the following command:

npm install nodemailer

The command installs the package and updates package.json and package-lock.json files.

Next, create a services/email.service.js file and add the following code snippet to it:

import nodemailer from 'nodemailer';
import { emailConfig, merchantEmail } from '../config.js';

class EmailService {
    constructor() {
        this.transporter = nodemailer.createTransport({
            service: emailConfig.service,
            auth: {
                user: emailConfig.user,
                pass: emailConfig.pass
            }
        });
    }

    async sendDisputeNotification(disputeData) {
        const { token, original_dispute_amount, original_transaction_id, currency } = disputeData;

        const emailContent = `
        Payment Dispute Alert

        Dispute Details:
        - Dispute ID: ${token}
        - Original Transaction ID: ${original_transaction_id}
        - Dispute Amount: ${original_dispute_amount} ${currency || 'USD'}
        - Date: ${new Date().toLocaleString()}

        Action Required:
        A dispute has been created for one of your transactions. Please review the dispute details and take appropriate action.

        This is an automated notification for demonstration purposes.`;

        const mailOptions = {
            from: emailConfig.user,
            to: merchantEmail,
            subject: `Payment Dispute Created - ${token}`,
            text: emailContent
        };

        try {
            const info = await this.transporter.sendMail(mailOptions);
            console.log('Dispute notification email sent:', info.response);
            return { success: true, messageId: info.messageId };
        } catch (error) {
            console.error('Error sending dispute notification email:', error);
            throw error;
        }
    }
}

export default new EmailService();

This code creates a new mail transport by calling the createTransport method in the service constructor. This transport is used to deliver an email over SMTP.

This code also defines a sendDisputeNotification method that takes disputeData as input, constructs the email body and subject, and calls the sendMail to send an email to the merchant.

Note that the email service requires an emailConfig to be defined with sender and receiver email details. Add the following details in the config.js file to configure the email details:

export const emailConfig = {
    service: process.env.EMAIL_SERVICE || 'gmail',
    user: process.env.EMAIL_USER || '',
    pass: process.env.EMAIL_PASS || '',
};

export const merchantEmail = process.env.MERCHANT_EMAIL || '';

Add the following environment variables to the .env file to configure the email service:

EMAIL_SERVICE=gmail
EMAIL_USER=your_email@gmail.com
EMAIL_PASS=your_email_password_here
MERCHANT_EMAIL=merchant@example.com

Note that if you're using Gmail, you need to configure OAuth 2.0 or generate an app password. This tutorial uses Gmail, but you can refer to the Nodemailer docs if you need to configure a custom SMTP transport.

Handle the Dispute Webhook

The PAYMENT_DISPUTE_CREATED webhook event contains information about the dispute, payment, and payment method. For example, you can retrieve the original_transaction_id to fetch transaction details.

Add the handleDisputeCreated method in the controllers/webhook.controller.js file as follows:

// add import
import EmailService from '../services/email.service.js';

const handleDisputeCreated = async (disputeData) => {
    const { token } = disputeData;
    console.log(`Dispute ID: ${token}`);

    try {
        await EmailService.sendDisputeNotification(disputeData);
        console.log(`Email notification sent for dispute: ${token}`);
    } catch (error) {
        console.error('Error handling dispute:', error);
    }
};

The method calls the EmailService.sendDisputeNotification method with the disputeData to notify the merchant about the dispute.

Next, update the handleWebhook method to call the dispute handler like this:

export const handleWebhook = (req, res) => {
    const event = req.body;
    switch (event.type) {
        ...
        case 'PAYMENT_DISPUTE_CREATED':
            console.log('Payment dispute created:', event.data);
            handleDisputeCreated(event.data);
            break;
        ...
    }
    ...
};

Now that the webhook is configured to send emails automatically, you can proceed to test the integration.

Test Automatic Dispute Resolution for Mastercard Transactions

Before testing the integration, you need to register the webhook endpoint on the Rapyd Client Portal to receive dispute events.

Register the Webhook

You need to expose Express on a public URL so that Rapyd can send webhook events to it. You can use ngrok to expose your web server as a public URL by executing the following command:

ngrok http http://localhost:8000

Once you execute the command, it creates a public proxy, and your output looks like this:

ngrok
...
Session Status                online
---OUTPUT TRUNCATED---
Forwarding                    https://3939-2601-602-9700-5c30-b883-8d8b-8def-708b.ngrok-free.app -> http://localhost:8000

Note the forwarding URL and navigate to the Rapyd Client Portal to register it. Under Developers > Webhooks > Management, click Edit URL and update the endpoint to the following:

https://<YOUR_FORWARDING_HOST_NAME>/api/webhook

Replace <YOUR_FORWARDING_HOST_NAME> with the forwarding URL's hostname. Make sure you save the changes for it to take effect:

Make sure that under Collect, the Dispute Created webhook event is checked to ensure that your web server receives it.

Test Automatic Dispute Resolution

The Simulating Cardholder Disputes guide lists a few card numbers that you can use to simulate a card payment dispute. When one of these cards is used to create a payment, Rapyd simulates a dispute flow by automatically creating a dispute for the completed payment.

To simulate a transaction dispute with a Mastercard card, execute the following curl command:

curl --location 'https://<YOUR_FORWARDING_HOST_NAME>/api/payment' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 26.51,
    "currency": "ZAR",
    "merchant_reference_id": "042620221450",
    "payment_method": {
        "type": "gb_mastercard_card",
        "fields": {
            "number": "5132803130357186",
            "expiration_month": "11",
            "expiration_year": "26",
            "cvv": "123",
            "name": "John Doe"
        }
    },
    "ewallets": [
        {
            "ewallet": "<YOUR_RAPYD_EWALLET_ID>",
            "percentage": 100
        }
    ],
    "metadata": {
        "merchant_defined": "created"
    },
    "capture": true,
    "payment_method_options": {
        "3d_required": false
    }
}'

Replace <YOUR_FORWARDING_HOST_NAME> with the ngrok hostname and <YOUR_RAPYD_EWALLET_ID> with your Rapyd wallet ID before executing the curl command. Once you execute the command, a payment is created, and within seconds, you'll receive a payment dispute webhook event for it. The dispute details are logged by the web server and look similar to this:

{
  ...
  "body": {
    ...
    "data": {
      "id": '0d37f5ca-0e7d-4c27-8476-2d3309e465b4',
      "token": 'dispute_8b36175b2121c5f4dffa9b624eb73b49',
      "status": 'ACT',
      "amount": 26.51,
      "currency": 'ZAR',
      "dispute_category": 'Cardholder Dispute',
      "dispute_reason_description": 'Cardholder Dispute',
      "original_transaction_currency": 'ZAR',
      "original_transaction_amount": 26.51,
      "original_dispute_amount": 26.51,
      "original_dispute_currency": 'ZAR',
      "original_transaction_id": 'payment_e5e014d419632d428023fcd5c8c3af53',
      ...
    }
  }
}

Because you configured the handleDisputeCreated method for Dispute Created events, it sends an email and logs the following to the console:

Dispute notification email sent: 250 2.0.0 OK  1751833493 d9443c01a7336-23c8455d09esm68323335ad.90 - gsmtp
Email notification sent for dispute: dispute_e9388a0a90c7366a96541f6b759c7de4

The configured MERCHANT_EMAIL receives an email as shown here:

You can also review the dispute details using the Collect > Review & Protect > Disputes tabs on the Rapyd Client Portal:

The Client Portal lets you update the status of the dispute, submit evidence, or refund a dispute.

You can find the entire source code used in this tutorial on GitHub.

Conclusion

Merchants need to proactively review and resolve card disputes to avoid chargebacks and revenue loss. They can leverage automatic dispute resolution tools like RDR and Mastercard Collaboration to configure rules that instantly evaluate dispute requests and issue automatic refunds if the criteria are met.

Rapyd enables businesses to automate dispute resolution by offering direct integration with Visa and Mastercard Collaboration programs, industry-leading authorization rates, and a robust all-in-one payment platform.

Try the Rapyd API and explore the code sample to see how Rapyd offers you the best in dispute resolution.

Client Portal: Stablecoin Payouts

mcduffin — Thu, 16 Oct 2025 21:32:05 +0000

Stablecoin payouts are the next evolution of the financial world: using cryptocurrency to make cross border transactions, using a digital, decentralized currency that allows you true financial freedom. By signing up for a Client Portal account, you can integrate with Rapyd today and begin using stablecoin payouts.

What is Stablecoin?

Stablecoin is a specific type of cryptocurrency that functions slightly differently than most cryptocurrencies. Most crypto derives their entire value from a form of digital scarcity. A limited number of the cryptocurrency is released and the users have to “mine” for this cryptocurrency by using algorithms to “search” for the cryptocurrency. When the crypto is found and verified, the user gets to keep the cryptocurrency. The most recognizable cryptocurrency that uses this model is Bitcoin.

An issue with cryptocurrency is its volatility. Although crypto can and does hold value, the value does not remain stable over time, but fluctuates wildly. This is partly due to cryptocurrency exchanges, and how the users treat crypto like an asset instead of a currency. When crypto is traded like an asset, it is bought and sold based on its perceived value. When crypto is treated like a currency, it is used to purchase everyday goods and services.

But Stablecoin is different. Although it uses the blockchain to verify transactions like all cryptocurrency, its value is pegged to both gold and fiat currency. This allows stablecoin to be “stable” and not experience sudden fluctuations in its value. This stability makes it favorable to be used as a currency in transactions such as payments and payouts. Rapyd now offers stablecoin payouts, allowing you to pay others using cryptocurrency.

Stablecoin Payout Features

When logging into the Client Portal, you can navigate to Disburse > Payouts and click the Create Payout button in the upper right corner. From there, you can create a payout, selecting UDSC as the payout currency.

When creating a payout, you can select the crypto account that has the stablecoin. And then define the beneficiary that will receive the payout. Fiat currency can also be converted to stablecoin when making the payout. The beneficiary can either be an individual or a company. You also need to agree to the provided Terms and Conditions before completing the crypto payout.

See Creating a Crypto Payout for more detailed information.

Rapyd and Using Stablecoin

Rapyd now offers stablecoin payouts through the Client Portal, and through the Rapyd API using the Create Payout endpoint. See Stablecoin Payout for more detailed information about how to complete a stablecoin payout using the API. Using stablecoins is useful because it gives you another financial tool that you can use. Both USDC and USDT are offered as payout currencies, and are now supported currencies.

Fintech and stablecoin blend together perfectly because both represent moving outside of the traditional financial establishment and represent the efforts to try and create a better path for all parties involved.

When using the Rapyd Client Portal, you can have a chance to enter the cryptocurrency world using a no-code solution. The process of using stablecoin is simplified. Rapyd provides the best available options to broaden your financial horizons.

Client Portal: The No-Code Solution to Your Financial Needs

mcduffin — Thu, 02 Oct 2025 18:46:43 +0000

The Rapyd Client Portal is a self-service product that allows developers and merchants to manage the financial information and services that Rapyd provides. Users can quickly view the information they need, generate a useful report, or create a payment. The Client Portal turns complex financial operations into simple tasks.

No-Code Solutions

Rapyd offers a no-code solution to our customers through the Client Portal. The portal is a point-and-click interface with various fields where important information can be entered. Files can be uploaded and downloaded. The Client Portal is a key component for merchants who wish to integrate with Rapyd. The KYB or Know Your Business Form is a required form used to verify a new business working with Rapyd. This form can be completed from the Client Portal.

For developers that wish to integrate with Rapyd via code, they can use the Rapyd API. But the Client Portal is also important to these developers. Your API access key and secret key are securely stored in your Client Portal account, and are needed to make calls via the Rapyd API.

Client Portal Features

The Client Portal has a wide range of features that allows users to interact with Rapyd’s core product offerings: Collect, Disburse, Issuing, and Rapyd Wallets. The first set of features center around viewing financial information. For example, users can view their payments, payouts, or a list of issued cards. Each line item in those lists can be expanded to provide additional details and financial information. The second set of features center around performing financial operations. This can include creating a payment, creating a payment link, creating a payout, creating a beneficiary, issuing a card, or creating a Rapyd Wallet. The third set of features center around file downloads, file uploads, and generating financial reports.

Developers can manage their API Keys, whitelist IP addresses, and manage their webhooks in the sandbox environment under the Developers section of the Client Portal. Users can also rotate their API keys as an added security measure. Other tools are available to use via the Client Portal such as Rapyd Protect. You can use machine learning to flag and block fraudulent transactions.

How Rapyd Can Help You

The Rapyd Client Portal can meet your financial needs because it simplifies the complex. It allows the user to quickly find needed financial information, and streamline tasks like initiating a cross-border payout. The portal provides a central place for all of your financial information, and allows you to manage linked accounts, card disputes, and generate hosted pages to name a few examples. The accurate financial reports allow you to plan for a successful financial future and identify patterns that can be used to boost your business performance. Even repetitive tasks like managing subscriptions become easy when you use the Client Portal. You can create an account here and begin by experimenting in the sandbox environment. The Client Portal represents an opportunity to create a better financial future.

Fintech and SWIFT: How Fintech and Traditional Finance Work Together

mcduffin — Fri, 19 Sep 2025 15:43:59 +0000

SWIFT is a facet of the traditional financial system, facilitating international payments and payouts. The SWIFT network is most often used by a wide range of organizations, from large banks and corporations to small businesses.

Fintech is a newer addition to the financial world. Fintech companies often build their own financial network that provide similar services. This is an effort to help reduce the red tape involved and improve the settlement times for transactions.

But sometimes, these two different systems need to work together to take advantage of their strengths. The traditional financial systems usually have a farther reach, and have a larger number of users. Fintech companies have unique product offerings that are tailored to their customer base, and are often more lean and efficient when compared to traditional finance.

When fintech networks integrate with the larger traditional financial system, it can allow a wider base of customers to create payments and payouts that have the widest reach and the fastest settlements with the least amount of compliance issues. The two types of financial networks can work together to form a greater whole.

What is SWIFT?

SWIFT or the Society for Worldwide Interbank Financial Telecommunication is an important element of the traditional financial system. SWIFT is a network of financial institutions that facilitate cross-border payments and disbursements. It is the main system used for international payments and payouts between countries.

An important data standard, called ISO 20022, is used to standardize financial information that is used for a transaction. This enables a uniform system that can be used by financial institutions across the globe. Another important element of the SWIFT system is the BIC SWIFT code. The BIC (Business Identifier Code) is used to identify financial institutions and businesses when making a transaction. Including the BIC in the payment or payout request ensures that the transaction is routed to the correct beneficiary bank or beneficiary business.

Rapyd and SWIFT

Rapyd offers a payout method type through SWIFT using the Rapyd API. You can call the Rapyd API to use the xx_swift_bank payout method and create a cross-border payout using SWIFT.

The user documentation for SWIFT payouts includes information about regex, workflows, supported sender currencies, and required fields by country that are needed to create a SWIFT payout. Examples of a SWIFT payout are included. Additional information about purpose codes are included. Purpose codes are required for specific countries.

Fintech and Traditional Finance Working Together

Fintech and traditional finance are like two sides of the same coin. Both systems share some similarities and differences. When fintech becomes integrated with traditional financial systems, this allows you to experience the greatest benefits by having increased options, decreased settlements times, and a secure, reliable way to disburse funds across the globe. When fintech services become integrated with traditional financial services, a unified financial network is created that can best meet your financial needs.

The Rapyd Partnership Program: What Rapyd Brings to Partners

mcduffin — Fri, 12 Sep 2025 20:50:21 +0000

Rapyd offers a unique opportunity through the Partnership Program. In this program, partners can work with Rapyd and gain access to the Rapyd API, the Partner Portal and other features aimed to smooth their operational flows, enable better tracking of merchants and transactions, and a system to manage their financial information with ease.

Rapyd stands apart from the competition by providing an experience that is tailored to partners. For example, Rapyd provides a faster onboarding experience for partners. The Partner API Reference documents how partners can manage their KYB applications via the API. Partners can view account information such as offerings and organizations by making an API call.

Rapyd provides the Partner Portal, a self service option that allows partners to:

Add and invite merchants
Create custom pricing
Manage sign-up links for your merchants

The Rapyd Partnership Program

The Rapyd Partnership Program serves three different partner types: Independent Sales Organizations (ISOs), Payment Facilitators (PayFacs) and Referral Partners.

A partner can sign an agreement with Rapyd, and then begin the integration and onboarding process. Rapyd is an ideal solution for partners. We can provide the services and financial infrastructure that partners need.

Rapyd provides extensive support to each partner that works with Rapyd. Our support teams ensure that each partner has a smooth experience and quick resolution times to any problems that could arise.

Partnership Types

Here is some additional information about each partner type:

Independent Sales Organization - An Independent Sales Organization (ISO) helps to contract and manage payment services for their merchants. ISOs directly interact with payment service providers like Rapyd to help manage the financial needs of their merchants.

Payment Facilitator - Payment Facilitators (PayFacs) help to facilitate payments for their merchants. They provide a specific range of services. PayFacs partner with payment service providers like Rapyd to contract and settle on behalf of their merchants.

Referral Partner - Referral partners are payment experts who refer merchants to a payment service provider, like Rapyd. Each merchant adheres to the agreement with the payment service provider, so the Referral Partner doesn’t need to manage the merchants directly.

What Rapyd Brings to Partners

Join the Rapyd Certified Partner Program and reap the benefits of our partnership expertise. Rapyd supports Independent Sales Organization (ISO), Payment Facilitator (PayFac) and Referral Partners.

Rapyd provides an array of support and benefits for partners that only get better as their business with Rapyd grows.

ISOs and Referral Partners can utilize the Rapyd API and the Partner Portal. The Partner Portal is a self-service option that enables the partner to manage their merchants, signup links, and pricing. Partners can easily onboard merchants and link them to their account.

PayFacs are supported via the Rapyd API. They can create card payments, APM payments, and create payouts with Rapyd.

Conclusion

The Rapyd Certified Partner Program is an excellent opportunity for partners to integrate with Rapyd. Rapyd provides the best solution for partners, including support via the Partner Portal and the Rapyd API.

Rapyd helps partners to manage their merchants, track financial information, and offer custom pricing structures, in addition to signup links. Such features are financial tools that partners can use to build a better financial future.

Multi-Currency Payment Systems: Using Rapyd’s Global Payment APIs

mcduffin — Fri, 12 Sep 2025 20:34:53 +0000

A UK-based SaaS company wants to pay its freelance designer in Brazil. They invoice in GBP, but she wants BRL in her account. Here’s how Rapyd makes that happen in seconds, not weeks.

Multi-currency payment systems are crucial for creating cross-border solutions and integrating into a globalized financial network. Creating payments where funds are collected, or creating payouts where funds are disbursed is a staple feature of Rapyd’s core offering. The ability to use multiple currencies through FX or Foreign Exchange allows merchants across the globe to use a solution that meets their financial needs.

What Are Multi-Curency Payment Systems?

A multi-currency payment system is a network comprising several elements including payment processors, payment gateways, forex exchanges, payment service providers, and banks. All of these elements form a network to facilitate payments that use multiple different currencies.

The key features of a multi-currency payment system include the ability to use different currencies in the same payment or payout. For example, a merchant could create a payout and select USD as the sender currency. But their employee lives in France, and would like to be paid in EUR. So the beneficiary currency would be EUR, and the funds would be converted into EUR via FX or Foreign Exchange.

Payment systems that allow multiple currencies to be used allow a truly globalized system to form. The benefits of using multiple currencies include customers using their local currency, ease of use for cross-border transactions, and using payment and payout methods that are faster and more efficient.

Foreign Exchange (FX) in Fintech

Foreign exchange (FX) is the act of converting one currency to another during a transaction. A payment gateway is used in the conversion process. The latest currency conversions and rates are used.

The fintech industry has helped to revolutionize FX by offering real-time transactions that use different currencies. The overall process has less red tape, and is easier to use when compared to using a more traditional bank or financial institution.

The ability to make settlements using your preferred currency is beneficial, especially when using local bank accounts and banking institutions.

Global Payment APIs

Rapyd offers a flexible and easy to use solution through our global payment APIs. The two main API calls used are Create Payment and Create Payout. Creating payments is under the Collect product offering, while creating payouts is under the Disburse product offering.

Additional elements include a variety of payment method types, payout method types, and supported currencies. Rapyd offers a wide variety of supported currencies for payments, payouts, settlements, and virtual accounts.

For example, your business based in Europe sells merchandise on your online store. A customer from the United States wants to purchase a product from you that costs 370 EUR (Euros). But the customer uses a payment method that only supports USD (U.S. Dollars). You would Create a Payment with FX using the Rapyd API.

You can use hundreds of different payment method types with Rapyd, which include ewallets, bank transfers, bank redirects, cash payments, and card payments. Supported regions include the Americas, APAC, and EMEA. You can use your preferred payment method types with the Rapyd API.

Multi-currency payment systems are a key component of globalized financial networks. They allow the merchant to use multiple different currencies for both payments and payouts. This kind of system can offer the flexibility and ease of use for merchants that operate on a global scale and need cross-border financial solutions. Rapyd is a leader in providing multi-currency payment systems accessible through the Rapyd API. Learn more about Rapyd and integrate with us today. Leave a comment below about your experience using our APIs.

Blockchain Interoperability: Connecting Multiple Blockchain Networks for Payments

Drew Harris — Tue, 09 Sep 2025 17:46:17 +0000

Writer Name: Vivek Kumar Maskara

Blockchain is a decentralized and immutable digital database or ledger that's distributed across a network of computers in a transparent and tamperproof manner.

Blockchain interoperability refers to the ability of blockchains to communicate and share data with other blockchains. This enables developers to build cross-chain solutions that combine the strengths of each blockchain. For example, financial applications need blockchain interoperability to enable smooth cross-chain transactions and to improve liquidity, accessibility, and expand financial inclusion.

In this article, you'll learn how to implement blockchain interoperability using Solidity smart contracts for payment verification.

Why Fintech Applications Need Blockchain Interoperability

If you're building a decentralized application (dApps), you need blockchain interoperability. This allows your app to interact with different blockchain networks, expanding the app's access to assets, usability, and scalability.

Here are a few benefits of blockchain interoperability:

Seamless cross-chain transactions: Blockchain interoperability enables users to transfer assets across different blockchain networks without relying on centralized exchanges or manually converting them to fiat currency.
Lower transaction costs and faster settlement: It reduces the need for intermediaries to carry out a transaction, optimizes payment processing costs, and enables faster settlement across blockchain networks.
Improved liquidity and accessibility: It connects fragmented payment ecosystems, allowing users to access a wider liquidity pool to exchange their tokens. For example, a user can transfer USDT from Ethereum (ERC-20) to the Tron network to take advantage of lower fees and faster transaction speeds. This enhances financial accessibility for global users as they can transfer their assets to a different chain based on their needs.
Expanded financial inclusion: Supporting multichain compatibility enables fintech applications to reach more users and businesses, even in regions where traditional financial services are limited.

Simplifying Payment Verification with Rapyd

Blockchain interoperability sounds great in theory: move assets and data across networks seamlessly. But building a complete payment verification system requires significant developer effort. Smart contracts struggle to handle real-world requirements, like fiat conversions, regulatory compliance, fraud prevention, and off-chain settlement on their own, especially when these systems must remain reliable and responsive at scale.

Thankfully, Rapyd offers a robust financial infrastructure with easy-to-integrate REST APIs that offload the hard parts for you. It acts as an off-chain settlement layer and cross-chain data exchange, enabling use cases like automated compliance checks, escrow, and transaction verification, without requiring developers to build and maintain that infrastructure themselves.

From real-time fraud prevention and automated global KYC/AML to fiat on/off-ramps in over 100 countries, Rapyd removes the traditional finance complexity from blockchain payments. The Rapyd API platform simplifies the end-to-end financial workflow:

The Collect Payments API receives funds from various payment methods and deposits them into Rapyd Wallets.
The Rapyd Verify APIs perform hosted Know Your Business (KYB) and Know Your Customer (KYC) verifications to meet compliance requirements.
The Rapyd Protect APIs detect fraud and suspicious activity through built-in risk scoring, enhancing compliance and eliminating the need to build custom fraud logic.
Webhooks receive real-time notifications for key events, such as payment status changes or verification updates.

As an off-chain infrastructure layer, Rapyd also aligns with one of the core principles of blockchain systems: availability. Even during peak congestion or transaction delays on the blockchain, Rapyd continues to operate reliably, ensuring high availability for compliance, verification, and settlement workflows.

Implementing Blockchain Interoperability

In this tutorial, you'll build, deploy, and test smart contracts on Ethereum testnets like Sepolia and Holesky. The tutorial uses the Hardhat developer environment to easily deploy your Solidity smart contracts and test them using the Hardhat network, which is a local Ethereum network designed for development.

Here are the primary components of the project:

CrossChainPayment is a simple smart contract that initiates a cross-chain transaction and emits the PaymentSent event.
PaymentVerifier is another smart contract that simulates a cross-chain transaction verification and emits the PaymentVerified event. For simplicity, it doesn't perform any complex checks, but it can be extended based on the use case.
relay.js script watches for events on the source chain (ie Sepolia) with the destination chain as Holesky and invokes the verifyPayment method of the destination chain.

Prerequisites

Before you get started, you need to do the following:

Install a Node.js development environment.
Sign up for an Alchemy account and create an API key.
Set up Metamask and create a wallet.
Obtain a Metamask account private key.
Fund your Metamask wallet using Google Cloud's Ethereum Holešky and Sepolia Faucet. You can use any faucet of your choice, but some faucets may require a minimum wallet balance to receive funds.

Cloning the Starter Project

This tutorial uses this GitHub starter code that has a barebones Hardhat app set up. To follow along, clone the GitHub repo and switch to the starter branch:

git clone https://github.com/Rapyd-Samples/rapyd-starter-blockhain.git
cd rapyd-starter-blockhain
git checkout starter

Let's go over the structure of the codebase:

The package.json file defines the Hardhat project dependencies. It uses the Hardhat dependency to get an Ethereum development environment and uses @nomicfoundation/hardhat-toolbox to get all the common Hardhat plugins.
The contracts directory contains a sample Lock.sol solidity smart contract. You won't need it in the tutorial, but you can use it to understand the basic structure of a Solidity smart contract.

Defining Smart Contracts for Cross-Chain Transaction Verification

In this section, you'll define two smart contracts to enable cross-chain transaction verification.

CrossChainPayment contract

Initially, you'll define the CrossChainPayment that initiates a cross-chain payment and emits the PaymentSent event. Here, you'll define a simple smart contract that checks for amount mismatch issues before emitting the PaymentSent event.

Create a contracts/CrossChainPayment.sol file and add the following code snippet to it:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract CrossChainPayment {
    event PaymentSent(address indexed from, address indexed to, uint256 amount, uint256 chainId);

    function sendPayment(address to, uint256 amount, uint256 destChainId) external payable {
        require(msg.value == amount, "Amount mismatch");
        emit PaymentSent(msg.sender, to, amount, destChainId);
    }
}

The smart contract defines a sendPayment function that does the following:

It takes the to address and amount for sending the payment, and it asserts that the amount matches the value set by the sender in the msg payload.
It emits a PaymentSent event with the sender's address (msg.sender), receiver's address (to), amount, and destination chain ID (destChainId).

PaymentVerified contract

Now it's time to define the PaymentVerifier that will be invoked by the relayer (more on this later). The PaymentVerifier smart contract contains the verifyPayment method, where on-chain verification can be performed before emitting the PaymentVerified event.

Create a contracts/PaymentVerifier.sol file and add the following code snippet to it:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract PaymentVerifier {
    event PaymentVerified(address indexed to, uint256 amount, uint256 srcChainId, bytes32 txHash);

    function verifyPayment(address to, uint256 amount, uint256 srcChainId, bytes32 txHash) external {
        // perform verification steps
        emit PaymentVerified(to, amount, srcChainId, txHash);
    }
}

This contract doesn't perform a full cross-chain verification on its own. It acts as a receiver for cross-chain data, and usually, a relayer or a middleware service invokes the verifyPayment method of the contract. This method expects the transaction receiver's address (to), amount, source chain ID (srcChainId), and the transaction hash (txHash). These fields will be supplied by the relayer while invoking the contract.

The txHash refers to the on-chain transaction hash and can be used to perform additional transaction checks before emitting the PaymentVerified event. For this tutorial, the smart contract emits the event without any checks.

Note that in a real-world system, the PaymentVerifier contract can be extended to include more extensive verification checks, such as validating signatures and cryptographic proofs.

Defining Scripts to Deploy the Smart Contracts

Now that you've defined the smart contracts, you need to deploy them to test blockchain networks (testnets) before you can use them.

To deploy the smart contracts, you can use a node script that uses the hardhat SDK to deploy the smart contract and print its address. To deploy the CrossChainPayment contract, create a scripts/deploy_crosschain.js script and add the following contents to it:

const hre = require("hardhat");

async function main() {
  const Contract = await hre.ethers.getContractFactory("CrossChainPayment");
  const contract = await Contract.deploy();

  await contract.waitForDeployment();
  console.log("Contract deployed to:", await contract.getAddress());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

The Hardhat SDK creates an instance of the Ethers ContractFactory to convert the CrossChainPayment solidity contract into bytecode and deploys it on the blockchain network.

Before using the script, you need to make sure that the network is configured under hardhat.config.js. You also need to specify the network name as a CLI parameter while using the script. More on this in a later section.

Similarly, to deploy the PaymentVerifier contract, create a scripts/deploy_paymentverifier.js file and add the following contents to it:

const hre = require("hardhat");

async function main() {
  const Contract = await hre.ethers.getContractFactory("PaymentVerifier");
  const contract = await Contract.deploy();

  await contract.waitForDeployment();

  console.log("Contract deployed to:", await contract.getAddress());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

This script converts the PaymentVerifier contract into bytecode and deploys it. Notice that both the contract deployment scripts are quite similar, and you could also parameterize the script and pass the contract name as a CLI argument.

Deploying the Smart Contracts to testnets

This tutorial uses the Sepolia and Holesky testnets. Because deploying a smart contract to a network requires gas, make sure to fund your wallet with tokens using a faucet like Google Cloud's Ethereum Holešky or Sepolia Faucet.

Before deploying the smart contracts, you need to configure the desired testnets in the hardhat.config.js file. Update the contents of the hardhat.config.js file with the following code snippet:

require("@nomicfoundation/hardhat-toolbox");
require("dotenv").config();

module.exports = {
  solidity: "0.8.20",
  networks: {
    sepolia: {
      url: process.env.SEPOLIA_RPC,
      accounts: [process.env.PRIVATE_KEY],
      chainId: 11155111,
    },
    holesky: {
      url: process.env.HOLESKY_RPC,
      accounts: [process.env.PRIVATE_KEY],
      chainId: 17000,
    },
  },
};

This snippet updates the network configuration to add sepolia and holesky testnets. Notice that the config file uses SEPOLIA_RPC, HOLESKY_RPC, and PRIVATE_KEY environment variables. To configure environment variables, create a .env file in the project's root and add the following contents to it:

PRIVATE_KEY=<YOUR_META_MASK_PRIVATE_KEY>
SEPOLIA_RPC=<YOUR_ALCHEMY_SEPOLOIA_TEST_NET_HTTPS_RPC_URL>
SEPOLIA_WSS=<YOUR_ALCHEMY_SEPOLOIA_TEST_NET_WSS_RPC_URL>
HOLESKY_RPC=<YOUR_ALCHEMY_HOLESKY_TEST_NET_HTTPS_RPC_URL>

Replace <YOUR_META_MASK_PRIVATE_KEY> with the Metamask wallet's private key obtained earlier. Replace <YOUR_ALCHEMY_SEPOLOIA_TEST_NET_HTTPS_RPC_URL> and <YOUR_ALCHEMY_HOLESKY_TEST_NET_HTTPS_RPC_URL> with your HTTPS RPC URL from the Alchemy dashboard:

Additionally, make sure you replace <YOUR_ALCHEMY_SEPOLOIA_TEST_NET_WSS_RPC_URL> with the WebSocket (WSS) RPC URL obtained from the Alchemy dashboard.

Now that your environment variables and Hardhat configuration are set up, you can deploy the contracts. Either of these chains can be used as a source or destination for a transaction, so you need to deploy PaymentVerifier and CrossChainPayment contracts to both Sepolia and Holesky chains.

Execute the following command to deploy the CrossChainPayment to the Holesky chain:

npx hardhat run scripts/deploy_crosschain.js --network holesky

It might take a few seconds for the contract to deploy, and it outputs the contract address like this:

Contract deployed to: 0x09292e7C53697DFcdBA3c51425bb7e36d7F6Ef2a

Note the contract address and deploy the PaymentVerifier contract to the Holesky chain by executing the following:

npx hardhat run scripts/deploy_paymentverifier.js --network holesky

Then, deploy the CrossChainPayment to the Sepolia chain:

npx hardhat run scripts/deploy_crosschain.js --network sepolia

Finally, deploy the PaymentVerifier to the Sepolia chain:

npx hardhat run scripts/deploy_paymentverifier.js --network sepolia

Make sure to save all the contract addresses as you will need them while defining the relay script.

Defining the Relay Script

Now that the smart contracts are defined, you need to define a relay script that will listen for PaymentSent events on the source chain. When it finds a PaymentSent event, it matches the destination chain ID and triggers the verifyPayment smart contract method on the destination chain.

Create a scripts/relay.js file and add the following code snippet to it:

const { WebSocketProvider, JsonRpcProvider, Contract, Wallet } = require("ethers");
require("dotenv").config();

// Use WebSocket for Sepolia (where we're listening for events)
const SEPOLIA_WSS = process.env.SEPOLIA_WSS;
const HOLESKY_RPC = process.env.HOLESKY_RPC;
const PRIVATE_KEY = process.env.PRIVATE_KEY;

const SEPOLIA_CONTRACT = "<YOUR_CROSS_PAYMENT_SEPOLIA_ADDRESS>";
const HOLESKY_VERIFIER = "<YOUR_PAYMENT_VERIFIER_HOLESKY_ADDRESS>";

const eventAbi = [
    "event PaymentSent(address indexed from, address indexed to, uint256 amount, uint256 chainId)"
];

const verifierAbi = [
    "function verifyPayment(address to, uint256 amount, uint256 srcChainId, bytes32 txHash)"
];

async function startRelayer() {
    // Use WebSocketProvider for event monitoring
    const sepoliaProvider = new WebSocketProvider(SEPOLIA_WSS);
    const holeskyProvider = new JsonRpcProvider(HOLESKY_RPC);
    const wallet = new Wallet(PRIVATE_KEY, holeskyProvider);

    const sourceContract = new Contract(SEPOLIA_CONTRACT, eventAbi, sepoliaProvider);
    const verifier = new Contract(HOLESKY_VERIFIER, verifierAbi, wallet);

    console.log("Relayer is watching for events on Sepolia via WebSocket...");

    // Set up reconnection logic
    sepoliaProvider.websocket.on('close', (code) => {
        console.log(`WebSocket connection closed with code ${code}. Reconnecting...`);
        setTimeout(startRelayer, 3000);
    });

    // Listen for events using WebSocket
    sourceContract.on("PaymentSent", async (from, to, amount, chainId, event) => {
        console.log("PaymentSent Detected:");
        console.log({ from, to, amount: amount.toString(), chainId });

        if (chainId.toString() !== "17000") {
            console.log("Skipping non-Holesky destination.");
            return;
        }

        try {
            // Get transaction hash from event and ensure it's in bytes32 format
            const txHash = event.log.transactionHash;

            const tx = await verifier.verifyPayment(
                to,
                BigInt(amount.toString()),
                11155111,
                txHash
            );
            console.log("Verification TX sent:", tx.hash);
        } catch (err) {
            console.error("Error verifying payment:", err.message);
            console.log("Error details:", err);
        }
    });

    // Handle process termination
    process.on('SIGINT', async () => {
        console.log('Closing WebSocket connection...');
        await sepoliaProvider.destroy();
        process.exit();
    });
}

// In case of connection errors, restart the relayer
try {
    startRelayer();
} catch (error) {
    console.error("Error starting relayer:", error);
    setTimeout(startRelayer, 3000);
}

To interact with the Sepolia and Holesky chains, this code creates an instance of the JsonRpcProvider. The relay script assumes that the transaction will be initiated on the Sepolia chain and starts listening for the PaymentSent events on this chain. It sets the Holesky chain as the destination chain, creates an instance of the PaymentVerifier contract deployed on it, and invokes the verifyPayment method using the payload received in the PaymentSent event.

This setup enables blockchain interoperability by bridging event data between two separate chains. It captures transactions on the source chain (Sepolia) and triggers verification logic on the destination chain (Holesky), without requiring a built-in bridge or shared state between them.

Testing Cross-chain Interactions

With smart contracts deployed to both Sepolia and Holesky chains and the relay scripts in place, you can test blockchain interoperability. The goal of testing is to verify the following:

Initiate a cross-chain transaction on the Sepolia chain using the sendPayment method defined in the CrossChainPayment. Once the transaction is complete, you will receive a ContractTransactionResponse confirming the successful completion of the transaction.
Within a few seconds of completion, the relay script should receive a PaymentSent event from the CrossChainPayment contract deployed on the Sepolia chain. The script should invoke the verifyPayment method defined in the PaymentVerifier contract deployed on the Holesky chain.
On invocation, the PaymentVerifier contract deployed on the Holesky chain should verify the transaction and return a successful response.

Before you begin testing, start the relay script in a new terminal window:

# Execute this command in the project's root directory
node scripts/relay.js

This code starts the relay script, which listens for events on the Sepolia chain.

To initiate a transaction on the Sepolia chain, start the hardhat console for the sepolia network by executing the following command in the project's root in a separate terminal window:

# Execute this in the project's root
npx hardhat console --network sepolia

This command starts the hardhat console, where you can execute smart contracts and perform transactions. To initiate a cross-chain payment, paste the following script in the hardhat console:

// Get ethers from Hardhat runtime
const { ethers } = hre;

// Load your deployed contract
const contract = await ethers.getContractAt("CrossChainPayment", "0x45d88f6DD0f0eDB69C563233Be73458c9980b519");

// Send payment
await contract.sendPayment(
  "0x11ddd4b07B095802B537267358fB8Eb954B29d99",            // Recipient
  ethers.parseEther("0.001"),                              // Amount
  17000,                                                   // Destination Chain ID (Holešky)
  { value: ethers.parseEther("0.001") }                    // Payment value
);

Note that if the terminal prompts you to confirm pasting multiple lines of code, click Paste to confirm the action. Once you paste the code and press Enter, you will receive a ContractTransactionResponse confirming that the transaction was successful:

ContractTransactionResponse {
  provider: HardhatEthersProvider {
    _hardhatProvider: LazyInitializationProviderAdapter {
      _providerFactory: [AsyncFunction (anonymous)],
      _emitter: [EventEmitter],
      _initializingPromise: [Promise],
      provider: [BackwardsCompatibilityProviderAdapter]
    },
    _networkName: 'sepolia',
    _blockListeners: [],
    _transactionHashListeners: Map(0) {},
    _eventListeners: []
  },
  blockNumber: null,
  blockHash: null,
  index: undefined,
  hash: '0xa2bd160eb0bfde7b1eadbde6c3a1c3a19f876ed5e8731e0d32d582628ba5e361',
  type: 2,
  to: '0x45d88f6DD0f0eDB69C563233Be73458c9980b519',
  from: '0xcD0AAcf118B43C0878D90886f0e1D54D043CF726',
  nonce: 7,
  gasLimit: 25215n,
  gasPrice: 55068367n,
  maxPriorityFeePerGas: 50000000n,
  maxFeePerGas: 55068367n,
  maxFeePerBlobGas: null,
  data: '0x8d82e72f00000000000000000000000011ddd4b07b095802b537267358fb8eb954b29d9900000000000000000000000000000000000000000000000000038d7ea4c680000000000000000000000000000000000000000000000000000000000000004268',
  value: 1000000000000000n,
  chainId: 11155111n,
  signature: Signature { r: "0x9c0bc7dd319671a3bf13c09e3d0b7398529fe0805055a86ecb41fc7a0a2c76f8", s: "0x047fcab2b6594f02d3fa8b3d0a00e92364b8c1a41713126cd2974bc15d00dd52", yParity: 0, networkV: null },
  accessList: [],
  blobVersionedHashes: null
}

The response contains details about the executed transaction, including the transaction hash (hash), the sender's address (from), the receiver's address (to), and the hashed transaction payload (data).

Head back to the relay script's terminal window, and within a few seconds, you should see a PaymentSent event log printed in the console:

PaymentSent Detected:
{
  from: '0xcD0AAcf118B43C0878D90886f0e1D54D043CF726',
  to: '0x11ddd4b07B095802B537267358fB8Eb954B29d99',
  amount: '1000000000000000',
  chainId: 17000n
}

Notice that the from and to addresses in the event match the addresses received in the ContractTransactionResponse. The relay script will invoke the verifyPayment contract on the Holesky chain, and within a few seconds, a transaction verification log will be printed in the console:

Verification TX sent: 0xb034b9bcd67eb3b58615fcdcd3704df70f75608bda16c1f2a454dc0f200a14dd

Conclusion

In this tutorial, you learned how to achieve blockchain interoperability by building smart contracts using Solidity and Hardhat. Smart contracts can be used to initiate cross-chain transactions and verify them based on preset rules. This lets developers connect and share data between isolated blockchains, helping them build innovative applications.

However, developing extensive verification checks to handle different scenarios relating to fraud, settlement, and compliance can be challenging for developers. With Rapyd, developers can focus on their core application logic, whether on-chain or off-chain, while relying on Rapyd to handle the complexity of compliance, identity verification, and secure settlement. More than just a complementary tool, Rapyd serves as your fiat bridge and compliance co-pilot by simplifying off-chain infrastructure, allowing teams to focus on delivering innovative, seamless, and scalable payment experiences faster.

Experiment with the Rapyd API and the code used in this tutorial to discover how Rapyd can offer you the best in building an interoperable payment system.

Creator Economy: How to Manage Royalties, Payouts, and Subscriptions with Rapyd

Drew Harris — Tue, 08 Jul 2025 09:00:00 +0000

By: Gourav Bais

The creator economy is all about the creation, collection, distribution, and monetization of content, skills, or products. Today's creators—whether YouTubers, streamers, educators, or musicians—are entrepreneurs. And behind every piece of digital content, there's usually an overlooked task: managing payments.

Creators have to juggle multiple income streams, including ad revenue, brand deals, subscriptions, affiliate commissions, digital product sales, brand partnerships, and direct fan contributions. Managing this mix means dealing with royalties, fluctuating transaction fees, and cross-border payouts. Creators need a payment system that simplifies operations, supports global subscriptions, and makes it easy to pay collaborators and affiliates.

In this article, you'll learn how Rapyd can help creators manage payments, receive international transactions, and simplify financial operations.

Core Payment Requirements in the Creator Economy

Managing payments isn't just about moving money from point A to B; it's also about how the transfer happens: the speed, cost, currency, compliance, and overall user experience. Let's take a look at the core payment requirements that define how financial transactions work in the creator economy.

Royalty Payments

Royalty payments can be complicated for creators collaborating on podcasts, music, or shared ad revenue. One of the biggest challenges is tracking revenue sources across platforms and ensuring everyone gets their fair share. Delays or errors in royalty distribution can damage trust and often lead to disputes when multiple parties are involved across various locations.

Clear, reliable royalty payments are key to maintaining long-term partnerships.

Affiliate Payouts

Affiliate marketing allows influencers and creators to earn commissions by promoting products or services—but managing multiple affiliates with varying rates, performance metrics, and payout schedules is tricky. Tracking earnings and calculating variable commissions based on clicks, sales, and engagement can also become increasingly difficult at scale.

To keep up, creators need tools that can not only automate payment calculations but also scale seamlessly as the affiliate networks expand.

Subscription Management

Subscriptions provide a steady stream of income and build a loyal community. But handling subscription-based businesses is often challenging, especially when it comes to handling recurring payments and renewals across different regions and currencies.

Subscriptions can also have multiple tiers, and each tier can have its own pricing, benefits, and audience. Managing these tiers requires a flexible system that can accommodate upgrades, downgrades, cancellations, and trial periods without disrupting the user experience.

Benefits of Using Rapyd APIs for Creator Payment Systems

Rapyd's suite of APIs provides the necessary infrastructure to scale payments efficiently, securely, and globally. It simplifies complex creator payment workflows by providing the following:

Simplified integration for complex payment flows: With a few lines of code, developers can integrate revenue sharing, automate payouts, and manage subscription billing, all within a single platform.
Support for global payouts in multiple currencies: Rapyd supports payouts to over 190 countries in more than 70 currencies. This helps creators send and receive payments globally without dealing with separate banking integrations or third-party processors.
Enhanced security with tokenization and PCI compliance: Rapyd provides security features like end-to-end tokenization, and sensitive data like card details is never stored on your servers. It also offers built-in PCI DSS compliance, helping platforms meet regulatory requirements.

Implementing a Creator Payment System with the Rapyd API

In this walkthrough, you'll learn how to build a basic creator payment system using Rapyd's API—covering royalties, affiliate payouts, and subscription management. We'll use Python and FastAPI to bring it all together.

Prerequisites

Before you begin, you'll need the following prerequisites:

A free Rapyd sandbox account. After registering, go to the Developers section to find your access key and secret key—you'll need these to access Rapyd's APIs.
Python 3.8+ installed on your system.
The FastAPI, uvicorn, Requests, and python-dotenv libraries. You can install these with the following command:
```
pip install fastapi uvicorn requests python-dotenv
```

You'll also need to create a folder to store all your scripts and files. You can name it something like creator_economy_rapyd_implementation.

Create a Rapyd Authentication File

Rapyd requires authentication to use its services. It's recommended that you use a .env file to store all your credentials.

Create a .env file inside your project folder and write the following lines of code, replacing your_access_key_here and your_secret_key_here with your actual credentials:

RAPYD_ACCESS_KEY=your_access_key_here
RAPYD_SECRET_KEY=your_secret_key_here

Create another file named rapyd_utils.py inside the same folder and import the necessary Python libraries:

import os
import time
import json
import hmac
import base64
import hashlib
import requests
from dotenv import load_dotenv

Once the libraries are imported, load the environment variables mentioned in the .env file:

load_dotenv()

Then, load the Rapyd credentials and define the Rapyd URL you'll use to access their services:

access_key = os.getenv("RAPYD_ACCESS_KEY")
secret_key = os.getenv("RAPYD_SECRET_KEY")
base_url = "https://sandboxapi.rapyd.net"

Once you've loaded your Rapyd credentials, it's time to implement Rapyd authentication with the following lines of code:

def generate_signature(http_method, url_path, salt, timestamp, body=''):
    body_str = json.dumps(body, separators=(',', ':')) if body else ''
    to_sign = f'{http_method}{url_path}{salt}{timestamp}{access_key}{secret_key}{body_str}'
    h = hmac.new(secret_key.encode(), to_sign.encode(), hashlib.sha256)
    return base64.b64encode(h.digest()).decode()

This function generates a signature to validate each request made to Rapyd's API. To ensure the request is coming from a validated source, Rapyd needs each request to be signed using HMAC-SHA256. This code uses the following variables:

url_path: The endpoint being called, like /v1/account/transfer.
salt: A randomly generated string to prevent replay attacks.
timestamp: The current UNIX timestamp to ensure freshness.
body: An optional request body for POST and PUT methods.

Next, define a function named make_rapyd_request that will help you call various Rapyd services:

def make_rapyd_request(method, path, body=None):
    salt = os.urandom(12).hex()
    timestamp = str(int(time.time()))
    signature = generate_signature(method, path, salt, timestamp, body)

    headers = {
        "access_key": access_key,
        "salt": salt,
        "timestamp": timestamp,
        "signature": signature,
        "Content-Type": "application/json"
    }

    response = requests.request(method, base_url + path, headers=headers, json=body)
    return response.json()

This code can be broken down into the following components:

It first creates a 12-byte random value (salt) to ensure uniqueness.
It then generates a timestamp to prevent replay attacks.
generate_signature() combines the HTTP method, path, salt, timestamp, and body to create a secure signature for authentication.
The code sets up the request headers, including authentication and content type.
It executes the HTTP request using the HTTP method and endpoint.
Finally, the code parses the server's response into JSON.

That's all you need to do to make a request to Rapyd endpoints.

Create an Rapyd API App

Once the Rapyd utility script is ready, it's time to implement the main functionalities of a creator economy payment system.

To start, you need to create main.py inside your project folder. Your folder structure should look like this:

creator_economy_rapyd_implementation/
│
├── main.py
├── rapyd_utils.py
└── .env

Import the necessary Python libraries as well as the FastAPI library for creating different payment facility endpoints:

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List
from rapyd_utils import make_rapyd_request

app = FastAPI()

Then, write the different data models that define and validate the expected JSON input for the endpoints:

# ---------- MODELS ----------
class Collaborator(BaseModel):
    name: str
    wallet_id: str
    share: float

class RoyaltyRequest(BaseModel):
    creator_wallet_id: str
    total_revenue: float
    collaborators: List[Collaborator]

class AffiliateRequest(BaseModel):
    affiliate_wallet_id: str
    commission_amount: float
    sender_wallet_id: str

class SubscriptionRequest(BaseModel):
    customer_email: str
    amount: float
    interval: str = "monthly"

Four different data models are defined: Collaborator defines an individual involved in royalty revenue sharing, and the remaining three data models define and validate the payment facilities in the creator economy app.

Royalty Payments

Royalty payments are often recurring and variable, and they need to be distributed across multiple parties. To handle this efficiently, you need to build a system that supports accurate and timely royalty disbursements.

In this section, you'll learn how to implement the first endpoint of the application for royalty payments. This is the foundation for handling complex, multiparty creator compensation.

Add the following endpoint to your FastAPI application inside the main.py file. This endpoint takes a list of collaborators and their revenue share, calculates each payout, and initiates the transfer to each collaborator:

@app.post("/royalty-payments")
def distribute_royalties(data: RoyaltyRequest):
    results = []
    for collab in data.collaborators:
        payout_amount = round(data.total_revenue * collab.share, 2)
        body = {
            "beneficiary": {"ewallet": collab.wallet_id},
            "amount": payout_amount,
            "currency": "USD",
            "sender": {"ewallet": data.creator_wallet_id},
            "metadata": {"type": "royalty"}
        }
        res = make_rapyd_request("POST", "/v1/account/transfer", body)
        results.append({
            "name": collab.name,
            "amount": payout_amount,
            "status": res.get("status", "FAILED")
        })
    return {"payouts": results}

This code uses the following variables:

data.collaborators calculates how much each collaborator should receive.
round(..., 2) rounds off the obtained value up to two decimal points.
beneficiary represents who gets the money.
sender is the creator paying the beneficiary.
metadata is an optional tag to label this as a royalty payout.
make_rapyd_request calls the Rapyd API to perform the transfer and returns a list of each collaborator, their payout, and the API status.

This endpoint is designed to split the revenue among multiple collaborators based on predefined share percentages. Once the request is received, including the creator's wallet ID, total revenue amount, and a list of collaborators, it calculates the payout amount by multiplying the total revenue by their share. The revenue is then rounded off to two decimal places for currency precision, and a JSON body is prepared that includes the sender and receiver wallet IDs, amount, currency, and metadata, indicating this is a "royalty" type of transfer. Finally, it makes a POST request to the Rapyd /v1/account/transfer endpoint for each collaborator using the make_rapyd_request function.

Affiliate Payouts

Now, let's implement an endpoint that pays a single affiliate based on the provided data:

@app.post("/affiliate-payout")
def process_affiliate_payout(data: AffiliateRequest):
    body = {
        "beneficiary": {"ewallet": data.affiliate_wallet_id},
        "amount": data.commission_amount,
        "currency": "USD",
        "sender": {"ewallet": data.sender_wallet_id},
        "metadata": {"type": "affiliate_commission"}
    }
    res = make_rapyd_request("POST", "/v1/account/transfer", body)
    return res

The body{...} variable is almost identical to the one in the /royalty-payments endpoint, but with different metadata. make_rapyd_request() performs and returns the result of the payout.

This endpoint accepts a JSON payload containing the affiliate's wallet ID, commission amount, and sender's wallet ID. It then constructs a body similar to the previous endpoint, defining the beneficiary, sender, currency, and amount, and tags the metadata with affiliate_commission. Finally, it makes a POST request to Rapyd's /v1/account/transfer endpoint to transfer the commission from the sender's wallet to the affiliate's.

Managing Subscriptions

Finally, let's implement the last endpoint for managing subscriptions. This endpoint implements a hosted payment link via Rapyd's /v1/payment_links API:

@app.post("/create-subscription")
def create_subscription(data: SubscriptionRequest):
    body = {
        "amount": data.amount,
        "currency": "USD",
        "customer": {
            "email": data.customer_email
        },
        "interval": data.interval,
        "metadata": {
                "subscription_tier": "premium"
        }
    }
    res = make_rapyd_request("POST", "/v1/payment_links", body)
    return {
            "redirect_url": res.get("data", {}).get("redirect_url", None)
    }

The following variables are used:

interval, which defines recurring subscriptions
metadata, which can be used to track tiers (basic, premium, etc.)
make_rapyd_request, which returns a redirect URL that the frontend or customer can use to pay

This endpoint accepts the customer's email, the subscription amount, and the payment interval. Then, it builds a request body that includes the amount, currency, customer details, subscription interval, and optional metadata like the tier name ("premium"). Finally, the body is sent to Rapyd's /v1/payment_links endpoint, which generates a hosted link that customers can visit to complete the subscription setup.

Run the Application

Once you've written the code, all you have to do is run the FastAPI app using uvicorn to access different endpoints. To do so, open your terminal and run the following command:

uvicorn main:app --reload

This starts your FastAPI application, which can be accessed on http://localhost:8000/docs:

You can also use curl commands to call the following endpoints: /royalty-payments, /affiliate-payout, and /create-subscription.

/royalty-payments

This endpoint splits and distributes revenue among collaborators based on their share. To do this, you need to obtain a wallet ID (such as ewallet_creator_123) from Rapyd. Every payment in the application—whether a royalty payout, affiliate commission, or subscription—depends on Rapyd Wallets, also known as ewallets.

curl -X POST http://localhost:8000/royalty-payments \
-H "Content-Type: application/json" \
-d '{
  "creator_wallet_id": "ewallet_creator_123",
  "total_revenue": 1000,
  "collaborators": [
    {
      "name": "Alice",
      "wallet_id": "ewallet_alice_001",
      "share": 0.5
    },
    {
      "name": "Bob",
      "wallet_id": "ewallet_bob_002",
      "share": 0.3
    },
    {
      "name": "Charlie",
      "wallet_id": "ewallet_charlie_003",
      "share": 0.2
    }
  ]
}'

Your output will look like this:

{
  "payouts": [
    {
      "name": "Alice",
      "amount": 500.0,
      "status": "SUCCESS"
    },
    {
      "name": "Bob",
      "amount": 300.0,
      "status": "SUCCESS"
    },
    {
      "name": "Charlie",
      "amount": 200.0,
      "status": "SUCCESS"
    }
  ]
}

The endpoint splits $1,000 USD in revenue into 50 percent, 30 percent, and 20 percent shares for Alice, Bob, and Charlie, respectively. Then, it initiates Rapyd transfers for each. The response confirms the transfer status for each payout.

/affiliate-payout

This endpoint pays a commission to an affiliate:

curl -X POST http://localhost:8000/affiliate-payout \
-H "Content-Type: application/json" \
-d '{
  "affiliate_wallet_id": "ewallet_aff_007",
  "commission_amount": 120,
  "sender_wallet_id": "ewallet_creator_123"
}'

Your output will look something like this:

{
  "status": {
    "status": "SUCCESS",
    "message": "",
    "error_code": "",
    "response_code": "",
    "operation_id": "e4bc3f56-d40b-4cb4-a9e1-e5d18fc77b8e"
  },
  "data": {
    "id": "transfer_abc123xyz",
    "amount": 120,
    "currency": "USD",
    "status": "ACT",
    "beneficiary": {
      "ewallet": "ewallet_aff_007"
    }
  }
}

This endpoint transfers $120 USD from the creator's wallet to the affiliate's wallet. The operation_id can be stored for logging or future reconciliation.

/create-subscription

This endpoint creates a payment link for a customer to subscribe:

curl -X POST http://localhost:8000/create-subscription \
-H "Content-Type: application/json" \
-d '{
  "customer_email": "subscriber@example.com",
  "amount": 15.99,
  "interval": "monthly"
}'

Your output will look something like this:

{
  "redirect_url": "https://sandboxcheckout.rapyd.net?token=pl_8fc456a83e"
}

This creates a hosted payment link. Once you click the URL, you'll be taken to a Rapyd-hosted checkout page where you can securely complete the subscription process using your preferred payment method.

The API call allows customers to subscribe to a monthly plan priced at $15.99 USD. You can also use webhooks in Rapyd to monitor subscription lifecycle events like subscription.created, payment.completed, or subscription.cancelled.

At this point, you've created an application that can manage royalties, payouts, and subscriptions with Rapyd. Congratulations! You can find the full code for this tutorial on GitHub.

Conclusion

The financial side of content creation can be hard to manage, but the right tools can make it easier. Rapyd helps simplify payment operations so creators can spend less time on logistics and more time on creating.

Rapyd is more than just a payment provider; it's an all-in-one fintech infrastructure that helps you move money with ease. Whether you're managing complex royalty splits, scaling affiliate payouts, or automating recurring subscriptions, Rapyd's APIs will help you build powerful, secure, and flexible payment systems quickly.

Check out the Client Portal or play around with Rapyd's Sandbox—you'll quickly see how easy it is to streamline payments and simplify your workflow with Rapyd.

Mastering Compliance API Integrations: A Developer's Guide to AI-Powered KYC, AML, & Fraud Prevention

Drew Harris — Thu, 03 Jul 2025 12:42:31 +0000

The rapid evolution of AI is fundamentally reshaping regulatory compliance in payments. For us developers on the front lines, this transformation often manifests through the integration of sophisticated AI-powered APIs for critical functions like Know Your Customer (KYC), Anti-Money Laundering (AML), and real-time fraud prevention. This isn't just about automation; it's about embedding intelligent decision-making directly into your payment flows, making your systems smarter and more resilient.

This article, part of our series on AI in payments compliance (and building on our strategic overview), serves as your direct playbook for navigating the world of compliance API integrations.

The Golden Nugget: APIs as Your Compliance Backbone

Here's the core insight for us as developers: you don't need to become an AI expert or a compliance lawyer. Instead, your superpower lies in effectively integrating and orchestrating best-in-class, specialized compliance APIs. These services, often powered by advanced machine learning, handle the heavy lifting of data analysis, risk scoring, and pattern recognition, providing you with clear, actionable outputs you can consume directly in your code. This is where the magic happens – leveraging intelligence without building it from scratch.

1. API Selection Criteria: Choosing Your Compliance Partner Wisely

Before writing a single line of code, let's talk strategy. What makes a compliance API robust and reliable for a production payment system?

Global Coverage & Data Sources: Does it cover the jurisdictions where your users operate? Leading providers like ComplyCube, Uniify, Jumio, and Onfido offer extensive global identity verification and screening. Don't get caught out by regional limitations.
Real-time Processing & Latency: For payment transactions, every millisecond counts. Prioritize APIs designed for near-instant responses to minimize friction in user journeys and prevent real-time fraud. Think about your SLAs.
Data Enrichment Capabilities: Beyond simple validation, can the API enrich data? For example, can it provide a risk score based on an IP address, email, or device fingerprint, as offered by solutions like SEON or IPQualityScore? This extra context is invaluable.
Documentation Quality (Critically Important!): This is paramount. Comprehensive, clear, and interactive API documentation (e.g., Swagger UI/OpenAPI spec) with robust code examples in multiple languages drastically reduces integration time and errors. If the docs are poor, run!
Sandbox Environments & Support: A robust, feature-rich sandbox for development and testing, coupled with responsive developer support channels, are non-negotiable. Test, test, test.
Pricing Models: Understand if it's per-API call, tiered, or based on usage volume. Model costs against your projected transaction volumes.

2. Integration Patterns: Weaving Compliance into Your Workflow

Compliance checks need to happen at various, often distinct, points in the payment lifecycle. Understanding the right integration pattern for each is key.

Onboarding (KYC/KYB): The Asynchronous Dance

Integrate identity and business verification APIs during user or merchant signup. This is often an asynchronous process, where initial checks trigger background processes, allowing the user to continue while comprehensive checks complete.

Pattern: Request-Response with Asynchronous Callbacks (Webhooks).

# Pseudocode for KYC Onboarding Flow
def initiate_kyc(user_data):
    transaction_id = generate_unique_id()
    # Send request to compliance API with your webhook endpoint
    compliance_api.send_kyc_request(user_data, {
        'callback_url': '[https://your-domain.com/webhooks/kyc-status](https://your-domain.com/webhooks/kyc-status)',
        'metadata': {'transactionId': transaction_id}
    })
    save_pending_kyc_status(transaction_id, user_data)
    return {'status': 'PENDING_REVIEW', 'transactionId': transaction_id}

# Your webhook endpoint: Called by compliance API when status changes
@app.route('/webhooks/kyc-status', methods=['POST'])
def handle_kyc_webhook():
    data = request.json
    transaction_id = data.get('transactionId')
    status = data.get('status')
    details = data.get('details')
    # IMPORTANT: Validate webhook signature here!
    if not validate_webhook_signature(request.body, request.headers.get('X-Signature'), YOUR_WEBHOOK_SECRET):
        return 'Invalid signature', 403

    update_kyc_status(transaction_id, status, details)
    if status == 'APPROVED':
        activate_user_account(transaction_id)
    return '', 200 # Acknowledge receipt

An initial API call validates basic info, and a webhook might notify your system when comprehensive background checks (e.g., identity verification, sanctions screening) are complete.

Transaction Processing (AML/Fraud): The Real-Time Gatekeeper

Implement real-time calls to fraud prevention and AML APIs before a transaction is authorized. These systems analyze transactional data (amount, location, payment method, card BIN) and behavioral signals to generate a risk score.

Pattern: Synchronous Request-Response.

# Pseudocode for Real-time Transaction Fraud Check
async def process_payment(payment_details):
    try:
        fraud_check_result = await fraud_api.check_transaction(payment_details)
        if fraud_check_result.get('riskScore', 0) > THRESHOLD_REJECT:
            return {'status': 'REJECTED', 'reason': 'High fraud risk'}
        if fraud_check_result.get('riskScore', 0) > THRESHOLD_REVIEW:
            # Log for manual review, but allow transaction to proceed conditionally
            log_for_manual_review(payment_details, fraud_check_result)

        # Proceed with payment authorization
        return await payment_processor.authorize(payment_details)
    except Exception as e:
        # Implement graceful fallback or block transaction
        handle_fraud_api_error(e, payment_details)
        return {'status': 'ERROR', 'message': 'Fraud check failed'}

The API call should be fast enough not to introduce significant latency into the checkout flow (aim for single-digit milliseconds). Google's reCAPTCHA Fraud Prevention and SEON are excellent examples of solutions for real-time risk assessments.

Post-Transaction Monitoring: The Background Watcher

For ongoing AML and suspicious activity detection, integrate APIs that monitor transaction streams or user behavior over time. This is less about blocking and more about continuous vigilance.
- Pattern: Event-Driven Architecture with Webhooks. Your system sends transaction data (or batches of data) to a monitoring service, and that service uses webhooks to notify your application of any suspicious activity or alerts that require review.

3. Data Flow & Security: Protecting Sensitive Information is Non-Negotiable

You're dealing with highly sensitive financial and personal data. Security is not an afterthought; it's fundamental to every line of code you write.

Secure Transmission: Always, always, always use HTTPS/TLS for all API communications. No excuses.
Authentication & Authorization: Implement robust API key management, OAuth 2.0, or OpenID Connect. Store API keys securely (e.g., in environment variables, secret management services like AWS Secrets Manager or HashiCorp Vault), never hardcode them. Rotate keys regularly.
Data Minimization: Only send the necessary data to the API. Avoid transmitting sensitive information that isn't required for the specific compliance check. The less data you send, the less surface area for compromise.
Encryption & Tokenization: Where possible, tokenize or encrypt sensitive data (e.g., payment card numbers, personally identifiable information (PII)) before sending it to third-party APIs. This limits exposure even if a breach occurs. Think of the Payment Card Industry Data Security Standard (PCI DSS) implications here.
Input/Output Schemas: Understand the exact data formats (JSON, XML) and required fields for API requests and responses. Implement strong input validation on all data sent to and received from APIs to prevent injection attacks or unexpected behavior.

4. Error Handling & Fallbacks: Building Resilient Systems

External APIs can fail, encounter rate limits, or return unexpected errors. Your integration must be resilient, just like any mission-critical system.

HTTP Status Codes: Know your common API error codes (e.g., 400 Bad Request, 401 Unauthorized, 403 Forbidden, 429 Too Many Requests, 500 Internal Server Error, 503 Service Unavailable). Each has a specific meaning and demands a specific response from your code.

Rate Limit Management: Implement client-side rate limiting or use strategies like exponential backoff with jitter for retries when encountering 429 Too Many Requests. The Retry-After HTTP header is your friend here, indicating when you can safely retry.

import time
import random
import requests # Assuming 'requests' library for HTTP calls

def make_api_call_with_retry(api_client_method, max_retries=5):
    for i in range(max_retries):
        try:
            response = api_client_method()
            response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)
            return response
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 429: # Too Many Requests
                wait_time = (2 ** i) + random.uniform(0, 1) # Exponential backoff + jitter
                print(f"Rate limit hit. Retrying in {wait_time:.2f} seconds...")
                time.sleep(wait_time)
            else:
                raise # Re-raise other HTTP errors
        except requests.exceptions.ConnectionError:
            # Handle network issues more gracefully
            print("Connection error. Retrying in 1 second...")
            time.sleep(1)
    raise Exception("Max retries exceeded for API call.")

Circuit Breakers & Timeouts: Implement circuit breakers to prevent cascading failures if an API becomes unresponsive. Set appropriate, aggressive timeouts for API calls to avoid hanging requests. Libraries like Hystrix (Java) or Polly (.NET) provide patterns for this.
Fallback Mechanisms: For non-critical checks, consider graceful degradation. What happens if a fraud API is down? Can you temporarily switch to a more conservative internal rule set, or queue checks for later processing when the service recovers? Always have a plan B.

5. Webhooks & Event-Driven Architecture: Powering Asynchronous Processing

For ongoing monitoring and long-running processes (like comprehensive AML screening or adverse media checks), webhooks are indispensable for an event-driven architecture.

Listen for Events: Your application exposes a secure endpoint that the compliance API can call when an event occurs (e.g., a screening result is ready, a fraud alert is triggered).

Validate Webhook Signatures: Always, always verify the signature of incoming webhooks. This ensures the webhook genuinely originates from the compliance provider and hasn't been tampered with by a malicious actor.

import hmac
import hashlib

def validate_webhook_signature(request_body, signature_header, secret):
    # Example for HMAC-SHA256 signature validation
    # The specific header name and signature generation method vary by API provider.
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        request_body,
        hashlib.sha256
    ).hexdigest()
    # Use a constant-time comparison to prevent timing attacks
    return hmac.compare_digest(expected_signature, signature_header)

Idempotency: Design your webhook handlers to be idempotent. This means processing the same event multiple times won't cause adverse effects, as webhooks can sometimes be delivered more than once due to network issues or retries. Store a unique event ID and check if it's already processed before taking action.

6. Testing Methodologies: Ensuring Compliance and Performance Under Pressure

Thorough testing is paramount for compliance APIs, given the financial and regulatory stakes.

Sandbox Environments: Conduct initial development and integration testing exclusively in the API provider's sandbox. This is your safe playpen.
Unit & Integration Tests: Write comprehensive unit tests for your API integration logic, verifying request formatting, response parsing, and error handling. Then, integration tests against the sandbox to confirm end-to-end flow.
Performance & Load Testing: Simulate realistic high transaction volumes. Can your integration handle the anticipated load without bottlenecks? Does the compliance API meet your latency requirements under stress?
Edge Case Testing: This is where you find the tricky bugs. Test scenarios like malformed data, very high/low transaction amounts, unusual geo-locations, and identity mismatches to ensure the API responds as expected and your code handles them gracefully.
Security Audits: Regularly conduct security audits and penetration tests on your integration points. This includes checking for API key exposure, data leakage, and potential for abuse.

Conclusion

Integrating AI-powered compliance APIs is rapidly becoming a fundamental skill set for modern payment developers. By meticulously selecting the right APIs, designing robust integration patterns, prioritizing data security, implementing resilient error handling, leveraging event-driven architectures, and rigorously testing your solutions, you can significantly enhance your payment gateway's security posture and regulatory adherence.

This practical, API-first approach to AI implementation empowers you to build highly intelligent, adaptive, and compliant payment systems. It allows you to future-proof your solutions, moving beyond basic automation to truly intelligent, adaptive compliance that supports innovation rather than hindering it.

What compliance APIs have you found most effective in your projects? What integration challenges have you overcome? Share your experiences and insights in the comments below!

This article is part of a series stemming from our comprehensive analysis: https://community.rapyd.net/t/ai-for-regulatory-compliance-in-payments/59638 Explore the other articles in the series to dive deeper into Explainable AI (XAI) and MLOps for compliance!