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.

Note

For best practices, include the first_name, last_name, date_of_birth, country, address.name and address.line_1 fields in the contact object. These fields are required for other operations.

Parameters

Request Header Parameters

Request Body Parameters

- contact
- Describes details about the wallet contacts. Array of objects.
  address
  Address of this contact person. Required when the client issues a card to the contact. This can be an address object or the ID of an address object created with Create Address.
  canton
  Name of the canton administrative subdivision, as used in banking.
  city
  City portion of the address. Required for issuance of a card to the wallet contact.
  country
  The two-letter ISO 3166-1 ALPHA-2 code for the country.
  district
  Name of the district administrative subdivision, as used in banking.
  line_1
  Line 1 of the address, such as a building number and street name.
  line_2
  Line 2 of the address, such as a suite or apartment number, or the name of a named building.
  line_3
  Line 3 of the address.
  metadata
  A JSON object defined by the client. See Metadata.
  name
  The name of a contact person or an "in care of" person at this address. For a personal wallet contact type, alphabetic characters and spaces.
  phone_number
  Phone number associated with this specific address in E.164 format. Must be unique.
  state
  State or province portion of the address.
  zip
  Postal code portion of the address.
  contact_type
  Type of contact. One of the following:
  personal - An individual customer.
  business - A business customer.
  country
  The two-letter ISO 3166-1 ALPHA-2 code for the country.
  To determine the code for a country, see List Countries.
  date_of_birth
  Date of birth of the individual. Format: MM/DD/YYYY
  email
  Email address of the contact.
  first_name
  First name of the personal contact or primary person associated with the business contact. For a personal contact type, alphabetic characters and spaces.
  gender
  Gender of the personal contact or primary person associated with the business contact. One of the following values:
  male
  female
  other
  not_applicable
  house_type
  Description of the type of residency at the contact's residence. One of the following values:
  lease - A long-term lease.
  live_with_family - The contact lives with family.
  own - The contact owns the residence.
  owner - The contact is the owner of the residence.
  month_to_month - An informal agreement, renewable each month.
  housing_project - A room in a large residence facility, such as a residence hall or senior citizens' home.
  identification_number
  ID number as shown by the ID document.
  identification_type
  Type of the identification document associated with the contact.
  For types that are valid in the country, use List Official Identification Documents.
  last_name
  Family name of the personal contact or primary person associated with the business contact. For a personal contact type, alphabetic characters and spaces.
  Required for issuing a card to a personal contact.
  marital_status
  Marital status of the personal contact or primary person associated with the business contact. One of the following values:
  married
  single
  divorced
  widowed
  cohabiting
  not_applicable
  metadata
  A JSON object defined by the client. See Metadata.
  middle_name
  Middle name of the personal contact or primary person associated with the business contact.
  mothers_name
  Name of the mother of the personal contact or primary person associated with the business contact. Alphabetic characters and spaces.
  nationality
  The citizenship of the contact. Two-letter ISO 3166-1 ALPHA-2 code for the country. To determine the code for a country, see List Countries.
  phone_number
  Phone number of the contact in E.164 format.
  second_last_name
  Second last name of the personal contact or primary person associated with the business contact.
  send_notifications
  Determines whether Rapyd sends notifications to the contact. Default is false.
- 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.
- last_name
- Family name of the Rapyd Wallet owner.
- metadata
- A JSON object defined by the client. See Metadata.
- type
- Type of wallet:
  - company
  - person
  person

Response Parameters

- accounts
- An array of objects with the following fields:
  alias
  Alternate text description of the currency.
  balance
  Available funds in the account.
  currency
  Three-letter ISO 4217 code for the currency used in the balance field.
  id
  ID of the account. UUID.
  limit
  Reserved.
  limits
  Reserved.
  on_hold_balance
  Amount in the on-hold balance of the account.
  received_balance
  Amount of escrow funds in the account.
  reserve_balance
  Amount in the reserve balance of the account.
- category
- Indicates the type of client wallet. One of the following:
  - collect
  - disburse
  - card_authorization
  - general
- contacts
- Contains the following fields:
  - data - An array of contact objects. See Wallet Contact.
  - has_more - Boolean. Indicates whether there are more contacts than appear in the data array.
  - total_count - Number. The total number of contacts in the wallet.
  - url - String. URL to retrieve all contacts in the wallet. Use HTTP get.
- email
- Email address of the wallet owner. Deprecated. The email address belongs to the contact.
- wallet_operational_currency
- Reserved.
- ewallet_reference_id
- Wallet ID defined by the customer or end user. Must be unique.
- first_name
- First name of the wallet owner. For a person wallet type, alphabetic characters and spaces.
- id
- Unique identifier of the wallet object. String starting with ewallet_.
- last_name
- Family name of the wallet owner. For a person wallet type, alphabetic characters and spaces.
- metadata
- A JSON object defined by the client. See Metadata.
- phone_number
- Phone number of the wallet owner in E.164 format. Deprecated. The phone number belongs to the contact.
- status
- Status of the wallet. One of the following:
  - ACT - Active.
  - DIS - Disabled.
- type
- Type of wallet. One of the following:
  - company - Indicates a business wallet.
  - person - Indicates the wallet of an individual consumer.
  - client - Indicates a wallet for the Rapyd client. To create additional wallets of this type, contact Client Support.
- verification_status
- Result of the verification check. One of the following:
  - not verified - The contact has not been submitted for the Know Your Customer checks.
  - KYCd - The user has passed the Know Your Customer checks.

Code Samples

.NET

using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var address = new
                {
                    name = "John Doe",
                    line_1 = "123 Main Street",
                    line_2 = "",
                    line_3 = "",
                    city = "Anytown",
                    state = "NY",
                    country = "US",
                    zip = "12345",
                    metadata = new { },
                    canton = "",
                    district = ""
                };

                var metadata = new
                {
                    merchant_defined = true
                };

                var contact = new
                {
                    email = "johndoe@rapyd.net",
                    first_name = "John",
                    last_name = "Doe",
                    mothers_name = "Jane Smith",
                    contact_type = "personal",
                    address,
                    identification_type = "PA",
                    identification_number = "1234567890",
                    date_of_birth = "11/22/2000",
                    country = "US",
                    metadata,
                };

                var requestObj = new
                {
                    first_name = "John",
                    last_name = "Doe",
                    email = "",
                    ewallet_reference_id = "John-Doe-02152020",
                    metadata,
                    phone_number = "",
                    type = "person",
                    contact,
                    country = "US",
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/user", request);

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}

JavaScript

const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const body = {
      first_name: 'John',
      last_name: 'Doe',
      ewallet_reference_id: 'John-Doe-02152020',
      metadata: {
        merchant_defined: true
      },
      type: 'company',
      contact: {
        phone_number: '+14155551234',
        email: 'johndoe@rapyd.net',
        first_name: 'John',
        last_name: 'Doe',
        mothers_name: 'Jane Smith',
        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: { number: 2 },
          canton: '',
          district: ''
        },
        identification_type: 'PA',
        identification_number: '1234567890',
        date_of_birth: '11/22/2000',
        country: 'US',
        metadata: {
          merchant_defined: true
        },
        business_details: {
          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
            }
          }
        }
      }
    };
    const result = await makeRequest('POST', '/v1/user', body);

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}

PHP

<?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);
$body = [
    'first_name' => 'John',
    'last_name' => 'Doe',
    'email' => '',
    'ewallet_reference_id' => 'John-Doe-02152020',
    'metadata' => [
        'merchant_defined' => true
    ],
    'phone_number' => '',
    'type' => 'person',
    'contact' => [
        'phone_number' => '+14155551234',
        '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' => '+14155551234',
            'metadata' => [],
            'canton' => '',
            'district' => '',
        ],
        'identification_type' => 'PA',
        'identification_number' => '1234567890',
        'date_of_birth' => '11/22/2000',
        'country' => 'US',
        'metadata' => [
                'merchant_defined' => true
        ],
      ],
    ];

try {
    $object = make_request('post', '/v1/user', $body);
    var_dump($object);
} catch(Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

# Creating personal wallet
personal_wallet = {
    "first_name": "John",
    "last_name": "Doe",
    "email": "",
    "ewallet_reference_id": "John-Doe-02152020",
    "metadata": {
        "merchant_defined": True
    },
    "phone_number": "",
    "type": "person",
    "contact": {
        "phone_number": "+14155551234",
        "email": "johndoe1@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": "+14155551234",
            "metadata": {},
            "canton": "",
            "district": ""
        },
        "identification_type": "PA",
        "identification_number": "1234567890",
        "date_of_birth": "11/22/2000",
        "country": "US",
        "metadata": {
            "merchant_defined": True
        }
    }
}

personal_wallet_results = make_request(method='post', path='/v1/user', body=personal_wallet)
pprint(personal_wallet_results)

# Creating company ewallet
company_wallet = {
    "first_name": "Four Star Professional Services",
    "last_name": "",
    "ewallet_reference_id": "e-77641",
    "metadata": {
        "merchant_defined": True
    },
    "type": "company",
    "contact": {
        "phone_number": "+14155551234",
        "email": "johndoe1@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": "11/22/2000",
        "country": "US",
        "metadata": {
            "merchant_defined": True
        },
        "business_details": {
            "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
                }
            }
        }
    }
}

company_wallet_results = make_request(method='post', path='/v1/user', body=company_wallet)
pprint(company_wallet_results)

/v1/user

Person Wallet

curl -X post
https://sandboxapi.rapyd.net/v1/user
-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'
-d '{
    "first_name": "John",
    "last_name": "Doe",
    "ewallet_reference_id": "2023-01-29b",
    "metadata": {},
    "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",
            "metadata": {},
            "canton": "",
            "district": ""
        },
        "identification_type": "DL",
        "identification_number": "1234567890",
        "date_of_birth": "11/22/2000",
        "country": "IS",
        "nationality": "IS",
        "metadata": {
            "merchant_defined": true
        }
    }
}'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "2322ef1e-2181-4981-8bd3-df329c240785"
    },
    "data": {
        "phone_number": null,
        "email": null,
        "first_name": "John",
        "last_name": "Doe",
        "id": "ewallet_1d0a9c24781aeccca21f9e640d020d28",
        "status": "ACT",
        "accounts": [],
        "verification_status": "not verified",
        "type": "person",
        "metadata": {
            "merchant_defined": true
        },
        "ewallet_reference_id": "2021-10-28d",
        "category": null,
        "contacts": {
            "data": [
                {
                    "id": "cont_7883d252a75f525ae28d74d6c1da7167",
                    "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": "+14155551234",
                    "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": "US",
                    "nationality": "US",
                    "address": {
                        "id": "address_a1cd1ab9cd3cb7395152ef9e7ceed05f",
                        "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": 1635423334
                    },
                    "ewallet": "ewallet_1d0a9c24781aeccca21f9e640d020d28",
                    "created_at": 1635423334,
                    "metadata": {
                        "merchant_defined": true
                    },
                    "business_details": null,
                    "compliance_profile": 0,
                    "verification_status": "not verified",
                    "send_notifications": false,
                    "mothers_name": "Jane Smith"
                }
            ],
            "has_more": false,
            "total_count": 1,
            "url": "/v1/ewallets/ewallet_1d0a9c24781aeccca21f9e640d020d28/contacts"
        }
    }
}

Company Wallet

curl -X post
https://sandboxapi.rapyd.net/v1/user
-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'
-d '{
    "first_name": "Four Star Professional Services",
    "last_name": "",
    "ewallet_reference_id": "e-0619",
    "metadata": {
        "merchant_defined": true
    },
    "type": "company",
    "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": "11/22/2000",
        "country": "US",
        "metadata": {
            "merchant_defined": true
        },
        "business_details": {
            "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
                }
            }
        }
    }
}'

{
    "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
                    },
                    "compliance_profile": 0,
                    "verification_status": "not verified",
                    "send_notifications": false,
                    "mothers_name": ""
                }
            ],
            "has_more": false,
            "total_count": 1,
            "url": "/v1/ewallets/ewallet_16f5b11d7cd37c0ebb9242699d1db61d/contacts"
        },
        "wallet_operational_currency": null
    }
}{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "e3269410-8312-4907-b998-9260adf5091c"
    },
    "data": {
        "phone_number": null,
        "email": null,
        "first_name": "Four Star Professional Services",
        "last_name": "",
        "id": "ewallet_2e3c6e5be63ed17a115e6ee66f825a37",
        "status": "ACT",
        "accounts": [],
        "verification_status": "not verified",
        "type": "company",
        "metadata": {
            "merchant_defined": true
        },
        "ewallet_reference_id": "2021-10-28c",
        "category": null,
        "contacts": {
            "data": [
                {
                    "id": "cont_08adc02f6916282d389910348d285373",
                    "first_name": "Four Star Professional Services",
                    "last_name": "",
                    "middle_name": "",
                    "second_last_name": "",
                    "gender": "not_applicable",
                    "marital_status": "not_applicable",
                    "house_type": "",
                    "contact_type": "business",
                    "phone_number": "",
                    "email": "",
                    "identification_type": "",
                    "identification_number": "",
                    "issued_card_data": {
                        "preferred_name": "",
                        "transaction_permissions": "",
                        "role_in_company": ""
                    },
                    "date_of_birth": null,
                    "country": "",
                    "nationality": null,
                    "address": null,
                    "ewallet": "ewallet_2e3c6e5be63ed17a115e6ee66f825a37",
                    "created_at": 1635422882,
                    "metadata": {},
                    "business_details": {
                        "id": "busi_c80f3dae4ceb059a3c3c338cbfd057bc",
                        "name": "",
                        "registration_number": "",
                        "entity_type": "n/a",
                        "industry_category": "n/a",
                        "industry_sub_category": "n/a",
                        "address": null,
                        "created_at": 1635422882,
                        "annual_revenue": 0,
                        "establishment_date": null,
                        "legal_entity_type": null,
                        "cnae_code": null
                    },
                    "compliance_profile": 0,
                    "verification_status": "not verified",
                    "send_notifications": false,
                    "mothers_name": ""
                }
            ],
            "has_more": false,
            "total_count": 1,
            "url": "/v1/ewallets/ewallet_2e3c6e5be63ed17a115e6ee66f825a37/contacts"
        }
    }
}

In this section:

Documentation