Skip to main content

Documentation

Rapyd Payment Facilitator Integration Guide

Overview

As a licensed Payment Facilitator (PayFac), you can utilize Rapyd’s infrastructure to acquire card transactions on behalf of your sub-merchants for VISA, MasterCard & AMEX. This guide provides a comprehensive overview of the end-to-end process, outlining your responsibilities and the necessary APIs to register sub-merchants, process payments, and manage settlements, all while ensuring compliance with card scheme rules and regulatory requirements.

Important Notes

  • You, as a Payment Facilitator, are a registered customer of Rapyd.

  • You are responsible for entering into agreements with your sub-merchants, onboarding them, conducting KYB, monitoring and providing ongoing support related to the acquiring services, in accordance with your regulatory license. 

  • As the acquirer and the Scheme Principal Member, Rapyd provides you with access to the card networks to acquire sub-merchant transactions. You are responsible to comply with the underlying scheme rules.

1. Risk Checks for Sub-Merchants via VMSS & MATCH

As part of the due diligence process prior to onboarding any sub-merchant, you are required to conduct a screening using Rapyd’s Card Network Lookup Service (CNLS). This service performs a real-time query of two critical card network databases. 

  • VMSS (Visa Merchant Screening Service) 

  • MATCH (Mastercard Alert to Control High-risk Merchants)

MATCH and VMSS are databases of terminated merchants that contain information about accounts that have been closed by credit card processors around the world for high chargebacks or violations of card brand rules.

The results provided by the CNLS service are delivered to you exactly as received from the card brands. Rapyd does not alter these results or interfere with your decision on whether to proceed with onboarding the merchant.

Integration Flow:

  1. Submit a query using the Initiate Merchant Query method.

  2. Retrieve results via the Retrieve Query Results method.

  3. Evaluate the match_type and registration_info values for fraud indicators.

Important

Querying the CNLS is mandatory before creating a wallet for a sub-merchant. If the CNLS reference (partner_query_reference), which is the identifier of the sub-merchant in PayFac systems, is not included during wallet creation then the request will be rejected.

2. Manage Your Sub-merchants

As a PayFac, you are fully responsible for the onboarding, due diligence, and ongoing monitoring of your sub-merchants. Rapyd does not perform these tasks on your behalf. However, you are still required to create a sub-merchant wallet on the Rapyd platform to ensure their details are recorded under a unique identifier within our system.

The PayFac:

  • Acts as the licensed entity (PI/EMI) and holds full financial regulatory responsibility for the merchant, including KYB and AML obligations. The PayFac may only operate and onboard merchants in jurisdictions where it is appropriately licensed or authorized to do so.

  • Is responsible for creating a wallet for each sub-merchant using the Create Wallet method.

  • Must provide the required wallet parameters during creation, which include:

    • cnls_partner_query_reference: This reference is required and will be validated to confirm that a CNLS lookup was performed before onboarding the sub-merchant. If multiple wallets are being created for the same sub-merchant, then the same reference ID can be reused.

    • statement_descriptor: This is the text that appears on the cardholder's bank statement, helping them recognize the transaction. Card schemes require that the descriptor clearly identify the merchant to reduce charge-backs due to unrecognized transactions.

    • MCC. A four-digit code that classifies the type of business the sub-merchant operates. Accurate MCC assignment is crucial for compliance, interchange qualification, and risk assessment.

    • website_url. Provides a point of reference for cardholders to learn more about the merchant. Schemes mandate that the merchant's website is active, contains clear product/service descriptions, pricing, and contact information.

    • customer_service_phone_number. Offers cardholders a direct line to resolve issues or inquiries. A valid customer service number must be provided and displayed prominently on the merchant's website. This information can be included in transaction details if required.

    • business_details.address fields. The physical address of the sub-merchant is required to verify their location and ensure compliance. Accurate and complete address information is essential for merchant identification, risk assessment, transaction processing, and reporting. All address fields, except line_2 and line_3, must be completed during sub-merchant onboarding. If values for the optional fields are provided, then they will be used. Fields of this address object include:

      • business_details.address.city

      • business_details.address.country

      • business_details.address.line_1

      • business_details.address.line_2

      • business_details.address.line_3

      • business_details.address.name

      • business_details.address.phone_number

      • business_details.address.zip

Note

For a full list of the fields, see also the contents and samples in Create Wallet and Add Contact to Wallet.

Your sub-merchant wallets are logically nested under your primary Rapyd client wallet and are used to store sub-merchant data required by the card schemes. The payments you create reference the sub-merchant wallet, and you can view all this activity in the reconciliation report.

3. Payment Transactions

All card transactions (Visa, Mastercard, Amex) are processed through the Rapyd platform.

Use the Create Payment method to create a payment for your sub-merchant.

Each payment must include the sub-merchant’s Wallet ID value in the merchant_ewallet field. This ID links the payment to the correct sub-merchant. Rapyd uses the metadata stored in the wallet (e.g., the statement descriptor, address, MCC) to automatically populate the required details to comply with scheme requirements.

You can optionally send:

  • The Wallet ID value in the ewallet field. This way, you can route the transaction to a dedicated Client Wallet or Business Wallet if you prefer a more customized setup. If left blank, the default Client wallet is automatically selected. 

  • The statement descriptor value in the statement_descriptor field. This will override the data stored on the sub-merchant Wallet.

4. Settlements

In the standard Payment Facilitator flow, settlement is centralized to a Rapyd Client Wallet in order to simplify operations and reconciliation:

  • All funds from sub-merchant transactions are credited by default to your primary client wallet and settled accordingly.  

  • If an alternative Client Wallet ID is provided in the Create Payment request then the funds will be routed and settled accordingly.

  • The merchant_ewallet data field will not be used to determine the settlement flow.

  • This setup allows for consolidated reporting, reduced operational complexity, and unified control over cash flow.

As the Payment Facilitator, you are fully responsible for managing onward settlement to your sub-merchants based on your internal ledger and policies.

You will typically:

  • Receive a periodical settlement from Rapyd to your bank account.

  • Perform your own disbursements to sub-merchants using your internal system workflows.

5. Reporting for Payment Facilitators

You have access to comprehensive reporting files that allow you to:

  • Track transactions at the sub-merchant level.

  • Monitor fees and settlement activity.

  • Verify pricing accuracy, including details on underlying interchange and scheme fees.

Reconciliation files (reports) are uploaded to an SFTP server and can be consumed automatically. For more information on the format and the structure of these files, see Reports.

In this section: