Skip to main content

Documentation

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.

create-wallet-payfac-flow-1.png
  1. Submit a query using the Initiate Merchant Query API.

  2. Retrieve results via 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
  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.

  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.

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: 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"
            ]
            }
        }
    • 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: string/^[\w\s\!\@\#\$\%\^\&\*\(\)\_\+\-\=\[\]\{\}\;\:\'\"\,\.\/\\\?]{0,60}$/

    • 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

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. 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
        
        {  
            "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.