DEV Community: Drew Harris

Boosting Authorization Rates: Partnering Strategies and Intelligent Retries

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

By: Adeyinka Adegbenro

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

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

Understanding the Payment Authorization Funnel

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

Stages of an Online Payment

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

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

Declines and Visibility into the Funnel

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

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

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

Implementing Smart Retry Logic with MACs

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

The following are some common MACs and their meaning:

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

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

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

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

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

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

Using AI to Predict and Optimize Authorization Outcomes

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

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

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

Use Case: Training Models on Transaction Data

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

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

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

How a Data-Driven Approach Boosts Success Rates

AI enables the following intelligent mechanisms within payment systems:

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

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

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

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

Partnering with a Unified Payments Platform

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

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

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

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

Sample Project: Payment Retry Orchestrator with MAC Logic

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

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

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

cd payment-retry-orchestrator

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

The main components include the following:

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

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

node index.js

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

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

Conclusion

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

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

Blockchain Interoperability: Connecting Multiple Blockchain Networks for Payments

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

Writer Name: Vivek Kumar Maskara

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

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

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

Why Fintech Applications Need Blockchain Interoperability

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

Here are a few benefits of blockchain interoperability:

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

Simplifying Payment Verification with Rapyd

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

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

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

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

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

Implementing Blockchain Interoperability

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

Here are the primary components of the project:

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

Prerequisites

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

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

Cloning the Starter Project

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

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

Let's go over the structure of the codebase:

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

Defining Smart Contracts for Cross-Chain Transaction Verification

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

CrossChainPayment contract

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

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

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

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

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

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

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

PaymentVerified contract

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

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

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

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

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

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

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

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

Defining Scripts to Deploy the Smart Contracts

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

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

const hre = require("hardhat");

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

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

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

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

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

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

const hre = require("hardhat");

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

  await contract.waitForDeployment();

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

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

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

Deploying the Smart Contracts to testnets

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

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

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

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

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

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

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

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

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

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

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

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

Contract deployed to: 0x09292e7C53697DFcdBA3c51425bb7e36d7F6Ef2a

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

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

Then, deploy the CrossChainPayment to the Sepolia chain:

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

Finally, deploy the PaymentVerifier to the Sepolia chain:

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

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

Defining the Relay Script

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Testing Cross-chain Interactions

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Verification TX sent: 0xb034b9bcd67eb3b58615fcdcd3704df70f75608bda16c1f2a454dc0f200a14dd

Conclusion

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

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

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

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

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

By: Gourav Bais

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

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

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

Core Payment Requirements in the Creator Economy

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

Royalty Payments

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

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

Affiliate Payouts

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

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

Subscription Management

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

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

Benefits of Using Rapyd APIs for Creator Payment Systems

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

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

Implementing a Creator Payment System with the Rapyd API

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

Prerequisites

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

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

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

Create a Rapyd Authentication File

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

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

RAPYD_ACCESS_KEY=your_access_key_here
RAPYD_SECRET_KEY=your_secret_key_here

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

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

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

load_dotenv()

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

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

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

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

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

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

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

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

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

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

This code can be broken down into the following components:

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

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

Create an Rapyd API App

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

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

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

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

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

app = FastAPI()

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

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

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

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

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

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

Royalty Payments

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

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

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

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

This code uses the following variables:

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

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

Affiliate Payouts

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

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

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

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

Managing Subscriptions

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

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

The following variables are used:

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

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

Run the Application

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

uvicorn main:app --reload

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

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

/royalty-payments

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

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

Your output will look like this:

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

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

/affiliate-payout

This endpoint pays a commission to an affiliate:

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

Your output will look something like this:

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

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

/create-subscription

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

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

Your output will look something like this:

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

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

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

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

Conclusion

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

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

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

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

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

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

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

The Golden Nugget: APIs as Your Compliance Backbone

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

1. API Selection Criteria: Choosing Your Compliance Partner Wisely

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

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

2. Integration Patterns: Weaving Compliance into Your Workflow

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

Onboarding (KYC/KYB): The Asynchronous Dance

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

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

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

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

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

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

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

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

Pattern: Synchronous Request-Response.

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

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

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

Post-Transaction Monitoring: The Background Watcher

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

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

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

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

4. Error Handling & Fallbacks: Building Resilient Systems

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

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

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

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

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

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

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

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

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

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

import hmac
import hashlib

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

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

6. Testing Methodologies: Ensuring Compliance and Performance Under Pressure

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

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

Conclusion

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

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

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

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

🗞 Rapyd Developer Newsletter: May 2025 🛠 Build Real-Time Payments with Rapyd’s Latest Tools

Drew Harris — Thu, 12 Jun 2025 15:15:41 +0000

💾 New API & Product Updates

Updated API Changelog and Product Changelog are now available.
Be sure your integrations are up to date!

⚡ Real-Time Payment Systems with Rapyd

Design instant, intelligent payment experiences with Rapyd’s APIs. Our latest guide walks you through building real-time systems that scale with your business.

🧩 Fintech APIs: Architecting the Future with AI

From fraud prevention to customer service, discover how AI is reshaping payments. Explore strategies and real-world applications with Rapyd’s platform.

🖥 POS Terminals: Fintech Reinvented

Ensure your APIs are compliant with GDPR, PSD2, and global regulations. Get the tools and tips for secure, audit-ready development.

🧾 Simplify Crypto Payouts with Beneficiary Tokenization

Easily generate a hosted page for beneficiary tokenization and enable USDC payouts. Check out the new docs and start building.

💼 Understand Wallet Balances with Merchant Reports

New updates to the Client Portal Guide now help you reconcile wallet balances and monitor transaction data.

See you next month,
The Rapyd Developer Community Team

💡 We’d love to hear from you! Got an idea, tutorial, or topic you'd like to see covered? Just reply and let us know.

From Gig to Cash‑Out Build & Monetize Global Payouts

Drew Harris — Thu, 12 Jun 2025 09:00:00 +0000

TL;DR: Gig platforms thrive on efficient cash-outs. Discover how to build this crucial revenue engine in an afternoon using Rapyd’s Disburse API and a ready-to-fork repository. Turn payouts into profit, globally!

1. The Micro‑Payment Opportunity is Massive

The gig economy isn't just a trend; it's a powerhouse. With over 435 million online gig workers worldwide, the flow of earnings is staggering. Yet, many burgeoning marketplaces and innovative side hustles still wrestle with the friction of manual payouts or the delays of traditional payroll systems.

Here's the game-changer: instant payouts + strategic micro-fees = a win for everyone. Workers gain immediate access to their hard-earned cash, fostering platform loyalty and stickiness. Simultaneously, the platform unlocks a scalable, automated revenue stream with every single transaction. It's time to tap into the immense potential of this micro-payment gold rush.

2. API Monetization 101: Why Pay-Per-Use Wins for Gigs

When integrating payments, monetization models come in various flavors:

Freemium: Basic features free, advanced tiers paid.
Subscription: Recurring fees for platform access.
Pay-Per-Use: Charges based on transaction volume.

For gig economy payouts, pay-per-use, especially when combined with a small surcharge for expedited ("instant") options, is the clear winner. The direct value exchange – worker receives funds, platform earns a small fee – makes it easily understandable and acceptable. Look at DoorDash's "Fast Pay," charging a modest $1.99 for quicker access to earnings. It's a proven model.

3. Rapyd Disburse: Your Unified Gateway to Global Payouts

Forget juggling multiple integrations and navigating complex banking regulations. Rapyd's Disburse API offers a single, powerful entry point to over 190 countries, handling currency conversions (FX) seamlessly under the hood. Get instant access to sandbox API keys and start building without the usual payment infrastructure headaches. Focus on your platform's core value proposition, not the plumbing.

4. Architecture at a Glance

Our example application boasts a straightforward, developer-friendly architecture:

Frontend: A sleek Next.js user interface.
Backend: Robust Next.js API routes for server-side logic.
Database: Reliable PostgreSQL for persistent data storage.
Webhooks: Real-time event notifications from Rapyd.
Fee Logic: Simple, configurable fee calculation.

5. Hands‑On: Building Your Monetized Payout System

Let's get practical. Here's how to get this up and running:

5.1 Clone & Install

Fire up your terminal and clone the repository:

git clone https://github.com/Rapyd-Samples/rapyd-basic-payroll-app-with-disburse.git
cd rapyd-basic-payroll-app-with-disburse
npm install

5.2 Configure Environment Variables

Create a .env.local file and populate it with your Rapyd API credentials and desired fee structure:

```Code snippet
RAPYD_API_KEY=YOUR_RAPYD_API_KEY
RAPYD_SECRET_KEY=YOUR_RAPYD_SECRET_KEY
FEE_FIXED=0.10
FEE_PERCENT=0.01
EXPRESS_PAYOUT_SURCHARGE=0.50 # Optional surcharge for express payouts




You can find your API Key and Secret Key in your Rapyd Sandbox dashboard.

### 5.3 Seed Test Data

Populate your database with some sample workers and earnings using the seed script:

`Bashnpm run seed`

Expect output similar to:

Seeding database...
Worker "Alice" created with ID: 1
Earnings added for Alice: $175.50
Worker "Bob" created with ID: 2
Earnings added for Bob: $230.25
Database seeding complete.




### 5.4 Trigger Standard vs. Express Payout

> *(Imagine a short GIF embedded here showing a simple UI with a list of workers, a "Payout" button, a modal to enter the amount, and options for "Standard" and "Express" payout before a final confirmation.)*

The application provides a straightforward UI to initiate payouts. Here's an example of a basic API request for a standard payout:



```code
{
  "amount": 75.00,
  "currency": "USD",
  "beneficiary": {
    "type": "bank_account",
    // ... detailed beneficiary information ...
  },
  "payout_method_type": "us_ach"
}

When an "Express Payout" is selected (and EXPRESS_PAYOUT_SURCHARGE is configured), the application logic will add this surcharge to the final amount processed by Rapyd.

5.5 Webhook Billing Flow

Rapyd Webhooks are essential for accurate fee tracking. When a payout completes successfully (payout.completed event), your backend receives a notification. Here's a simplified snippet of how you might handle this event and record the fee:

// /pages/api/webhooks/rapyd.js (example)
export default async function handler(req, res) {
  if (req.method === 'POST') {
    const event = req.body;
    if (event.type === 'payout.completed') {
      const { amount, id: payoutId, metadata } = event.data;
      const { workerId, isExpress } = metadata;
      let fee = parseFloat(process.env.FEE_FIXED) + (amount * parseFloat(process.env.FEE_PERCENT));
      if (isExpress === 'true' && process.env.EXPRESS_PAYOUT_SURCHARGE) {
        fee += parseFloat(process.env.EXPRESS_PAYOUT_SURCHARGE);
      }
      try {
        const result = await pool.query(
          'INSERT INTO invoices (worker_id, payout_id, amount, fee, created_at) VALUES ($1, $2, $3, $4, NOW())',
          [workerId, payoutId, amount, fee]
        );
        console.log(`Recorded fee of ${fee.toFixed(2)} for payout ${payoutId}`);
        res.status(200).send('Webhook received and processed');
      } catch (error) {
        console.error('Error recording invoice:', error);
        res.status(500).send('Error processing webhook');
      }
    } else {
      res.status(200).send('Webhook received');
    }
  } else {
    res.setHeader('Allow', ['POST']);
    res.status(405).end(`Method ${req.method} Not Allowed`);
  }
}

5.6 Admin Dashboard

(Imagine a simple screenshot here showing a basic admin interface displaying a table or chart of collected fees, potentially broken down by date or worker.)

The included (basic) admin dashboard provides a quick overview of the fees your platform has collected.

6. Deploy & Go Live

Get your payout engine live quickly using platforms like Render or Railway, which offer seamless deployment from Git repositories. Simply connect your forked repo, configure your environment variables (API keys, fee settings) as secrets in their dashboards, and let them handle the build and deployment process. Remember to run any necessary database migrations on your deployed environment and configure your Rapyd Webhook URL in the Rapyd dashboard to point to your live backend webhook endpoint.

7. Monetization Tweaks & Ideas

The basic fee structure is just the beginning. Consider these enhancements:

Tiered Fees: Adjust fees based on the number of active workers.
FX Markup: Add a small margin on currency conversions.
Subscription Add-ons: Offer premium analytics or invoicing for a recurring fee.
"Instant Payout" Upsell: Clearly market the faster payout option with its surcharge.

8. Security & Compliance Notes

Since this setup primarily handles payouts and doesn't directly process or store sensitive card data, the PCI DSS scope is minimal. However, for platforms with high transaction volumes or specific regulatory requirements, consider integrating Rapyd's KYC (Know Your Customer) solutions. Always consult with legal and compliance experts for your specific jurisdiction.

9. Key Takeaways: Your Fast Track to Monetized Payouts

In just an afternoon, you can build a global payout system with built-in monetization. Rapyd Disburse handles the complexity, and our ready-to-fork repo gives you a running start. Start earning revenue with every cash-out, quickly and efficiently.

10. Ready to Monetize Your Gig Economy Platform?

Stop leaving money on the table!

GET THE REPO NOW

Set your fees, deploy your application, and start tracking your platform's profit. Share your feedback and any cool enhancements you build in the comments below!

Tokenization in Payments: The Future of Secure, Anonymous Transactions

Drew Harris — Tue, 10 Jun 2025 10:00:00 +0000

By: Adeyinka Adegbenro

Since the 2010s, the gatekeepers of the payment industry—think Payment Card Industry Data Security Standard (PCI DSS), Mastercard, and Visa—have promoted tokenization as the industry standard for compliance and card-related fraud prevention.

Why? Because tokenization is extremely important for protecting the privacy of financial institutions. Instead of sharing a card's actual sixteen-digit number, it swaps in a unique, randomly generated token so that a user's raw card details are never shared.

In this article, you'll learn more about tokenization and how to implement payment tokenization using the Rapyd API.

Understanding Tokenization

At its core, tokenization replaces sensitive payment details with nonsensitive, randomly generated tokens that can't be reversed, unless you have access to the provider's vault. These tokens are securely stored either by the merchant or in the tokenization provider's vault.

Tokenizing payment data doesn't use just a single algorithm—it uses a layered approach that combines techniques, like masking, cryptographic storage, obfuscation, and randomization, to create secure tokens:

In most cases, using a tokenization service is recommended over creating your own service because it's PCI DSS–compliant out of the box, quicker to implement, and built to scale.

It's important to note that tokenization does not replace due diligence. You still need to validate PCI DSS compliance, but it may simplify the process by reducing the number of components subject to PCI DSS requirements.

Benefits of Tokenization

The main benefit of tokenization is that it significantly reduces the impact of data breaches and the risk of fraud because the stolen tokens can't be used to access the original card details. Tokenization also provides you with the following benefits:

Requires fewer resources than other privacy measures, like encryption, because it doesn't involve complex mathematical operations and can be carried out by third-party providers like Rapyd.
Enables secure storage of credit card information for modern payment methods, including one-click payments, mobile wallets, and cryptocurrencies.
Enhances security and convenience while remaining invisible to customers, allowing businesses to offer a seamless payment experience without requiring user actions like signing up, logging in, or managing passwords.
Reduces fraud risk, increasing the likelihood of bank transactions.

Encryption vs. Tokenization

Tokenization is the process of replacing sensitive data with a token. Meanwhile, encryption is the process of converting data into an unreadable format using a decryption key. Encryption is ideal for securely transmitting and retrieving data, like encrypted emails, readable only by recipients with the cryptographic key. In contrast, tokenization is best for masking data that doesn't need to be stored in its original form. Unlike encryption, tokenization is irreversible if you don't have access to the token vault.

Encryption also differs from tokenization because encryption can be computationally intensive, especially for large-scale systems. Encryption is widely used for general data security and compliance with privacy laws like the Health Insurance Portability and Accountability Act (HIPAA) and the General Data Protection Regulation (GDPR).

In contrast, tokenization is lightweight, making it the primary choice for PCI DSS.

How to Implement a Tokenized Payment System with Rapyd

In this tutorial, you'll learn how to use Rapyd for tokenization in a payment system by using a sample project on GitHub called Rapyd_Ecommerce or rapyd-tokenization-example
. Rapyd_Ecommerce is a simple Node.js app that uses Express as a server and EJS as a light template framework to render the UI.

Before you begin, you need to install the latest version of Git, Node.js, and npm (which comes with Node.js) on your computer.

Once you have the latest version of Git, clone the sample application from GitHub by running the following:

git clone https://github.com/Rapyd-Samples/rapyd-tokenization-example.git

cd Rapyd_Ecommerce

Create a Rapyd Account

If you don't already have one, create a Rapyd account. Once you're signed in, you will, by default, be in sandbox mode.

From the sidebar, navigate to Developers > API access control and note your sandbox credentials:

Next, create a .env file in the root folder. This holds your Rapyd credentials:

touch .env

In the .env file, add the following:

RAPYD_ACCESS_KEY=<YOUR_RAPYD_ACCESS_KEY>
RAPYD_SECRET_KEY=<YOUR_RAPYD_SECRET_KEY>
RAPYD_BASE_URL=https://sandboxapi.rapyd.net

Then, in the same file, replace and with your access key and secret key. Install the dependencies:

npm install

Finally, start the server:

npm start

Since the Rapyd API doesn't support localhost URLs for webhooks, this tutorial uses ngrok to create a secure, temporary public URL that tunnels requests to your local server. Use the following code to install ngrok:

npm install -g ngrok

Then, create an ngrok account and fetch your ngrok token by selecting Your Authtoken from the sidebar. Copy your authtoken, add it to ngrok in the terminal, and start the server:

ngrok config add-authtoken $YOUR_AUTHTOKEN

ngrok http 3000

In the output, you'll see a public URL that looks like this—https://862e-102-89-82-24.ngrok-free.app:

Set Up Webhooks

Webhooks are sent by Rapyd after a payment request is completed—whether successful, failed, or canceled.

From your Rapyd Client Portal, navigate to Developer > Webhooks > Management. Go to the section named Define your callback URL and the events that will trigger it. On the blank, add your callback URL. It should look something like this:

For example, if your public URL is https://cb9d-102-89-83-16.ngrok-free.app, then the callback URL will be https://cb9d-102-89-83-16.ngrok-free.app/api/webhook.

In the Collect section, click Select all and save your changes. From now on, whenever a payment flow starts and the user completes payment, the server receives a webhook request at /api/webhook with an update on the original payment request.

Set Up the Payment Flow

To start the payment flow, enter your ngrok public URL in a browser and click Visit Site. You'll see a page listing gadgets and their prices:

This page is being served by index.ejs and the product data from products.json. Clicking the Buy button sends a GET request to the server endpoint (/buy) along with the productId, amount, and currency.

In server.js, the /buy endpoint renders the Checkout page using views/checkout.ejs. This page collects the user's card details and processes the payment. The Rapyd API securely tokenizes the card details and charges the card based on the specified currency, amount, and other transaction details.

When the Checkout page loads, the app sends a request to the /create-checkout endpoint to retrieve the Rapyd Checkout page URL. Handling this on the backend is more secure as it keeps sensitive API credentials like RAPYD_ACCESS_KEY and RAPYD_SECRET_KEY hidden.

In server.js, the /create-checkout route needs to call the Rapyd API /v1/checkout endpoint with the required headers and body attributes. For a list of possible attributes, see the Rapyd Create Checkout Page documentation.

For this tutorial, the body payload contains the required attributes as well as a few others. On line 75, the body payload contains the following:

amount refers to the price of the gadget converted to string format.
currency is the currency of the item being purchased.
country is the two-letter ISO 3166-1 code for the country.
complete_payment_url is the URL to which you want Rapyd to redirect the user after a successful checkout. It's set to http://localhost:3000/success.
error_payment_url is the URL to which you want Rapyd to redirect the user after a failed checkout. In this case, it's set to http://localhost:3000/fail.

Rapyd uses HMAC-SHA256 signature-based authentication to verify that every API request comes from an authorized source. This means that a request to /v1/checkout must include a digitally signed SHA-256 signature.

In server.js (line 88), the header object contains the following attributes:

content-type is set to application/json, indicating the request body is in JSON format.
access_key is retrieved from your .env file. This is the Rapyd access key found in the Developers section of your Rapyd Client Portal.
idempotency is a unique ID generated using the uuid library (UUID version 4) to prevent duplicate transactions. When retrying a failed request, reuse the same idempotency key to avoid processing it as a new request.
salt is an eight- to sixteen-digit random string required by Rapyd to generate a unique signature for each request, preventing replay attacks. It's an extra layer of security to protect against malicious reuse of old requests. While the idempotency key can be reused for retries, the salt and signature must be regenerated for every request.
timestamp is the request timestamp in Unix format (seconds).
signature is generated in the generateSignature function by concatenating the request method (POST), URL path (/v1/checkout), salt, timestamp, access key, secret key, and the stringified JSON body. The string is then hashed using SHA-256 and encoded to Base64. For more details, check out the Rapyd documentation on Signatures.

Once the POST request is successfully sent to /v1/checkout, /create-checkout returns the checkout_url to checkout.ejs, which then redirects the page to the official Rapyd Checkout page. At this point, you should see a Checkout page with multiple payment options:

Since this tutorial focuses on card payment and tokenization, select the Card option.

Rapyd provides test card numbers for testing card payments. Use 4111111111111111 as the card number, any future date as the expiration date, and any three-digit number as the CVV number. Then select Place Your Order.

Once you've placed the order, you should see another authentication page that mimics 3-D Secure:

Enter 123456 and click Continue. Rapyd then handles payment tokenization and charges the card. All this is done on the Rapyd secure servers, which means you don't need to worry about card number security, tokenization, or the details of charging the card.

If the payment fails, the error_payment_url endpoint /fail is called, and a PAYMENT_FAILED webhook is sent to the /api/webook endpoint.

On the flip side, if the payment is successful, the complete_payment_url endpoint /success is called. Then a PAYMENT_SUCCEEDED webhook is sent to the /api/webook endpoint:

Rapyd lets you save a user's card details by initially creating a customer via the Create Customer endpoint, which returns a customer ID. This ID can be included in the /v1/checkout request, giving users the option to save their card for future purchases. For future transactions, simply reuse the customer ID to access saved cards—securely stored by Rapyd—so they never need to be saved on your server.

The beauty of this payment flow is that the tokenization process is completely abstracted away, leaving you time to focus on other things.

Conclusion

Without tokenization, unprotected data is a ticking time bomb. A data breach costs millions in damages and fines. Adding tokenization to your system design helps you build data breach–resilient systems.

Using the Rapyd API for tokenization, you can safeguard payment data for all your tokenization needs while ensuring compliance with global security best practices. Rapyd can also be used to receive, send, and manage funds globally. Learn more about Rapyd today.

Fintech APIs: Architecting the Future with AI

Drew Harris — Fri, 16 May 2025 17:57:44 +0000

APIs have long been the foundation of fintech innovation, enabling everything from payouts to identity verification. Now, Artificial Intelligence is fundamentally changing how developers build and interact with these tools, transforming them from static integrations into intelligent decision-making systems.

This article explores the evolution of fintech APIs and provides actionable insights for developers looking to build smarter, AI-enhanced payment workflows using GPT-4 and Rapyd.

The Rise of AI-Powered APIs

APIs are evolving from simple data conduits to context-aware services. Integrating large language models like GPT-4 into financial workflows allows developers to move from fixed rules to intelligent, adaptive logic.

This leads to advancements in fintech such as:

Smarter real-time payment decisioning
Adaptive credit workflows based on user behavior
Evolving fraud detection systems

Let's look at a practical implementation.

Project: GPT-4 Powered Payment Form

We've created an example project to help developers explore this future. It's a working template for integrating AI into real-world fintech flows.

Implementation: GPT-4 and Rapyd Integration

This open-source repository demonstrates how to:

Generate secure payment forms using GPT-4
Implement custom payment workflows based on user needs
Trigger payment actions via Rapyd’s API
Create a modular and customizable framework

This project provides a starting point for applications like AI-driven form pre-filling, intelligent chatbot checkouts, and AI-assisted KYC processes.

Repository Contents:

main.py: AI and payment interaction orchestration
form_generator.py: GPT-4 powered secure form generation
payment_flows.py: Rapyd API interaction logic
.env.example: Setup for API keys and tokens

This demonstrates secure connection of AI-generated input to real API calls within a scalable architecture.

Developer Benefits

This shift towards AI-enhanced APIs offers significant advantages:

Reduced manual steps and intelligent defaults
Simplified and secure API interaction
Improved user and business experiences

This approach is crucial for developers in areas like embedded finance, wallets, B2B payouts, and global payments.

Explore the Implementation

Start exploring the possibilities of AI-enhanced fintech development:

👉 GPT-4 + Rapyd Payment Workflow on GitHub

This open-source project is designed for quick setup and real-world application.

Fork it, extend it, and use it as the foundation for your next fintech innovation.

Real-Time Payment Systems: How to Build Instant Payment Solutions with Rapyd

Drew Harris — Tue, 13 May 2025 13:08:20 +0000

By: Gift Uhiene

Real-time payment (RTP) systems enable instant fund transfers between bank accounts, making them essential for modern financial applications. For each transaction, funds and payment information are exchanged and settled within seconds of the transaction initiation. RTP service is continuous 24/7 and available all year round.

Rapyd is a global fintech-as-a-service provider that enables businesses to perform instant fund transfers in local currencies and maintain digital wallets globally. With its extensive API offerings, developers can integrate Rapyd finance capabilities into their applications to effortlessly manage cross-border payments, multicurrency treasury, card issuing, fraud protection, and compliance.

In this tutorial, you'll learn how to build an RTP-enabled Node.js app using Rapyd and WebSockets, covering setup, API integration, and transaction handling.

You can explore the complete code and follow along with the implementation via GitHub.

Prerequisites

Before getting started, you should have the following:

A Rapyd account; if you're signing up for the first time, you'll need to verify your email and complete the required verification steps
Node.js installed on your system
A basic understanding of JavaScript, React.js, and APIs

Getting Rapyd API Credentials

Store these keys securely as you'll need them to authenticate API requests:

Building a Real-Time Payment Backend

In this section, you'll build a backend system that integrates the Rapyd API and WebSockets to create a real-time payment flow. The system will allow users to create wallets, initiate transfers, and receive real-time updates on transfer statuses. Here's what we'll cover:

Setting up the Rapyd API client to send secure requests
Creating a WebSocket server to broadcast real-time updates to clients
Creating wallet controllers to communicate with Rapyd APIs
Building the Express server to tie everything together

Project Setup

Clone the starter branch of the project with the command below:

git clone --branch starter --single-branch https://github.com/Rapyd-Samples/rtp-rapyd.git

This is the structure of the backend directory:

rtp-rapyd/
    │── backend/
    │   │── node_modules/
    │   │── src/
    │   │   │── config/
    │   │   │   ├── rapydClient.js    # Handles API requests to Rapyd
    │   │   │── controllers/
    │   │   │   ├── walletController.js   # Logic for wallet
    │   │   │── routes/
    │   │   │   ├── walletRoutes.js   # Defines API routes for wallet actions
    │   │   │── server.js             # Main entry point
    │   │   │── websocket.js          # WebSocket logic for real-time updates
    │   │── .env                      # API keys and secrets
    │   │── package.json              # Project dependencies
    │   │── README.md                 # Documentation

Installing Dependencies

Navigate to the backend directory in your terminal and install dependencies:

cd backend
npm install

Then, run the following command in the backend directory of your terminal to start the server:

npm run dev

Configuring the Rapyd API Client

To interact with Rapyd's API, you'll need a client that handles authentication, request signing, and HTTP communication.

Rapyd's API requires specified header parameters for each request to verify that the requester is an authorized user and to protect against data tampering.

Go to the backend/src/config/rapydClient.js file and include the code below to set up a Rapyd API client. This will allow you to securely authenticate and make HTTP requests to Rapyd's API:

require("dotenv").config();
const https = require("https");
const crypto = require("crypto");

const accessKey = process.env.RAPYD_ACCESS_KEY;
const secretKey = process.env.RAPYD_SECRET_KEY;

async function makeRequest(method, urlPath, body = null) {
  try {
    const httpMethod = method.toUpperCase();
    const httpBaseURL = "sandboxapi.rapyd.net";
    const salt = generateRandomString(8);
    const idempotency = new Date().getTime().toString();
    const timestamp = Math.round(new Date().getTime() / 1000);
    const signature = sign(httpMethod, urlPath, salt, timestamp, body);

    const options = {
      hostname: httpBaseURL,
      port: 443,
      path: urlPath,
      method: httpMethod,
      headers: {
        "Content-Type": "application/json",
        salt: salt,
        timestamp: timestamp,
        signature: signature,
        access_key: accessKey,
        idempotency: idempotency,
      },
    };

    return await httpRequest(options, body);
  } catch (error) {
    console.error("Error generating request options", error);
    throw error;
  }
}

function sign(method, urlPath, salt, timestamp, body) {
  try {
    let bodyString = body ? JSON.stringify(body) : "";
    let toSign =
      method.toLowerCase() + urlPath + salt + timestamp + accessKey + secretKey + bodyString;

    let hash = crypto.createHmac("sha256", secretKey);
    hash.update(toSign);
    return Buffer.from(hash.digest("hex")).toString("base64");
  } catch (error) {
    console.error("Error generating signature", error);
    throw error;
  }
}

function generateRandomString(size) {
  return crypto.randomBytes(size).toString("hex");
}

async function httpRequest(options, body) {
  return new Promise((resolve, reject) => {
    try {
      let bodyString = body ? JSON.stringify(body) : "";

      const req = https.request(options, (res) => {
        let response = { statusCode: res.statusCode, headers: res.headers, body: "" };

        res.on("data", (data) => {
          response.body += data;
        });

        res.on("end", () => {
          response.body = response.body ? JSON.parse(response.body) : {};
          if (response.statusCode !== 200) return reject(response);
          return resolve(response);
        });
      });

      req.on("error", (error) => reject(error));

      req.write(bodyString);
      req.end();
    } catch (err) {
      reject(err);
    }
  });
}

module.exports = { makeRequest };

The code above is from the Node.js example on the Rapyd documentation. The sign function generates a signature for each request using your accessKey and secretKey, ensuring secure communication with the API. To prevent duplicate transactions, every request includes a unique idempotency key.

Before moving forward, create a .env file in the root of the backend directory to store your Rapyd credentials:

RAPYD_ACCESS_KEY=your_access_key
RAPYD_SECRET_KEY=your_secret_key

Setting Up WebSockets

WebSockets enable bidirectional communication between the server and clients, allowing real-time updates without the need for constant polling. Implementing WebSockets in this project will keep the connection open so that when a change happens, the server will immediately update users without them having to refresh the page. To implement this, update backend/src/websocket.js file with the code below:

const WebSocket = require("ws");

let wss;

exports.setupWebSocketServer = (server) => {
  wss = new WebSocket.Server({ noServer: true });

  server.on("upgrade", (request, socket, head) => {
    wss.handleUpgrade(request, socket, head, (ws) => {
      wss.emit("connection", ws, request);
    });
  });

  wss.on("connection", (ws) => {
    console.log("✅ New WebSocket connection");

    ws.on("message", (message) => {
      console.log("📩 Received:", message);
      ws.send(`Server received: ${message}`);
    });

    ws.on("close", () => console.log("❌ Client disconnected"));
  });
};

exports.notifyUsers = (transaction) => {
  if (!wss) return;

  wss.clients.forEach((client) => {
    if (client.readyState === WebSocket.OPEN) {
      client.send(JSON.stringify(transaction));
    }
  });
};

The setupWebSocketServer(server) function initializes a WebSocket server that handles upgrades from an HTTP server, listens for client connections, and processes incoming messages. The notifyUsers(transaction) function will broadcast real-time updates to all connected clients by sending transaction data as a JSON string.

Update backend/src/server.js file with the code below to create a server for the application:

const express = require("express");
const http = require("http");
const cors = require("cors");
const { setupWebSocketServer } = require("./websocket");
const walletRoutes = require("./routes/walletRoutes");

const app = express();

const server = http.createServer(app);

app.use(cors());
app.use(express.json());
app.use("/api/wallet", walletRoutes);

setupWebSocketServer(server);

server.listen(4000, () => console.log("Server running on port 4000"));

Rapyd Wallet: Managing Real-Time Transactions and Fund Transfers

When building a real-time payment system, one of the key components you'll need is a reliable and flexible wallet system. Rapyd Wallet allows businesses and developers to create, manage, and transfer funds between wallets in real time by acting as a financial hub where money can be moved across borders, currencies, and payment methods.

Some of its key features include:

Multicurrency support: Each wallet can hold multiple accounts, each with its own currency and balance.
Custom branding: You can brand the wallets with your own logo and design, making it feel like a native part of your application.
Client and user wallets: A two-tier structure with client wallets for businesses and user wallets for individuals (such as sellers or employees).
FX capabilities: Rapyd Wallet integrates with Rapyd's foreign exchange (FX) features, allowing you to convert currencies at competitive rates.
Split payments: You can split payments between multiple wallets, which is useful for marketplaces or platforms with shared revenue models.

Building the Wallet Controller

To manage all wallet-related operations, let's build a wallet controller. This controller will handle interactions with the Rapyd API and centralize the logic for wallet management.

Open backend/src/controllers/walletController.js and update createWallet with the code below to implement the function to handle wallet creation and initial funding using Rapyd's API:

exports.createWallet = async (req, res) => {
  try {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({ errors: errors.array() });
    }

    const { first_name, last_name, email, type } = req.body;

    const timestamp = Date.now();
    const emailPrefix = email.split("@")[0];
    const ewalletReferenceId = `${emailPrefix}_${timestamp}`;

    // Construct the wallet creation payload
    const walletData = {
      first_name,
      last_name,
      ewallet_reference_id: ewalletReferenceId,
      email,
      type,
      contact: {
        email,
        first_name,
        last_name,
        contact_type: `${type === "company" ? "business" : "personal"}`,
        country: "SG",
        address: {
          name: `${first_name} ${last_name}`,
          line_1: "123 Main Street",
          country: "SG",
        },
        country: "SG",
        date_of_birth: "2000-11-22",
        metadata: {
          merchant_defined: true,
        },
      },
    };

    const walletResponse = await makeRequest(
      "POST",
      "/v1/ewallets",
      walletData
    );
    const walletId = walletResponse.body.data.id;

    const fundResponse = await makeRequest("POST", "/v1/account/deposit", {
      ewallet: walletId,
      currency: "SGD",
      amount: 20,
    });

    res.json({
      wallet: walletResponse.body.data,
      initial_deposit: fundResponse.body,
    });
  } catch (error) {
    handleError(res, error);
  }
};

This code performs the following steps:

Validates the request using express-validator to ensure all required fields are present.
Extracts user details from the request body.
Generates a unique ewallet_reference_id by combining the email prefix and a timestamp.
Constructs a walletData object containing user details, contact information, address, and metadata. Some fields, like the country (SG), are hard-coded but can be customized.
Creates a wallet by sending a POST request to Rapyd's /v1/ewallets endpoint. The response includes a walletId that uniquely identifies the wallet.
Funds the wallet with 20 SGD by making a deposit request to /v1/account/deposit. This step is specific to sandbox mode, as real deposits require actual funding sources in production.
Returns a JSON response with the wallet details and deposit transaction.

Next, in the same file, update the retrieveWallet function to fetch details about a user wallet:

exports.retrieveWallet = async (req, res) => {
  try {
    const accountId = req.params.id;

    if (!accountId) {
      return res.status(400).json({ error: "Account ID is required" });
    }

    const result = await makeRequest("GET", `/v1/ewallets/${accountId}`);
    res.json(result.body.data);
  } catch (error) {
    handleError(res, error);
  }
};

The function above extracts accountId from the request parameters and makes a GET request to Rapyd's API to retrieve a wallet's details.

Transferring Funds Between Wallets

Rapyd allows funds transfers between wallets; if the destination wallet does not have the specified currency, an account for that currency is automatically created. When a transfer is initiated, the status is marked as "PEN" until accepted by the transferee, using the Set Transfer Response API. Unaccepted transfers can, in turn, be canceled by the sender using the same API.

To initiate a peer-to-peer wallet transfer, update the transferFunds function in the backend/src/controllers/walletController.js file:

exports.transferFunds = async (req, res) => {
  try {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({ errors: errors.array() });
    }

    const { senderWalletId, receiverWalletId, amount } = req.body;

    const response = await makeRequest("POST", "/v1/ewallets/transfer", {
      source_ewallet: senderWalletId,
      destination_ewallet: receiverWalletId,
      currency: "SGD",
      amount,
    });

    const transactionId = response.body.data.id;

    if (!transactionId) {
      return res.status(500).json({ error: "Transaction ID not found." });
    }

    notifyUsers({
      sender: senderWalletId,
      receiver: receiverWalletId,
      id: transactionId,
      currency: "SGD",
      amount,
      status: "pending",
      variant: "TRANSFER_FUNDS",
    });

    res.json({
      message: "Transfer initiated. Waiting for confirmation...",
      transactionId,
    });
  } catch (error) {
    handleError(res, error);
  }
};

The function sends a request to Rapyd's /v1/ewallets/transfer endpoint to transfer funds between wallets, using SGD as the currency. It extracts the transaction ID, notifies all WebSocket clients about the transfer, and responds to the client confirming the request was initiated.

Finally, update the respondToTransfer function in the same file to enable both the sender and transferee to respond to a transaction:

exports.respondToTransfer = async (req, res) => {
  try {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({ errors: errors.array() });
    }

    const { status, id } = req.body;

    if (!["accept", "decline", "cancel"].includes(status)) {
      return res.status(400).json({
        error: "Invalid status. Must be 'accept', 'decline', or 'cancel'.",
      });
    }

    const response = await makeRequest(
      "POST",
      "/v1/ewallets/transfer/response",
      {
        id,
        status,
      }
    );

    if (response.body.status.status !== "SUCCESS") {
      return res.status(500).json({ error: `Failed to ${status} transfer.` });
    }

    notifyUsers({
      sender: response.body.data.source_ewallet_id,
      receiver: response.body.data.destination_ewallet_id,
      id,
      currency: response.body.data.currency_code,
      amount: response.body.data.amount,
      status:
        status === "accept"
          ? "Accepted"
          : status === "decline"
          ? "Declined"
          : status === "cancel"
          ? "Cancelled"
          : status.charAt(0).toUpperCase() + status.slice(1),
      variant: "RESPONDS_TO_TRANSFER",
    });

    res.json({
      message: `Transfer ${status}ed successfully.`,
      status: response.body.data.status,
    });
  } catch (error) {
    handleError(res, error);
  }
};

The function extracts the status and id from the request, validates the status (accept, decline, or cancel), and sends a request to Rapyd's /v1/ewallets/transfer/response endpoint to update the transfer. It also notifies the WebSocket clients about the transaction.

Connecting the Frontend

Now that the backend is set up, let's connect the frontend application to interact with the backend and provide real-time updates to users.

Note: Most of the frontend components are already provided in the starter project, so this example doesn't focus on building them from scratch. Instead, you'll concentrate on integrating the frontend with the backend and enabling real-time functionality.

Installing Dependencies

In another terminal, navigate to the frontend directory and install dependencies:

cd frontend
npm install

Run npm run dev to run the React.js project.

The createWallet Function

Go to the frontend/src/components/create-wallet-form.jsx file and update createWallet with the code below. This function sends a POST request to the backend to create a wallet and stores the wallet ID in local storage:

const createWallet = async (e) => {
  e.preventDefault();
  setLoading(true);
  try {
    const response = await axios.post(
      "http://localhost:4000/api/wallet/create",
      userData
    );
    localStorage.setItem("ewallet", response.data.wallet.id);
    await fetchUser();
  } catch (error) {
    console.error("Failed to create wallet:", error);
  } finally {
    setLoading(false);
  }
};

The transferFunds Function

Let's implement the function to transfer funds between wallets. Update transferFunds in the frontend/src/components/transfer-form.jsx file. This function sends a POST request to the backend to initiate a transfer between two wallets:

const transferFunds = async (e) => {
  e.preventDefault();
  setLoading(true);

  try {
    await axios.post("http://localhost:4000/api/wallet/transfer", {
      senderWalletId: walletData.id, 
      receiverWalletId: receiverWallet, 
      amount: Number(amount), 
    });
  } catch (error) {
    console.error("Failed to transfer funds:", error);
  } finally {
    setLoading(false);
  }
};

The respondToTransfer Function

Finally, let's add the function to respond to transfer requests. Update respondToTransfer in the frontend/src/components/transaction-list.jsx file. This function sends a POST request to the backend to approve or reject a transfer:

const respondToTransfer = async (transactionId, action) => {
  setLoading(true);

  try {
    await fetch("http://localhost:4000/api/wallet/respond-transfer", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        id: transactionId,
        status: action,
      }),
    });
  } catch (error) {
    console.error("Failed to respond to transfer:", error);
  }

  setLoading(false);
};

Final Result

To bring everything together, here's a demonstration of the app in action. The GIF below showcases the real-time payment features, including:

Initiating a fund transfer between wallets
Receiving real-time updates on transaction statuses
Accepting, declining, or canceling transfers dynamically

With that, you've successfully implemented a dynamic, real-time payment system using Rapyd's API and WebSockets.

Conclusion

In this article, you learned how to build a real-time payment system using the Rapyd API and WebSockets. From setting up the backend to handling wallet creation, wallet-to-wallet transfers, and real-time updates, you now have the tools to create a seamless payment experience for users. By integrating Rapyd's powerful API and leveraging WebSocket communication, you can ensure that both senders and receivers receive instant feedback on their transactions so your application is dynamic and responsive.

Rapyd's global payment capabilities make it an excellent choice for developers and businesses looking to implement secure and scalable payment solutions in their applications. Whether you're building a peer-to-peer payment app, an e-commerce platform, or a financial service, Rapyd provides the infrastructure to handle transactions efficiently. To explore more features and capabilities, visit the Rapyd API documentation and start building your next fintech solution today.

For further learning, check out Rapyd's developer community resources and sample projects.

Navigating Regulatory Compliance in API Development

Drew Harris — Thu, 03 Apr 2025 09:00:00 +0000

Regulatory compliance is not just a checkbox in API development - it's foundational to maintaining trust, security, and operational integrity. Developers working with enterprise merchants and partners must understand critical regulatory frameworks and embed compliance into every stage of API design and implementation.

Key Regulatory Frameworks

GDPR (General Data Protection Regulation)

GDPR mandates stringent requirements for personal data management within APIs. Developers must ensure:

Data Minimization: Collect only necessary user information.
Consent Management: APIs must facilitate clear and explicit user consent.
Right to Erasure: Implement mechanisms to delete user data upon request.

PSD2 (Payment Services Directive 2)

PSD2 shapes how payment services APIs interact within the European Economic Area:

Strong Customer Authentication (SCA): APIs must support multi-factor authentication.
Secure Communication: Ensuring secure data transmission via encryption and authentication methods.
Open Banking Standards: Adhering to defined API protocols for financial transactions.

Regional Compliance Challenges

Regional regulations, such as California's CCPA or Brazil's LGPD, introduce additional layers of complexity. APIs need configurable compliance logic that adapts to region-specific data protection and security standards.

Building APIs with Compliance in Mind

Compliance should be integral from the outset:

Security by Design: Adopt secure coding practices, perform regular penetration testing, and code reviews.
Data Governance: Implement clear data handling and retention policies.
Documentation and Transparency: Clearly document API functionalities, including compliance-related considerations, making audits smoother.

Embedding compliance strategically doesn't only fulfill obligations - it can deliver competitive advantages like faster market entry, greater customer trust, and reduced risk exposure.

Tools and Strategies for Real-time Reporting and Audit Readiness

Effective compliance management involves real-time monitoring and immediate audit readiness:

Logging and Monitoring: Implement comprehensive logging of API requests and responses.
Real-time Alerts: Develop alert systems for unusual activity to ensure rapid response.
Audit Trails: Maintain immutable records of transactions and user actions for compliance verification.

Practical Resource: Secure Request Signatures

To practically implement secure API interactions, developers can utilize the Rapyd PHP SDK for request signatures:

GitHub Repository: rapyd-request-signatures-php

This repository provides:

Ready-to-use examples demonstrating how to generate and verify secure API request signatures.
Clear documentation to quickly implement security measures compliant with GDPR, PSD2, and similar regulations.

Conclusion

Compliance is integral to Rapyd’s mission to drive global payment innovation securely and reliably. Have you encountered specific regulatory challenges or discovered effective tools in your API projects? We'd love to hear your insights and experiences in the comments below or connect directly with our compliance experts in the Rapyd community.

🗞 Rapyd Developer Newsletter: March 2025 💥 Boost Your Dev Workflow: Automate APIs, Track Payouts & Master Fintech KPIs

Drew Harris — Thu, 27 Mar 2025 14:01:19 +0000

Stay ahead with the latest updates, trends, and tools from the Rapyd Developer Community! 🚀

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

🧩 Using OpenAPI to Automate API Integration With Rapyd's Payment Gateway
Automate setup, reduce errors and speed up payment integrations

💰 Payout Status Change
Get instant visibility into payment progress and track updates effortlessly

💳 Partners: How ISOs and PayFacs Are Shaping Fintech
Explore how industry partners are redefining financial services and unlocking new opportunities

🎯 KPIs Fintech Developers Should Know
Track the metrics that matter in fintech development and optimize performance with actionable insights.

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.

Embedded Financial Services: The Future of Vertical SaaS

Drew Harris — Mon, 03 Mar 2025 15:47:50 +0000

Introduction

Embedded financial services are transforming Vertical SaaS, allowing developers to integrate payments, lending, and banking directly into applications. This shift reduces friction for users, unlocks new revenue streams, and keeps financial interactions inside the platform - a game-changer for SaaS providers.

In this article, we'll cover:

✅ What embedded financial services are and why they matter

✅ Real-world case studies of Vertical SaaS implementations

✅ API strategies for embedding payments in niche industries

✅ A hands-on GitHub project using Rapyd’s API to integrate payments into a travel agency web app

Let’s dive in.

What Are Embedded Financial Services?

Embedded financial services refer to integrating payments, lending, banking, and insurance directly within a software platform. Instead of users relying on external financial institutions, SaaS platforms own the financial experience - improving user retention and creating new monetization opportunities.

Key Examples

📌 Embedded Payments: Accept transactions within the platform.

📌 Lending & Financing: Offer loans to users based on transaction history.

📌 Insurance: Provide in-app coverage for specific user needs.

📌 Digital Wallets: Allow users to store and send money natively.

For developers, the challenge is seamless integration - leveraging APIs to connect financial services while ensuring security, compliance, and scalability.

Case Studies: How Vertical SaaS Embeds Financial Services

1. Payments & Lending in E-Commerce Platforms

A cloud-based e-commerce platform integrated embedded payments and merchant financing, allowing businesses to process transactions without third-party providers. The platform later expanded into business loans, using sales data to assess loan eligibility.

Impact for Developers:

Built-in payments eliminated reliance on external payment gateways.
API-driven underwriting enabled automated financing decisions.
Increased developer control over checkout flows and user experience.

2. Subscription Billing for Service-Based SaaS

A SaaS company serving health and wellness businesses embedded recurring billing and payments, allowing gyms, studios, and therapists to automate payments and manage memberships seamlessly.

Impact for Developers:

Integrated payments reduced churn by keeping transactions inside the platform.
API-driven automation replaced manual billing processes.
Improved reporting capabilities for tracking revenue and subscriptions.

3. Payments & Payroll for Industry-Specific SaaS

A restaurant technology platform embedded payment processing, payroll, and financial reporting to streamline operations for businesses in the hospitality industry.

Impact for Developers:

Developers implemented an API-first approach for real-time financial transactions.
Reduced operational complexity by embedding financial management tools.
Enabled multi-party payments, distributing funds to vendors, employees, and partners.

These examples highlight why embedded finance is the next frontier for SaaS—it increases platform value and revenue by keeping financial transactions inside the ecosystem.

API Strategies for Embedding Financial Services

1. Choosing the Right API Provider

When embedding financial services, pick an API provider that offers:

✅ Comprehensive Documentation – Clear API references, code samples, and tutorials.

✅ Multi-Currency Support – For global transactions.

✅ Compliance & Security – PCI DSS, PSD2, and local financial regulations.

Example Providers:

Rapyd (Global payments, wallets, and payouts)
Stripe (Payments and financial automation)
Plaid (Banking API for financial data)

2. Implementing Embedded Payments with APIs

Let’s say we’re integrating Rapyd’s API into a travel booking platform to accept payments.

Step 1: API Authentication

First, securely authenticate API requests using HMAC signature authentication:

import hmac
import hashlib
import base64

secret_key = "your_secret_key"
message = "data_to_sign"

signature = base64.b64encode(
    hmac.new(secret_key.encode(), message.encode(), hashlib.sha256).digest()
).decode()

headers = {
    "Authorization": f"Bearer {signature}",
    "Content-Type": "application/json",
}

Step 2: Creating a Payment Checkout Page

Send a request to the Rapyd API to generate a checkout page:

import requests

url = "https://sandboxapi.rapyd.net/v1/checkout"
payload = {
    "amount": 100,
    "currency": "USD",
    "complete_checkout_url": "https://yourwebsite.com/success",
    "cancel_checkout_url": "https://yourwebsite.com/cancel",
    "payment_method_types_include": ["card"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Step 3: Handling Webhooks for Payment Confirmation

Use webhooks to listen for successful transactions:

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def webhook():
    data = request.json
    if data["event"] == "PAYMENT_COMPLETED":
        print("Payment received:", data["data"])
    return "", 200

if __name__ == "__main__":
    app.run(port=5000)

📌 Best Practices:

Avoid storing API keys in code – Use environment variables.
Validate webhook requests to prevent spoofing.
Ensure compliance with local financial regulations.

Practical Example: Building a Travel Agency Web App with Rapyd

To showcase how embedded finance works, we’ve built a travel booking web app that integrates Rapyd’s payment gateway using Python (Flask) and React.

🔗 GitHub Repo

Tech Stack

🚀 Backend: Python, Flask
💻 Frontend: React
💳 Payments: Rapyd API

Features

✅ Secure Payments – Accept cards, bank transfers, and digital wallets.
✅ Booking System – Users can book flights, hotels, and activities.
✅ API-Driven Architecture – The backend communicates with Rapyd’s payment APIs.

Quick Setup Guide

Clone the repo and run the app locally:

git clone https://github.com/your-repo/travel-agency-rapyd.git
cd travel-agency-rapyd
pip install -r requirements.txt
npm install && npm start

🚀 Run Flask Backend:

python app.py

💻 Start React Frontend:

npm start

Now, you can test payments directly in the app!

Conclusion

Embedded financial services are redefining Vertical SaaS—allowing businesses to own financial transactions and increase platform revenue. Developers play a key role in this transformation by leveraging financial APIs like Rapyd to integrate payments, lending, and banking into their SaaS applications.

Next Steps:

🔹 Explore the GitHub project and integrate Rapyd’s API into your own application.
🔹 Test the API calls and webhooks using the sandbox environment.
🔹 Think about how embedded finance could enhance your own SaaS product.

What’s your next embedded finance project? Let’s discuss in the comments! 🚀

DEV Community: Drew Harris

Boosting Authorization Rates: Partnering Strategies and Intelligent Retries

Understanding the Payment Authorization Funnel

Stages of an Online Payment

Declines and Visibility into the Funnel

Implementing Smart Retry Logic with MACs

Using AI to Predict and Optimize Authorization Outcomes

Use Case: Training Models on Transaction Data

How a Data-Driven Approach Boosts Success Rates

Partnering with a Unified Payments Platform

Sample Project: Payment Retry Orchestrator with MAC Logic

Conclusion

Blockchain Interoperability: Connecting Multiple Blockchain Networks for Payments

Why Fintech Applications Need Blockchain Interoperability

Simplifying Payment Verification with Rapyd

Implementing Blockchain Interoperability

Prerequisites

Cloning the Starter Project

Defining Smart Contracts for Cross-Chain Transaction Verification

CrossChainPayment contract

PaymentVerified contract

Defining Scripts to Deploy the Smart Contracts

Deploying the Smart Contracts to testnets

Defining the Relay Script

Testing Cross-chain Interactions

Conclusion

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

Core Payment Requirements in the Creator Economy

Royalty Payments

Affiliate Payouts

Subscription Management

Benefits of Using Rapyd APIs for Creator Payment Systems

Implementing a Creator Payment System with the Rapyd API

Prerequisites

Create a Rapyd Authentication File

Create an Rapyd API App

Royalty Payments

Affiliate Payouts

Managing Subscriptions

Run the Application

/royalty-payments

/affiliate-payout

/create-subscription

Conclusion

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

The Golden Nugget: APIs as Your Compliance Backbone

1. API Selection Criteria: Choosing Your Compliance Partner Wisely

2. Integration Patterns: Weaving Compliance into Your Workflow

Onboarding (KYC/KYB): The Asynchronous Dance

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

Post-Transaction Monitoring: The Background Watcher

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

4. Error Handling & Fallbacks: Building Resilient Systems

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

6. Testing Methodologies: Ensuring Compliance and Performance Under Pressure

Conclusion

🗞 Rapyd Developer Newsletter: May 2025 🛠 Build Real-Time Payments with Rapyd’s Latest Tools

💾 New API & Product Updates

⚡ Real-Time Payment Systems with Rapyd

🧩 Fintech APIs: Architecting the Future with AI

🖥 POS Terminals: Fintech Reinvented

🧾 Simplify Crypto Payouts with Beneficiary Tokenization

💼 Understand Wallet Balances with Merchant Reports

From Gig to Cash‑Out Build & Monetize Global Payouts

1. The Micro‑Payment Opportunity is Massive

2. API Monetization 101: Why Pay-Per-Use Wins for Gigs

3. Rapyd Disburse: Your Unified Gateway to Global Payouts

4. Architecture at a Glance

5. Hands‑On: Building Your Monetized Payout System

5.1 Clone & Install

5.2 Configure Environment Variables

5.5 Webhook Billing Flow

5.6 Admin Dashboard

6. Deploy & Go Live

7. Monetization Tweaks & Ideas

8. Security & Compliance Notes

9. Key Takeaways: Your Fast Track to Monetized Payouts

10. Ready to Monetize Your Gig Economy Platform?

Tokenization in Payments: The Future of Secure, Anonymous Transactions

Understanding Tokenization