--- title: "Creating a Wallet" source_url: https://docs.rapyd.net/en/creating-a-wallet-606308.html lang: en --- # 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. ## Roles and Responsibilities 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. > **Note:** > > - 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](https://docs.rapyd.net/en/create-wallet.md "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. ## Creating a Rapyd Wallet Workflow 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. ![create-wallet-payfac-flow-1.png](image/img-006da724e37c830989f6512156f1874e.png) 1. Submit a query using the [Initiate Merchant Query](https://docs.rapyd.net/en/initiate-merchant-query.md "Initiate Merchant Query") API. 2. Retrieve results via [Retrieve Query Results](https://docs.rapyd.net/en/retrieve-query-results.md "Retrieve Query Results") . 3. Evaluate the `match_type` and `registration_info` fields for fraud indicators. 4. Safeguard the `partner_merchant_reference` for 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. ![create-wallet-payfac-flow-2.png](image/img-38f4b607b40eb2dc4bd4a3e84cee6550.png) 1. Submit a query using the Create Wallet API including the required business information and `partner_merchant_reference` from the CNLS lookup. 2. Rapyd returns with a wallet and sends you a [webhook](https://docs.rapyd.net/en/webhooks.md "Webhooks"). 3. Safeguard the `merchant_ewallet` for 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_ewallet` associated 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_ewallet` as 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. ## How Creating a Rapyd Wallet Works ### Submerchant Screening You can use the Card Network Lookup service that Rapyd provides to verify your submerchant. The payment facilitator (PayFac) is responsible for submerchant screening. ### Initiate Merchant Query Request See [Initiate Merchant Query](https://docs.rapyd.net/en/initiate-merchant-query.md "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**: `string/^[\w\s\!\@\#\$\%\^\&\*\(\)\_\+\-\=\[\]\{\}\;\:\'\"\,\.\/\\\?]{0,60}$/` | | partner_query_reference | Unique ID of the query request, defined by the partner. **Length**: 0-60 **Regex**: `string/^[\w\s\!\@\#\$\%\^\&\*\(\)\_\+\-\=\[\]\{\}\;\:\'\"\,\.\/\\\?]{0,60}$/` | | 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" ] } } ``` ### Initiate Merchant Query Response - - 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" } } ``` ### Retrieve Query Results Request See [Retrieve Query Results](https://docs.rapyd.net/en/retrieve-query-results.md "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**: `string/^[\w\s\!\@\#\$\%\^\&\*\(\)\_\+\-\=\[\]\{\}\;\:\'\"\,\.\/\\\?]{0,60}$/` | - - Request - ``` // Request URL: GET https://sandboxapi.rapyd.net/v1/cnl/termination_query/12345678 // Message body absent ``` ### Retrieve Query Results Response - - 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" } } ] } } ``` ### Creating a Rapyd Wallet ### Create a Rapyd Wallet Request To create a Rapyd Wallet, you'll use [Create Wallet](https://docs.rapyd.net/en/create-wallet.md "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 | 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 `partner_query_reference` parameter used as the query request ID in the Card Network Lookup Service (CNLS). See [Retrieve Query Results](https://docs.rapyd.net/en/retrieve-query-results.md "Retrieve Query Results"). You must run the CNLS before creating a wallet for a merchant. If the `cnls_partner_query_reference` and `partner_query_reference` values do not match, ERROR_CREATE_WALLET_CNLS_PARTNER_QUERY_REFERENCE_MISMATCH is returned. | 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 { "first_name": "Four Star Professional Services", "last_name": "", "ewallet_reference_id": "e-0619", "metadata": { "merchant_defined": true }, "type": "company", "cnls_partner_query_reference": "abcd1234", "contact": { "phone_number": "+14155551234", "email": "johndoe@rapyd.net", "first_name": "John", "last_name": "Doe", "contact_type": "business", "address": { "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": "" }, "identification_type": "PA", "identification_number": "1234567890", "date_of_birth": "2000-11-22", "country": "US", "metadata": { "merchant_defined": true }, "business_details": { "statement_descriptor": "Four Star Pro Services", "website_url": "https://fourstarprofessionalservices.com", "mcc": "5812", "customer_service_phone_number": "+14155555555", "entity_type": "association", "name": "Four Star Professional Services", "registration_number": "4234567779", "industry_category": "company", "industry_sub_category": "home services", "address": { "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 } } } } } ``` ### Create Wallet Response - - 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": "Four Star Pro Services", "mcc": "5812", "website_url": "https://fourstarprofessionalservices.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](https://docs.rapyd.net/en/wallet-contact-365061.md "Wallet Contact") . - The ewallet id is **ewallet_16f5b11d7cd37c0ebb9242699d1db61d**.