Create Wallet
Create a Rapyd Wallet.
The following types of wallet are supported:
Person - Requires one personal contact.
Company - Requires one business contact. You can add personal contacts as required. See Add Contact to Wallet.
Client - Requires one business contact. Created by Rapyd Client Support.
See also Creating a Wallet.
Parent Wallet
The optional parent_ewallet parameter associates a person wallet with a company wallet.
Implementing a parent wallet enhances the onboarding process and helps fulfill compliance regulations.
Single parent: A person wallet can have only one parent wallet.
Default parent wallet: When a request does not specify a parent wallet, the client wallet is automatically assigned as the parent wallet.
Parent wallet type: You can only assign a company wallet as a parent wallet. A person wallet cannot be a parent wallet.
Payment Facilitator (PayFac) Wallet for a Sub-Merchant - Prerequisite
As a PayFac, before creating a wallet for a sub-merchant, you must first complete a Card Network Lookup Service (CNLS) query. The partner_query_reference value from the Retrieve Query Results CNLS response must be used as the cnls_partner_query_reference in the Create Wallet request body.
Note
For best practices, include the
first_name,last_name,date_of_birth,country,address.nameandaddress.line_1fields in thecontactobject. These fields are required for other operations.For information on the wallet and the wallet contact in an account funding transaction (AFT), see Creating an AFT Payment.
To change wallet parameter values, see Update Wallet.
This endpoint replaces the deprecated endpoint -
post /v1/userRapyd no longer supports the deprecated endpoint.
The code samples include successful requests (200) and bad requests (400).
For error messages that appear due to bad requests (400), see:
For information about unauthorized request (401) and other authentication errors, see Troubleshooting Authentication and Authorization Errors.
cnls_partner_query_reference
Payment Facilitator (PayFac) only. Required when a PayFac creates a wallet for a sub-merchant. Value of the
partner_query_referenceparameter 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 sub-merchant. If thecnls_partner_query_referenceandpartner_query_referencevalues do not match, ERROR_CREATE_WALLET_CNLS_PARTNER_QUERY_REFERENCE_MISMATCH is returned. See Wallet Errors.
contact
Describes details about the wallet contacts. Array of objects. For details about the fields in the 'contact' object, see Add Contact to Wallet.
ewallet_reference_id
Rapyd Wallet ID defined by the customer or end user. Must be unique.
first_name
First name of the Rapyd Wallet owner. For a person wallet type, alphabetic characters and spaces.
last_name
Family name of the Rapyd Wallet owner. For a person wallet type, alphabetic characters and spaces.
type
Type of wallet:
company - Indicates a business wallet.
person - Indicates the wallet of an individual consumer.
Note
To create additional wallets of the client type for a Rapyd client, contact Client Support.
person
/v1/ewallets
Company Wallet - Payment Facilitator (PayFac) Sub-Merchant
curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' --data-raw '{ "first_name": "Four Star Professional Services", "last_name": "", "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", "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" } } } }'{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "a8d5fd6d-7312-4c8c-ae4d-7887700f5acf" }, "data": { "phone_number": null, "email": null, "first_name": "Four Star Professional Services", "last_name": "", "id": "ewallet_b9cbf3f4691aab019efacc3e376548df", "status": "ACT", "accounts": [], "verification_status": "not verified", "type": "company", "metadata": {}, "ewallet_reference_id": null, "category": null, "contacts": { "data": [ { "id": "cont_232e04d58c8d9a0188ee649ceebe85c9", "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_d809ebc52486d68f5d77b4b91979c466", "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": 1753096440 }, "ewallet": "ewallet_b9cbf3f4691aab019efacc3e376548df", "created_at": 1753096440, "metadata": {}, "business_details": { "id": "busi_8a368f85fe2b3143d2a1dbbd3207bafe", "name": "Four Star Professional Services", "registration_number": "4234567779", "entity_type": "association", "industry_category": "company", "industry_sub_category": "home services", "address": { "id": "address_a0fda2f72ac2c55fa2eceae29519ac77", "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": {}, "canton": "", "district": "", "created_at": 1753096440 }, "created_at": 1753096440, "annual_revenue": 0, "establishment_date": null, "legal_entity_type": null, "cnae_code": null, "statement_descriptor": null, "mcc": null, "website_url": null, "customer_service_phone_number": null }, "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_b9cbf3f4691aab019efacc3e376548df/contacts" }, "parent_ewallet": null, "cnls_partner_query_reference": null } }
Company Wallet
curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' --data-raw '{ "first_name": "Four Star Professional Services", "last_name": "", "contact": { "first_name": "Jane", "last_name": "Doe", "contact_type": "business", "identification_type": "PA", "identification_number": "1233242424", "country": "US", "address": { "name": "Jane Doe", "line_1": "123 Lake Forest Drive" } }, "type": "company" }'{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "d42834dc-5820-405e-b0d7-542ba975c4cc" }, "data": { "phone_number": null, "email": null, "first_name": "Four Star Professional Services", "last_name": "", "id": "ewallet_82a37823e21dd1de710b927615027cf9", "status": "ACT", "accounts": [], "verification_status": "not verified", "type": "company", "metadata": {}, "ewallet_reference_id": null, "category": null, "contacts": { "data": [ { "id": "cont_2db1b7c16e78e78745ef040017657a19", "first_name": "Jane", "last_name": "Doe", "middle_name": "", "second_last_name": "", "gender": "not_applicable", "marital_status": "not_applicable", "house_type": "", "contact_type": "business", "phone_number": "", "email": "", "identification_type": "PA", "identification_number": "1233242424", "issued_card_data": { "preferred_name": "", "transaction_permissions": "", "role_in_company": "" }, "date_of_birth": null, "country": "US", "nationality": null, "address": { "id": "address_f5e8e3ddbf48566a852425f5384a0316", "name": "Jane Doe", "line_1": "123 Lake Forest Drive", "line_2": "", "line_3": "", "city": "", "state": "", "country": "", "zip": "", "phone_number": "", "metadata": {}, "canton": "", "district": "", "created_at": 1754574124 }, "ewallet": "ewallet_82a37823e21dd1de710b927615027cf9", "created_at": 1754574124, "metadata": {}, "business_details": { "id": "busi_8c3fae3acdb8d1b63d0e43462832e086", "name": "", "registration_number": "", "entity_type": "n/a", "industry_category": "n/a", "industry_sub_category": "n/a", "address": null, "created_at": 1754574124, "annual_revenue": 0, "establishment_date": null, "legal_entity_type": null, "cnae_code": null, "statement_descriptor": null, "mcc": null, "website_url": null, "customer_service_phone_number": null }, "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_82a37823e21dd1de710b927615027cf9/contacts" }, "parent_ewallet": null, "cnls_partner_query_reference": null } }
Person Wallet
curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' --data-raw '{ "first_name": "John", "last_name": "Doe", "ewallet_reference_id": "2025-07-21a", "type": "person", "contact": { "phone_number": "+3547826575", "email": "johndoe@rapyd.net", "first_name": "John", "last_name": "Doe", "mothers_name": "Jane Smith", "contact_type": "personal", "address": { "name": "John Doe", "line_1": "123 Main Street", "line_2": "", "line_3": "", "city": "Anytown", "state": "NY", "country": "US", "zip": "12345", "phone_number": "+14155551611", "canton": "", "district": "" }, "identification_type": "DL", "identification_number": "1234567890", "date_of_birth": "2000-11-22", "country": "IS", "nationality": "IS" } }'{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "d9519d52-3af9-4965-9edd-02963d6b1a78" }, "data": { "phone_number": null, "email": null, "first_name": "John", "last_name": "Doe", "id": "ewallet_1ab07083a434d85337668f6a4b22a39a", "status": "ACT", "accounts": [], "verification_status": "not verified", "type": "person", "metadata": {}, "ewallet_reference_id": "2025-07-21a", "category": null, "contacts": { "data": [ { "id": "cont_4098213b1a8c66a61bb9ceb505d26a54", "first_name": "John", "last_name": "Doe", "middle_name": "", "second_last_name": "", "gender": "not_applicable", "marital_status": "not_applicable", "house_type": "", "contact_type": "personal", "phone_number": "+3547826575", "email": "johndoe@rapyd.net", "identification_type": "DL", "identification_number": "1234567890", "issued_card_data": { "preferred_name": "", "transaction_permissions": "", "role_in_company": "" }, "date_of_birth": "2000-11-22", "country": "IS", "nationality": "IS", "address": { "id": "address_1c577026077d53ef1368121da9338c94", "name": "John Doe", "line_1": "123 Main Street", "line_2": "", "line_3": "", "city": "Anytown", "state": "NY", "country": "US", "zip": "12345", "phone_number": "+14155551611", "metadata": {}, "canton": "", "district": "", "created_at": 1753105164 }, "ewallet": "ewallet_1ab07083a434d85337668f6a4b22a39a", "created_at": 1753105164, "metadata": {}, "business_details": null, "compliance_profile": 0, "verification_status": "not verified", "send_notifications": false, "mothers_name": "Jane Smith", "contact_reference_id": null } ], "has_more": false, "total_count": 1, "url": "/v1/ewallets/ewallet_1ab07083a434d85337668f6a4b22a39a/contacts" }, "parent_ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861", "cnls_partner_query_reference": null } }
Person Wallet with Associated Parent Wallet
curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "first_name": "John", "last_name": "Doe", "parent_ewallet": "ewallet_b5320c566cc4aa01fe77440ad08693f7", "type": "person", "contact": { "first_name": "John", "last_name": "Doe", "country": "US", "address": { "name": "John Doe", "line_1": "123 Lake Forest Drive" } } }'{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "79c481b5-2f02-4c4e-a477-cc2562c84a77" }, "data": { "phone_number": null, "email": null, "first_name": "John", "last_name": "Doe", "id": "ewallet_2e68f9992c92118898b5e62bb085dcdc", "status": "ACT", "accounts": [], "verification_status": "not verified", "type": "person", "metadata": {}, "ewallet_reference_id": null, "category": null, "contacts": { "data": [ { "id": "cont_c129bf0d73896c78c1ddb177df67faef", "first_name": "John", "last_name": "Doe", "middle_name": "", "second_last_name": "", "gender": "not_applicable", "marital_status": "not_applicable", "house_type": "", "contact_type": "personal", "phone_number": "", "email": "", "identification_type": "", "identification_number": "", "issued_card_data": { "preferred_name": "", "transaction_permissions": "", "role_in_company": "" }, "date_of_birth": null, "country": "US", "nationality": null, "address": { "id": "address_77f9a572dd61b12bd339143beaa5c60d", "name": "John Doe", "line_1": "123 Lake Forest Drive", "line_2": "", "line_3": "", "city": "", "state": "", "country": "", "zip": "", "phone_number": "", "metadata": {}, "canton": "", "district": "", "created_at": 1754574716 }, "ewallet": "ewallet_2e68f9992c92118898b5e62bb085dcdc", "created_at": 1754574716, "metadata": {}, "business_details": null, "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_2e68f9992c92118898b5e62bb085dcdc/contacts" }, "parent_ewallet": "ewallet_b5320c566cc4aa01fe77440ad08693f7", "cnls_partner_query_reference": null } }
Create Wallet with Contact Reference ID
curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' --data-raw '{ "first_name": "John", "last_name": "Doe", "ewallet_reference_id": "2025-06-21d", "type": "person", "contact": { "contact_reference_id": "johndoe2025-07-21b", "phone_number": "+3547826575", "email": "johndoe@rapyd.net", "first_name": "John", "last_name": "Doe", "mothers_name": "Jane Smith", "contact_type": "personal", "address": { "name": "John Doe", "line_1": "123 Main Street", "line_2": "", "line_3": "", "city": "Anytown", "state": "NY", "country": "US", "zip": "12345", "phone_number": "+14155551611", "canton": "", "district": "" }, "identification_type": "DL", "identification_number": "1234567890", "date_of_birth": "2000-11-22", "country": "IS", "nationality": "IS" } }'{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "4823edca-b6ef-44c2-b0b9-7673a369d1d9" }, "data": { "phone_number": null, "email": null, "first_name": "John", "last_name": "Doe", "id": "ewallet_c0a6549983b384e5b8b323a0abb8cff1", "status": "ACT", "accounts": [], "verification_status": "not verified", "type": "person", "metadata": {}, "ewallet_reference_id": "2025-06-21d", "category": null, "contacts": { "data": [ { "id": "cont_5db48beb9dabdc3f1614de0eaf316d3d", "first_name": "John", "last_name": "Doe", "middle_name": "", "second_last_name": "", "gender": "not_applicable", "marital_status": "not_applicable", "house_type": "", "contact_type": "personal", "phone_number": "+3547826575", "email": "johndoe@rapyd.net", "identification_type": "DL", "identification_number": "1234567890", "issued_card_data": { "preferred_name": "", "transaction_permissions": "", "role_in_company": "" }, "date_of_birth": "2000-11-22", "country": "IS", "nationality": "IS", "address": { "id": "address_0ccd3c0541fd70bcf414a953745ea78d", "name": "John Doe", "line_1": "123 Main Street", "line_2": "", "line_3": "", "city": "Anytown", "state": "NY", "country": "US", "zip": "12345", "phone_number": "+14155551611", "metadata": {}, "canton": "", "district": "", "created_at": 1753105571 }, "ewallet": "ewallet_c0a6549983b384e5b8b323a0abb8cff1", "created_at": 1753105571, "metadata": {}, "business_details": null, "compliance_profile": 0, "verification_status": "not verified", "send_notifications": false, "mothers_name": "Jane Smith", "contact_reference_id": "johndoe2025-07-21b" } ], "has_more": false, "total_count": 1, "url": "/v1/ewallets/ewallet_c0a6549983b384e5b8b323a0abb8cff1/contacts" }, "parent_ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861", "cnls_partner_query_reference": null } }
Bad Request - Invalid Statement Descriptor Length
curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "first_name": "Four Star Professional Services", "last_name": "", "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", "canton": "", "district": "" }, "identification_type": "PA", "identification_number": "1234567890", "date_of_birth": "2000-11-22", "country": "US", "business_details": { "statement_descriptor": "Four Star Professional 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" } } } }'{ "status": { "error_code": "INVALID_FIELDS - [BUSINESS_DETAILS.STATEMENT_DESCRIPTOR]", "status": "ERROR", "message": "The request attempted an operation, but one or more of the fields did not have a valid value. The request was rejected. Corrective action: Use valid values. The names of the affected fields appear at the end of the error code. See the API Reference for details.", "response_code": "INVALID_FIELDS - [BUSINESS_DETAILS.STATEMENT_DESCRIPTOR]", "operation_id": "a636f9d9-d014-4481-be27-e59842a12ad3" } }
Bad Request - Reference ID Exists
curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' --data-raw '{ "first_name": "John", "last_name": "Doe", "ewallet_reference_id": "2025-11-12", "type": "person", "contact": { "phone_number": "+15555555555", "email": "johndoe@rapyd.net", "first_name": "John", "last_name": "Doe", "mothers_name": "Jane Smith", "contact_type": "personal", "address": { "name": "John Doe", "line_1": "123 Main Street", "line_2": "", "line_3": "", "city": "Anytown", "state": "NY", "country": "US", "zip": "12345", "phone_number": "+14155551611", "metadata": {}, "canton": "", "district": "" }, "identification_type": "DL", "identification_number": "1234567890", "date_of_birth": "2000-11-22", "country": "IS", "nationality": "IS", "metadata": { "merchant_defined": true } } }'{ "status": { "error_code": "ERROR_CREATE_USER_EWALLET_REFERENCE_ID_ALREADY_EXISTS", "status": "ERROR", "message": "The request tried to create a wallet, but the reference ID was already in use. The request was rejected. Corrective action: For 'ewallet_reference_id', enter a unique string.", "response_code": "ERROR_CREATE_USER_EWALLET_REFERENCE_ID_ALREADY_EXISTS", "operation_id": "0f043021-4b19-4260-9303-c761210b5fa1" } }