Creating a Wallet
Build a powerful wallet architecture for PayFacs.
As a licensed Payment Facilitator (PayFac), you can leverage Rapyd’s infrastructure to acquire Visa and Mastercard transactions on behalf of your sub-merchants. This guide walks you through the full flow, responsibilities, and APIs needed to onboard sub-merchants, process transactions, and manage settlements while maintaining compliance with card schemes and regulatory standards.
Sub-merchants are onboarded and screened by the PayFac, not by Rapyd.
You are the customer of record to Rapyd.
Sub-merchants are not direct customers of Rapyd; they are managed by you.
You are responsible for KYB, onboarding, and ongoing monitoring processes of the sub-merchants based on your license.
Rapyd is the underlying Scheme Principal Member with Visa and Mastercard. As such, Rapyd holds the acquiring license and provides Payment Facilitators (PayFacs) with the ability to operate under this license to process card transactions.
The PayFac
The PayFac is the licensed party (PI/EMI) and holds full financial regulatory responsibility of the merchant (KYB, AML).
The PayFac creates a wallet for each merchant using the Create Wallet API.
The wallets for your submerchants are linked under your main Rapyd client wallet and used to associate all transactional data for the submerchants.
In order to become a Rapyd Partner, a Payment Facilitator must be onboarded with Rapyd, including the KYB process, and then receive a client wallet. The PayFac can then evaluate a submerchant via the Card Network Lookup Service before onboarding them.
Step 1: Merchant Screening (Card Network Lookup Service)
Before onboarding a sub-merchant, you must screen them via Rapyd’s Card Network Lookup Service to ensure they’re not listed in termination databases like:
VMSS (Visa Merchant Screening Service)
MATCH (Mastercard Alert to Control High-risk Merchants)
You must run and pass CNLS before creating a wallet for a sub-merchant. Failing to include the partner_merchant_reference from the CNLS lookup in wallet creation will result in a rejection.
Submit a query using the Initiate Merchant Query API.
Retrieve results via Retrieve Query Results .
Evaluate the
match_typeandregistration_infofields for fraud indicators.Safeguard the
partner_merchant_referencefor use in wallet creation.
Step 2: Creating a Wallet
You must create a wallet for each of your sub-merchants and submit the required information for later payment creation.
Submit a query using the Create Wallet API including the required business information and
partner_merchant_referencefrom the CNLS lookup.Rapyd returns with a wallet and sends you a webhook.
Safeguard the
merchant_ewalletfor use in creating a payment.
Step 3: Payment Transactions
All card transactions (Visa, Mastercard, Amex) are processed through Rapyd APIs.
Each transaction:
Must include the
merchant_ewalletassociated with the sub-merchant to map the correct submerchant metadata, which is stored under each subwallet, ensuring scheme compliance.Use the Create Payment API and pass the
merchant_ewalletas a reference.
Payouts and Settlements
While each transaction is linked to a subwallet, the settlement of funds is centralized:
All balances are credited to your client wallet, not individual subwallets.
This simplifies cash flow and reconciliation from Rapyd to you.
You are responsible for onward settlement to sub-merchants based on your internal accounting.
You can:
Choose a daily settlement from the Rapyd account to your bank account.
Disburse directly to your submerchants using Rapyd’s Payout API to direct payments to sub-merchants via bank transfers or card payout options.
You can use the Card Network Lookup service that Rapyd provides to verify your submerchant. The payment facilitator (PayFac) is responsible for submerchant screening.
See Initiate Merchant Query for more information.
Description of Parameters
Body Parameter | Description |
|---|---|
partner_merchant_reference | ID of the merchant, defined by the partner. Length: 0-60 Regex: |
partner_query_reference | Unique ID of the query request, defined by the partner. Length: 0-60 Regex: |
queried_merchant | Information about the merchant who is the subject of the query. |
search_criteria | Specifies search criteria for the query. |
Request
// Request URL: POST https://sandboxapi.rapyd.net/v1/cnl/termination_query { "partner_merchant_reference": "ABCDEFGH", "partner_query_reference": "12345678", "search_criteria": { "search_area": "global" }, "queried_merchant": { "legal_name": "Four Star Market, Ltd.", "dba_name": "Four Star Market", "address": { "address_line_1": "123 Boulevard St Germain", "address_line_2": "", "city": "Paris", "country": "FR", "postal_code": "12345" }, "phone_numbers": [ "+1/555 555-5555" ], "business_category": "Merchant", "principals": [{ "first_name": "John", "middle_initial": "A", "last_name": "Doe", "email": "john.doe@fourstarmarket.net", "address": { "address_line_1": "123 Rue De Rivoli", "address_line_2": "", "postal_code": "12345", "city": "Paris", "country": "FR" }, "phone_number": "+1/555 555-1234" } ], "is_ecommerce": false, "email": "service@fourstarmarket.com", "url": [ "https://fourstarmarket.com" ] } }
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "4998cec5-72ac-46d7-b3bd-65bd631a4e78" }, "data": { "status": "IN_PROGRESS", "operation_id": "4998cec5-72ac-46d7-b3bd-65bd631a4e78", "partner_query_reference": "12345678", "partner_merchant_reference": "ABCDEFGH" } }
See Retrieve Query Results for more information.
Description of Parameters
Body Parameter | Description |
|---|---|
partner_query_reference | Unique ID of the query request, defined by the partner. Length: 0-60 Regex: |
Request
// Request URL: GET https://sandboxapi.rapyd.net/v1/cnl/termination_query/12345678 // Message body absent
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "c8dff275-ff01-4382-aeb9-f0653c8b2972" }, "data": { "match_stats": { "registered_match_count": 2, "query_match_count": 0 }, "query_info": { "partner_merchant_reference": "ABCDEFGH", "partner_query_reference": "12345678", "queried_merchant": { "legal_name": "Four Star Market, Ltd.", "dba_name": "Four Star Market", "address": { "address_line_1": "123 Boulevard St Germain", "address_line_2": "", "city": "Paris", "country": "FR", "postal_code": "12345" }, "phone_numbers": [ "+1/555 555-5555" ], "business_category": "Merchant", "principals": [ { "first_name": "John", "middle_initial": "A", "last_name": "Doe", "email": "john.doe@fourstarmarket.net", "address": { "address_line_1": "123 Rue De Rivoli", "address_line_2": "", "postal_code": "12345", "city": "Paris", "country": "FR" }, "phone_number": "+1/555 555-1234" } ], "is_ecommerce": false, "email": "service@fourstarmarket.com", "mcc": ["1234"], "url": [ "https://fourstarmarket.com" ] }, "search_criteria": { "search_area": "global" }, "query_status": "PROCESSED", "query_created_at": 1714999806182, "events_status": { "VMSS": "PROCESSED", "MATCH": "PROCESSED" } }, "matches": [ { "card_network": "VISA", "match_type": "registered match", "exact_match": [ "merchant.address.city", "merchant.address.postal_code", "merchant.address.country" ], "partial_match": [ "merchant.address.address_line_1" ], "matched_merchant": { "business_category": "", "legal_name": "Snap Photo Inc", "dba_name": "Snap Photo", "address": { "country": "FR", "city": "Paris", "address_line_1": "123 BOULEVARD ST GERMAIN", "address_line_2": "", "postal_code": "12345" }, "phone_numbers": [ "+1/555 555-5111" ], "email": "", "is_ecommerce": false, "mcc": "3000", "url": "" }, "registration_info": { "registered_by_acquirer_id": "40018064", "registered_by_acquirer_region": "", "registered_by_acquirer_name": "", "contract_end_date": "2022-05-15", "contract_start_date": "2022-04-15", "primary_registration_reason": "28-Fraud Conviction" } }, { "card_network": "MASTERCARD", "match_type": "registered match", "exact_match": [ "merchant.address" ], "partial_match": [], "matched_merchant": { "legal_name": "THE BAIT SHOP", "dba_name": "BAIT R US", "address": { "address_line_1": "123 BOULEVARD ST GERMAIN", "postal_code": "12345", "city": "Paris", "country": "FR" }, "phone_numbers": [ "+1/555 555-5222", "+1/555 555-5333" ], "business_category": "", "principals": [ { "first_name": "DAVID", "middle_initial": "", "last_name": "SMITH" } ], "email": "", "mcc": [], "url": [ null ] }, "registration_info": { "registered_by_acquirer_id": "1998", "registered_by_acquirer_region": "", "registered_by_acquirer_name": "", "contract_end_date": "2024-04-10", "contract_start_date": "", "primary_registration_reason": "13-Illegal Transactions" } } ] } }
To create a Rapyd Wallet, you'll use Create Wallet with the following parameters:
Description of Parameters
Body Parameter | Description | Required |
|---|---|---|
contact | Describes details about the wallet contacts. Array of objects. | Yes |
Email address of the wallet owner. | No | |
ewallet_reference_id | Rapyd Wallet ID defined by the customer or end user. Must be unique. | No |
first_name | First name of the Rapyd Wallet owner. | No |
last_name | Family name of the Rapyd Wallet owner. | No |
metadata | A JSON object defined by the client. | No |
type | Type of wallet: company or person. Default is person. | Yes |
cnls_partner_query_reference | Rapyd Platform only. Required when a PayFac partner creates a Rapyd Platform wallet for a merchant. Value of the | Yes |
statement_descriptor | Submerchant details Length: 22 characters | Yes |
business_details.address.zip | Postal Code/ZIP Code of the legal entity | Yes |
business_details.address.city | City of the business | Yes |
business_details.address.country | Country of the business | Yes |
mcc | Industry in which the business operates | Yes |
business_details.address.line1 | Street name and number of the business | Yes |
business_details.adress.line2 | Additional address details of the business | Yes |
business_details.address.phone_number | Phone number of the Authorized Representative | Yes |
website_url | Business website URL | Yes |
customer_service_phone_number | Customer service phone number | Yes |
Request
// Request URL: POST https://sandboxapi.rapyd.net/v1/ewallets { "type": "company", "cnls_partner_query_reference": "abcd1234", "contact": { "contact_type": "business", "address": { "line_1": "123 Main Street", "line_2": "", "city": "Anytown", "state": "NY", "country": "US", "zip": "12345", "phone_number": "+14155551234", }, "country": "US", "business_details": { "statement_descriptor": "Acme*Apex", "website_url": "https://acme.com ", "mcc": "5812", "customer_service_phone_number": "+14155555555", "name": "Four Star Professional Services", "address": { "line_1": "1234 Main Street", "line_2": "Suite 1200", "city": "Anytown", "state": "NY", "country": "US", "zip": "10101", "phone_number": "14155557779", } } } }
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "28671f60-49c4-4989-a1ab-0b89dbf1e002" }, "data": { "phone_number": null, "email": null, "first_name": "Four Star Professional Services", "last_name": "", "id": "ewallet_16f5b11d7cd37c0ebb9242699d1db61d", "status": "ACT", "accounts": [], "verification_status": "not verified", "type": "company", "metadata": { "merchant_defined": true }, "ewallet_reference_id": "e-0619", "category": null, "contacts": { "data": [ { "id": "cont_de961371a321e0ed782c521e41def4e0", "first_name": "John", "last_name": "Doe", "middle_name": "", "second_last_name": "", "gender": "not_applicable", "marital_status": "not_applicable", "house_type": "", "contact_type": "business", "phone_number": "+14155551234", "email": "johndoe@rapyd.net", "identification_type": "PA", "identification_number": "1234567890", "issued_card_data": { "preferred_name": "", "transaction_permissions": "", "role_in_company": "" }, "date_of_birth": "2000-11-22", "country": "US", "nationality": null, "address": { "id": "address_f39ec1393ddd85022c9cd430b996f59c", "name": "John Doe", "line_1": "123 Main Street", "line_2": "", "line_3": "", "city": "Anytown", "state": "NY", "country": "US", "zip": "12345", "phone_number": "+14155551234", "metadata": {}, "canton": "", "district": "", "created_at": 1687158709 }, "ewallet": "ewallet_16f5b11d7cd37c0ebb9242699d1db61d", "created_at": 1687158709, "metadata": { "merchant_defined": true }, "business_details": { "id": "busi_d49d261b771642ecf7209d8401f741b6", "name": "Four Star Professional Services", "registration_number": "4234567779", "entity_type": "association", "industry_category": "company", "industry_sub_category": "home services", "address": { "id": "address_5b6d9f0148e34ba084d158fe88af05ea", "name": "John Doe", "line_1": "1234 Main Street", "line_2": "Suite 1200", "line_3": "", "city": "Anytown", "state": "NY", "country": "US", "zip": "10101", "phone_number": "14155557779", "metadata": { "merchant_defined": true }, "canton": "", "district": "", "created_at": 1687158709 }, "created_at": 1687158709, "annual_revenue": 0, "establishment_date": null, "legal_entity_type": null, "cnae_code": null, "statement_descriptor": "Acme*Apex", "mcc": "5812", "website_url": "https://acme.com ", "customer_service_phone_number": "+14155555555" }, "compliance_profile": 0, "verification_status": "not verified", "send_notifications": false, "mothers_name": "", "contact_reference_id": null } ], "has_more": false, "total_count": 1, "url": "/v1/ewallets/ewallet_16f5b11d7cd37c0ebb9242699d1db61d/contacts" }, "parent_ewallet": null, "cnls_partner_query_reference": "abcd1234" } }
The data section of this request shows the ewallet that was created.
The contact object id is cont_de961371a321e0ed782c521e41def4e0. The fields are described under Wallet Contact Object .
The ewallet id is ewallet_16f5b11d7cd37c0ebb9242699d1db61d.