DEV Community: mcduffin

Enhancing Payment Fraud Detection with Rapyd Protect

mcduffin — Thu, 09 Apr 2026 14:00:00 +0000

By: Manish Hatwalne

Rapyd provides a platform for embedding payment services into your applications. To help you combat payment fraud, Rapyd Protect is included for Rapyd accounts (verify plan eligibility) that offers protection for transactions involving credit cards, bank transfers, and e-wallets, while maintaining a seamless checkout experience for legitimate customers.

Powered by machine learning (ML) and advanced risk models, Rapyd Protect works in real time to identify suspicious patterns, from unusual spending behavior to mismatched user information. It also allows you to maintain full control with customizable rules that can automatically block high-risk transactions or flag them for manual review.

In this article, you'll learn how you can enhance payment fraud detection in your applications with Rapyd Protect.

Rapyd Protect

Rapyd Protect helps you minimize chargebacks and protect your revenue. It provides protection via two approaches:

Machine learning
Fraud rules

How Rapyd Protect Uses Machine Learning to Prevent Fraudulent Transactions

Rapyd Protect uses ML models that have been trained on Rapyd's historical transaction data to recognize patterns that indicate fraud. When a transaction comes through, the models analyze various signals, like the customer's location, device fingerprint, transaction amount, and payment method, to assign a specific risk score.

For example, if someone attempts multiple small test transactions from different IP addresses using the same card within a short timeframe (a common card-testing pattern), the velocity engine typically tracks this behavior while the ML model evaluates the overall risk profile. Similarly, if a card’s Bank Identification Number (BIN) belongs to a U.S. bank but is used for a high-value transaction from an IP in another country, Rapyd Protect may flag it as suspicious.

The ML models are continuously retrained with new data to detect evolving fraud tactics, like shifts in geographic attack patterns or new account takeover techniques.

Fraud Rules

Rapyd Protect also includes a rules engine for creating custom fraud policies based on parameters like IP addresses, card types, amount, geographic locations, and 3D Secure requirements. The platform maintains reference lists of known fraudulent entities, suspicious IP addresses, restricted countries, and high-risk BIN ranges. Transactions can be blocked or routed to manual review queues based on configurable criteria such as transaction amount or origin country.

The system provides interfaces for reviewing flagged transactions, approving or declining payments, viewing triggered rules, and accessing blocked transaction logs. These rules work alongside ML to enhance fraud detection and adapt to evolving threats.

Implementing Custom Fraud Rules in Rapyd Protect

While ML used by Rapyd Protect prevents common fraudulent transactions, sometimes you need custom rules to address your specific business requirements. For example, you might want to block customers making more than a specified number of card transactions within three days, block card transactions from regions where you don't operate, or block high-value card transactions over 2,500 EUR.

Let's look at how you can create this amount-based blocking rule in Rapyd Protect.

Rules Engine

The Rapyd Protect Rules Engine lets you create custom fraud prevention rules based on various transaction attributes like IP addresses, card types, countries, transaction amounts, BIN ranges, and 3D Secure requirements. These rules provide an additional layer of protection tailored to your specific business needs. Each rule consists of two components: the triggering conditions (what to look for) and the action (allow, block, or review) to take when those conditions are met.

Rules fall into three categories with a specific hierarchy:

Allow rules takes highest priority and permits transactions matching their criteria, overriding any other rules.
Block rules automatically rejects transactions that meet their conditions, unless an "Allow" rule applies.
Review rules flags transactions for manual evaluation and routes them to an "Under Review" queue where you must approve or decline them within seven days. These rules only trigger if the transaction doesn't match any "Allow" or "Block" rules and they are only available for bank payments, not for card payments.

The following diagram shows how rule processing takes place in Rapyd Protect:

Creating an Amount-Based Blocking Rule

Now that you understand how Rapyd Protect rule processing works, let's create a blocking rule for high-value transactions. We'll build a rule that automatically blocks any transaction exceeding 2,500 EUR.

Log in to your Rapyd account and select Protect from the left-hand navigation menu. The Rules page displays all your existing rules and lets you create new ones:

Click the Add rule button in the Block section at the bottom of the page. In the dialog that appears, define your blocking condition: "Amount EUR Greater than 2,500". Then, add a meaningful description for your rule.

Rapyd Protect supports complex rule logic, so you can combine multiple conditions using and or or clauses if needed.

After configuring your conditions, click the Create rule button (this becomes active once you've added at least one condition). A confirmation dialog will appear asking you to enable the rule:

Click Enable to activate your rule. If you skip this step, the rule will be created but remain inactive (aka disabled). It won't affect any transactions until you manually enable it later.

You can create additional blocking rules based on your specific business needs. For instance, if you only accept US-issued cards, create a rule with the condition Card country Not Equal to US to block all international card transactions.

Testing the Blocking Rule

After creating your amount-based blocking rule, you can test it using Rapyd's Virtual Terminal. Navigate to the Getting started page and select the Collect payments tab. This page provides multiple options, including payment links, card payment simulation, and branding customization.

Rapyd provides a sandbox mode for development, so all transactions use test data, no real cards or money are involved. Click the Collect virtually button under the Virtual terminal:

With the Virtual Terminal, you can simulate a card payment by following these steps:

Enter payment details: Select the customer's country, payment method (card type: Visa or Mastercard), amount (enter a value above your rule threshold, such as: 2501 EUR), currency, then click Next.

Enter card information: Provide the cardholder name, card number (use test card 4111 1111 1111 1111), a future expiration month and year, and any 3-digit CVV number (any digits work in Sandbox), then click Next.

Skip additional details: Click Create payment to bypass the optional Additional details dialog.

View the blocking result: Since the transaction amount exceeds EUR 2,500, the Rapyd Protect rules engine marks the payment as blocked or routes it to the Under Review queue; see your dashboard for the block reason. You'll see a Payment blocked dialog with the message: "Your transaction has been blocked by Rapyd Protect. It can be viewed under the "Blocked" tab."

Click Close to dismiss this dialog. Your blocking rule has successfully triggered and prevented the high-value transaction.

To verify the rule works correctly, test a few more transactions. Use amounts at or below 2,500 EUR (which should process successfully) and amounts above 2,500 EUR (which should be blocked). This confirms your rule is enforcing the threshold properly.

Note: Your application can integrate the payment collection using Rapyd APIs as well.

Monitoring Blocked and Successful Transactions

After testing your rule, you can review the results in the Rapyd dashboard. Navigate to Collect in the left-hand navigation, then under Review & Protect, select Blocked. This page displays all transactions that were rejected by your blocking rules. You can filter the list by date range and other criteria.

Click on any transaction row to view its details in the right-hand panel. The detail view shows the transaction amount, currency, timestamp, customer information, and other relevant data:

At the bottom of the detail panel, you'll see a Triggered rules section. Click the View link to see which rule(s) caused the transaction to be blocked. A dialog will display the specific blocking rule that triggered it, which is your high-value transaction rule:

To verify that legitimate transactions are processing correctly, navigate to the Payments page under Collect. This page shows all successfully processed transactions. As shown in the following screenshot, transactions at or below 2,500 EUR complete successfully and are not blocked by your rule:

Note: These transactions may take up to 15 minutes to appear in this dashboard.

Advanced Features of Rapyd Protect

Beyond basic blocking rules, Rapyd Protect offers several advanced features for more sophisticated fraud prevention strategies.

3D Secure rules allow you to conditionally trigger additional authentication for card transactions based on specific criteria. For example, requiring 3D Secure verification for all transactions above a certain amount or from particular countries.
Review rules work differently from blocking rules by placing transactions in a manual review queue rather than automatically rejecting them. This is available for bank payments (inbound or outbound) where you want human oversight before approving high-risk transactions. Reviewers have seven days to approve or decline each flagged transaction from the Under Review dashboard.
Rule Library provides a collection of pre-configured fraud prevention rules that you can activate and customize for your business. Instead of building common rules from scratch, you can select templates from the library, adjust their parameters to match your requirements, and add them to your active rule set. This speeds up the implementation of standard fraud prevention patterns while still allowing full customization.
Lists Rapyd Protect offers several lists that your rules can reference for more granular control.
- The Allowed Cards and Blocked Cards lists use card fingerprints to whitelist or blacklist specific cards.
- For bank transactions, you can manage Approved Bank Accounts (always allow) and Blocked Bank Accounts (always reject) based on customer (or beneficiary) account details.
- Geographic controls are available through Country Codes to Block (for card-issuing countries) and Blocked Beneficiary Bank Country (for bank transfer destinations). These lists provide a flexible way to maintain exception-based policies without creating individual rules for each case.
Programmatic access Rapyd Protect provides API endpoints and Webhooks that allow you to integrate fraud prevention directly into your application. The APIs allow you to handle payments, while webhooks send real-time alerts when your fraud rules trigger, allowing your system to respond automatically to fraud events.

For detailed integration guides and API documentation, visit the Rapyd Developer Portal.

Conclusion

In this article, you learned how Rapyd Protect combines ML with customizable fraud prevention rules to safeguard your payment operations. You not only learned how to create those custom rules, but also test those rules using the Virtual Terminal, and then monitor their performance through the dashboard.

Rapyd Protect is an important component of Rapyd's comprehensive payment platform. Whether you're processing cards, bank transfers, or e-wallets, Rapyd provides the tools to accept payments globally while maintaining security and compliance.

If you're looking to implement fraud prevention in your application, sign up for Rapyd's trial account to access the Sandbox environment, explore the full Rapyd API capabilities, and start building secure payment flows today.

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.

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.

🗞️ Rapyd Developer Newsletter: April 2025 💥 One-Click Checkout, Global Payouts, and What’s New for Devs

mcduffin — Sat, 19 Apr 2025 19:11:43 +0000

💾 Essential Updates
Be code-ready – our updated API and Product changelogs are your go-to for changes impacting your work.

🤝 Partner Models for Payments: How Rapyd Powers Partner Payment Solutions
Discover how to build flexible payment systems with Rapyd’s partner model, ideal for platforms scaling globally.

🔗 Payment Links: A One-Click Solution
Simplify checkout with one-click payment links. Fast to implement, easy for your customers.

🛡️ Navigating Regulatory Compliance in API Development
Ensure your APIs are compliant with GDPR, PSD2, and global regulations. Get the tools and tips for secure, audit-ready development.

📱 Rapyd Dashboard App
View your settlements and payments from your iOS device. The Rapyd Dashboard App is available to CNP merchants in Europe, UK, and Israel.

🌍 SWIFT Payout - Now Available in Singapore
Send cross-border payouts with ease. Learn how SWIFT through Rapyd supports your global business growth.

See you next month,
The Rapyd Dev Community Team

P.S. Do you have ideas to improve this newsletter or want to contribute an article or join a panel? Let us know by replying.

POS Terminals: Fintech Reinvented

mcduffin — Wed, 16 Apr 2025 22:52:37 +0000

Point-Of-Sale (POS) Terminals are an essential way to make payments in the real world. Countless brick-and mortar businesses use POS terminals to capture card payments and facilitate other payment methods such as cash payments via a voucher or QR code. The latest terminals also support contactless card payments, and contactless payments using an ewallet on a mobile device.

POS Terminals and Fintech

Two main elements are needed for a successful POS terminal experience. The physical terminal is needed, and the connection to a payments processor. Fintech companies are offering POS APIs and connections to physical POS terminals to help expand payments to businesses everywhere.

Using a POS that can accept a wider variety of cards and payment methods can help customers to make payments their way, and offer a wider range of choices in countries where traditional banking services are less available.

Fintech companies also allow the merchant greater flexibility, transparency, and control over their POS experience when running their business.

Why POS Terminals Are Important

POS terminals are important because they provide vital infrastructure to help facilitate digital payments. A business that runs an online store-front can easily collect payment details, or use a hosted checkout experience to manage online payments. But businesses that have a physical location have more limited options for collecting payment.

POS terminals are the go-to solution for merchants that run businesses at physical locations. But the experience is heavily influenced by how easily they can collect payments, or issue refunds when needed.

POS Solutions

Fintech companies such as Rapyd transform the POS experience because a larger financial network can be connected to the devices. Rapyd offers a wide variety of payment methods that are accepted in many countries.

In addition, you can manage your POS terminals using the Rapyd App. You can gain access to a wider variety of features to manage your POS terminals from your mobile device. See the documentation for the Rapyd App here. Merchants can easily view a list of their POS transactions from their mobile device. Pre-authorized sales can also be created.

Partner Models for Payments: How Rapyd Powers Partner Payment Solutions

mcduffin — Tue, 08 Apr 2025 17:00:00 +0000

By: Gourav Bais

SaaS platforms and online marketplaces have revolutionized the way businesses operate. While SaaS platforms provide cloud-based solutions, marketplaces connect buyers and sellers within a shared ecosystem. Both models rely on a strong partner ecosystem, where third-party businesses, service providers, and merchants collaborate to deliver value to their customers. This ecosystem supports tasks like onboarding, revenue models, and payment processes.

However, managing payments across these networks can be challenging due to fragmented systems, regulatory issues, and cross-border complexities. To address these challenges, businesses need a reliable payment infrastructure that supports global operations and ensures smooth transactions. It's possible to establish this infrastructure manually following a partner model or to opt for a reliable payment solution like Rapyd. Rapyd offers a flexible API and partner-friendly infrastructure, enabling you to create tailored payment experiences, onboard merchants, and automate payouts, all while avoiding the complexities of cross-border payments.

This article introduces some different partner payment models and explains the main components of an effective partner payment flow. You'll then learn how to implement partner-based payment with Rapyd and Python.

Partner Models for Payments

When businesses expand to support multiple merchants, service providers, or third-party vendors, they should have their payment system designed in a way that will ensure seamless transactions across the ecosystem. Partner payment models help businesses manage these complex financial interactions since they often support handling customer payments, distributing payments to merchants, and splitting revenue with partners.

Businesses using SaaS or marketplaces often integrate partner payment models to manage transactions and compliance. These models can greatly simplify the effort of handling challenges like regulatory compliance, fraud prevention, and operational complexity. Two common models are independent sales organization (ISO) and payment facilitator (PayFac).

An ISO is a third-party company that resells credit card processing from established providers but doesn't process payments directly.
The PayFac model, also known as payment aggregation, involves a third party acting as a merchant of record. In other words, it processes transactions for sub-merchants under a single master account. This model includes payment processing, risk management, and fraud prevention.

Key Components of a Partner Payment Flow

If you want to implement and use a partner payment flow, you need a strong understanding of its key components. An effective partner payment system involves:

Partner onboarding
Revenue sharing and tracking
Compliance and taxation considerations

Partner Onboarding

Partner onboarding is the first step for integrating merchants, vendors, or service providers into a payment system. The process begins with verifying their identity, then setting up their accounts and enabling transactions. A smooth onboarding process can help minimize drop-off rates and ensure that partners can quickly start using the platform. For example, the Rapyd Partner Portal streamlines this process by offering automated registration and verification, ensuring compliance with Know Your Customer (KYC) and Anti-Money Laundering (AML) requirements, and providing tools for partners to track transactions, monitor payouts, and manage accounts from a single interface.

Revenue Sharing and Tracking

Once onboarding is complete, you'll need to share revenue and track payments. This is particularly important, as you'll probably be owed an agreed percentage of each partner transaction. A payment platform should support automated revenue splits based on pre-agreed models, real-time tracking of earnings, transaction history, payout schedules, and commission breakdowns. It should also offer flexible payout options, such as instant, scheduled, or milestone-based payments, and support multicurrency payments to reduce conversion fees. A few common revenue-sharing models include equal split, royalty-based, percentage of gross revenue, and percentage of net revenue.

Compliance and Taxation Considerations

Handling payments at scale requires compliance with financial regulations and tax obligations across different regions. Compliance is nonnegotiable in partner payments and ensures that businesses and their partners operate legally and avoid financial penalties. This involves verifying partner identities, monitoring transactions for suspicious activity, and, depending on the jurisdiction, withholding taxes and reporting earnings to tax authorities. Additionally, payment flows must adhere to PCI DSS standards to protect sensitive financial data and comply with privacy regulations like GDPR and CCPA.

Implementing a Partner-Based Payment System with Rapyd and Python

As you can see, manually managing partner payments can become quite a complex and time-consuming task. Rapyd's payment solution can simplify partner payments for SaaS platforms, marketplaces, and fintech businesses. It supports multiple currencies and handles issues like banking restrictions, currency conversion, and varying country regulations. It also provides built-in compliance tools for automated KYC verification, fraud detection, and adherence to tax compliance. For developers, Rapyd provides easy integration with RESTful APIs and SDKs in languages like Python, Node.js, and Java.

Let's look at how to use Rapyd to build a simple system where you can onboard merchants, add products, receive payments, and receive payouts, all powered by Rapyd's API. To fully integrate this system, businesses can sign up as a Rapyd partner to access additional capabilities for managing merchant transactions. In this tutorial, you'll see how to use the FastAPI framework in Python to create endpoints for each step: onboarding merchants, adding products, receiving payments, and receiving payouts.

Prerequisites

Before you start, you'll need a working Rapyd Client Portal account to set up a sandbox environment for testing payments. Once you're logged in, you can get your access key and secret key under the API credentials section in the Client Portal. You'll need these later.

You'll also need to have Python installed. Any version 3.8 or later will work for this tutorial.

Create a Python app

Before you begin, install the necessary Python dependencies with this command:

pip install fastapi uvicorn requests

Create a project folder to store all your development scripts. Inside this folder, create a new Python file called merchant_rapyd_app.py.

In merchant_rapyd_app.py, first import the necessary Python dependencies as follows:

from fastapi import FastAPI, HTTPException
import requests
import uuid
import hashlib
import hmac
import time
import json
import base64

Once the imports are ready, initialize the FastAPI app and define some dummy databases for merchants, products, payments, and payouts:

app = FastAPI()

# Dummy database
merchants = {}
products = {}
payments = {}
payouts = {}

To connect to the Rapyd API, define your credentials as follows, making sure to replace the placeholders with your actual access key and secret key:

RAPYD_ACCESS_KEY = "YOUR_ACCESS_KEY"
RAPYD_SECRET_KEY = "YOUR_SECRET_KEY"
RAPYD_BASE_URL = "https://sandboxapi.rapyd.net"

Then, define a function named generate_rapyd_headers that will generate the necessary headers for making the authenticated requests to the Rapyd payment platform:

# Utility function to generate Rapyd headers
def generate_rapyd_headers(http_method, path, body):
    timestamp = str(int(time.time()))
    salt = str(uuid.uuid4())
    body_string = json.dumps(body) if body else ""

    to_sign = http_method + path + salt + timestamp + RAPYD_ACCESS_KEY + RAPYD_SECRET_KEY + body_string
    signature = base64.b64encode(hmac.new(RAPYD_SECRET_KEY.encode(), to_sign.encode(), hashlib.sha256).digest()).decode()

    return {
        "Content-Type": "application/json",
        "access_key": RAPYD_ACCESS_KEY,
        "salt": salt,
        "timestamp": timestamp,
        "signature": signature
    }

The above code helps you interact securely with Rapyd's API, where each request must be authenticated using a signature-based mechanism. Here:

timestamp saves the current UNIX time (in seconds). Rapyd requires a valid timestamp to ensure that the request is fresh and prevent replay attacks.
salt is a randomly generated unique identifier (UUID). This makes sure that each request is unique and adds an extra layer of security.
body_string represents the request payload, which is converted to a JSON string. If there is no request body, it will remain an empty string.
to_sign is a concatenation of the HTTP method, request path, salt, timestamp, access key, secret key, and body content. This string is what you sign to generate the authentication signature.
The hmac.new() function creates a cryptographic hash-based message authentication code (HMAC) using the SHA-256 hashing algorithm. It signs the to_sign string with the RAPYD_SECRET_KEY, ensuring that people with a secret key can generate valid signatures.
The HMAC result is always a binary output, so you need base64.b64encode to encode it to Base64 and make it a readable string, which is suitable for transmissions in HTTP headers.

Create an Endpoint for Merchant Onboarding

The first stage in the partner payment solution is to onboard a merchant. Each merchant should have a unique ID that identifies them.

Create an endpoint for merchant onboarding:

@app.post("/merchant/register")
def register_merchant(name: str):
    merchant_id = str(uuid.uuid4())
    merchants[merchant_id] = {"name": name, "balance": 0.0}
    return {"merchant_id": merchant_id, "message": "Merchant registered successfully"}

The merchant IDs are generated using the uuid module. These unique IDs ensure there are no conflicts or duplications when processing transactions and are essential for managing merchant-specific payments and payouts.

This is just a basic example; onboarding a merchant is a far more detailed process and can also involve KYC steps. But don't worry—Rapyd has a product called Rapyd Verify to help with that as well.

Create an Endpoint for Adding a Product

Once the merchant is onboarded, it can list products for customers to buy. To enable this, create an endpoint where merchants can add products:

@app.post("/merchant/{merchant_id}/add_product")
def add_product(merchant_id: str, name: str, price: float):
    if merchant_id not in merchants:
        raise HTTPException(status_code=404, detail="Merchant not found")

    product_id = str(uuid.uuid4())
    products[product_id] = {"merchant_id": merchant_id, "name": name, "price": price}
    return {"product_id": product_id, "message": "Product added successfully"}

As you can see, the product is linked to the merchant. This ensures that when multiple customers make purchases simultaneously, each product is correctly associated with the right merchant, avoiding payment confusion. This example is only a simplified version; in real-world applications, products will likely include additional details such as descriptions, categories, stock levels, and images to provide a rich customer experience.

Create an Endpoint to Receive Payments Using Rapyd

Once a customer purchases something, the next step is to forward them to an endpoint where they can complete the payment for the product they're buying from the merchant. To process the payment, you need to integrate with the Rapyd API, which will handle the transaction. This example uses a card payment method with the currency set to USD. Before proceeding, you need to enable the Card Payment API for payments and payouts:

@app.post("/pay/{product_id}")
def collect_payment(
    product_id: str,
    currency: str,
    payment_method: str,
    platform_fee_percentage: float = 10.0  # Default fee is 10%
):
    if product_id not in products:
        raise HTTPException(status_code=404, detail="Product not found")

    product = products[product_id]
    merchant_id = product["merchant_id"]
    amount = product["price"]

    # Validate platform fee percentage (should be between 0% and 100%)
    if not (0 <= platform_fee_percentage <= 100):
        raise HTTPException(status_code=400, detail="Invalid platform fee percentage")

    # Convert percentage to decimal
    platform_fee_decimal = platform_fee_percentage / 100

    # Calculate platform fee and merchant payout
    platform_fee = amount * platform_fee_decimal
    merchant_payout = amount - platform_fee  # Amount merchant receives

    # Prepare payment data for Rapyd API
    payment_data = {
        "amount": amount,
        "currency": currency,
        "payment_method": payment_method,
        "description": f"Payment for {product['name']}"
    }

    headers = generate_rapyd_headers("post", "/v1/payments", payment_data)
    response = requests.post(f"{RAPYD_BASE_URL}/v1/payments", json=payment_data, headers=headers)

    if response.status_code != 200:
        raise HTTPException(status_code=500, detail="Failed to create payment")

    payment_response = response.json()
    payment_id = payment_response.get("id")

    # Store payment record
    payments[payment_id] = {
        "merchant_id": merchant_id,
        "amount": amount,
        "platform_fee": platform_fee,
        "merchant_payout": merchant_payout
    }

    # Update merchant balance
    merchants[merchant_id]["balance"] += merchant_payout

    return {
        "payment_id": payment_id,
        "platform_fee_percentage": platform_fee_percentage,
        "platform_fee": platform_fee,
        "merchant_payout": merchant_payout,
        "message": "Payment successful"
    }

The endpoint initiates the payment for the selected products. You might notice that platform_fee_percentage is a requested parameter (10 percent by default) that allows merchants or platform admins to set a custom percentage for the platform fee for each transaction. This allows them to customize the fee based on factors such as transaction type (card-based vs. non-card transactions), debit vs. credit cards, merchant category code, and commercial vs. consumer cards to determine the right platform cost based on the transaction overheads and risks. This fee is then deducted from the total product amount, and the remaining amount is updated in the merchant's balance.

It's possible for the client to disconnect after the API request is initiated but before a response can be received. This would mean that the payment is processed, but since the client (ie the Python app) doesn't know about it, the purchase will fail. In such situations, webhooks can help by sending a callback message to your app every time a payment is processed. In a real-world app, you must implement these to make your payments reliable.

Create an Endpoint to Automate Merchant Payouts

Finally, once the payment is successful, merchants should be able to withdraw their funds using the Rapyd payout system. To implement this functionality, create the final endpoint as follows:

@app.post("/merchant/{merchant_id}/payout")
def payout_merchant(merchant_id: str):
    if merchant_id not in merchants:
        raise HTTPException(status_code=404, detail="Merchant not found")

    balance = merchants[merchant_id]["balance"]
    if balance <= 0:
        raise HTTPException(status_code=400, detail="No funds available for payout")

    payout_data = {
        "amount": balance,
        "currency": "USD",
        "payout_method_type": "bank_transfer",
        "sender_currency": "USD",
        "beneficiary": {"name": merchants[merchant_id]["name"]}
    }

    headers = generate_rapyd_headers("post", "/v1/payouts", payout_data)
    response = requests.post(f"{RAPYD_BASE_URL}/v1/payouts", json=payout_data, headers=headers)

    if response.status_code != 200:
        raise HTTPException(status_code=500, detail="Failed to process payout")

    payout_response = response.json()
    payout_id = payout_response.get("id")
    payouts[payout_id] = {"merchant_id": merchant_id, "amount": balance}
    merchants[merchant_id]["balance"] = 0

    return {"payout_id": payout_id, "message": "Payout successful"}

This endpoint allows you to pay merchants without having to worry about manually calculating their earnings and initiating transfers for those amounts. Moreover, it also automates compliance with payout regulations.

Run the App

That's it! You've just created a partner payments solution where merchants can be onboarded and add products, and customers can make payments for purchased products using Rapyd. The next step is to run your app and test the endpoints.

To run the app, open a command prompt and run the merchant_rapyd_app.py file as follows:

uvicorn merchant_rapyd_app:app --host 0.0.0.0 --port 8000 --reload

This will start your application, which you can access in your browser at http://localhost:8000/docs:

Feel free to test the endpoints that you've created with curl commands.

This command registers the merchant and creates a new merchant account:

curl -X POST "http://localhost:8000/merchant/register?name=John's%20Store"

{ "merchant_id": "550e8400-e29b-41d4-a716-446655440000", "message": "Merchant registered successfully" }

Save this merchant ID for additional tests.

List a product for the merchant (with the appropriate merchant ID) using the following command:

curl -X POST "http://localhost:8000/merchant/550e8400-e29b-41d4-a716-446655440000/add_product?name=Wireless%20Headphones&price=50.0"

{ "product_id": "c1a7f2d5-3e3a-49c6-bc15-22a5dc5e2a80", "message": "Product added successfully" }

Save this product ID for the next test.

Payment processing should happen as soon as the customer buys a product. You can test this with the following endpoint hit (using the product ID):

curl curl -X POST "http://localhost:8000/pay/c1a7f2d5-3e3a-49c6-bc15-22a5dc5e2a80?currency=USD&payment_method=card&platform_fee_percentage=10.0"

{ "payment_id": "pay_12345", "platform_fee_percentage": 10.0, "platform_fee": 5.0, "merchant_payout": 45.0, "message": "Payment successful" }

Since you set the platform fee to 10 percent, it's deducted from the total product amount, and the remaining amount is reflected in the merchant payout. The payment ID is useful for tracking payments.

Finally, test the merchant payout with the following command:

curl -X POST "http://localhost:8000/merchant/550e8400-e29b-41d4-a716-446655440000/payout"

{ "payout_id": "payout_567e4567-e89b-12d3-a456-426614174003", "message": "Payout successful" }

You can access the full code in this GitHub repo.

Conclusion

After reading this article, you now know how to implement a partner-based payment system using Rapyd. You've explored various partner models (ISO and PayFac), the key components of a partner payment flow, and a step-by-step guide to building a payment solution with Rapyd and Python.

Rapyd offers a simplified solution for payment processing that makes it easier for SaaS platforms, marketplaces, and fintech businesses to onboard partners, receive payments, and automate revenue sharing. Ready to integrate Rapyd into your platform? Sign up for a free Rapyd account and check out the Rapyd API documentation.