Update Wallet Contact

Update a contact for a Rapyd Wallet.

Note

The following body parameters can only be updated if they previously had an empty value.
This limitation does not apply to a Payment Facilitator (PayFac).
- country
- date_of_birth
- first_name
- last_name
- identification_number
- identification_type
- nationality
The code samples include successful requests (200), bad requests (400), and an unauthorized request (401). For all error messages that appear due to bad requests, see Wallet Contact Errors, Wallet Errors, and General Errors.

Parameters

Request Path Parameters

- contact
- ID of the contact. String starting with cont_.
- wallet
- ID of the wallet associated with the contact. String starting with ewallet_.

Request Header Parameters

Request Body Parameters

Note

The following fields can be updated only if they previously had an empty value.

This limitation does not apply to a Payment Facilitator (PayFac).

· country
· date_of_birth
· first_name
· identification_number
· identification_type
· last_name
· nationality

The following business_details fields can be updated only by a PayFac:

· customer_service_phone_number
· mcc
· statement_descriptor
· website_url

- 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. Required for creating a Visa card payment that requires 3DS.
  country
  The two-letter ISO 3166-1 ALPHA-2 code for the country.
  Required for creating a Visa card payment that requires 3DS.
  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.
  Required for creating a Visa card payment that requires 3DS.
  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.
  Required for creating a Visa card payment that requires 3DS.
  phone_number
  Phone number associated with this specific address in E.164 format. Must be unique.
  Required for creating a Visa card payment that requires 3DS.
  state
  State or province portion of the address.
  Required for creating a Visa card payment that requires 3DS.
  zip
  Postal code portion of the address.
  Required for creating a Visa card payment that requires 3DS.
- business_details
- Describes additional information for business entities. Required when type is company.
  address
  Principal address of the business. Values for name and line_1 are required. See Create Address.
  Note
  Payment Facilitator (PayFac) only. The following additional values are required when a PayFac creates a wallet for a sub-merchant:
  city
  country
  line_2
  phone_number
  zip
  annual_revenue
  Annual revenue of the business in US dollars. Maximum value: 100000000000000. Decimal.
  cnae_code
  Business activity code of the business, according to the Classificação Nacional de Atividades Econômicas of Brazil. Alphanumeric string. Maximum 7 characters.
  customer_service_phone_number
  Payment Facilitator (PayFac) only. Required when a PayFac creates a wallet for a sub-merchant. Phone number for contacting the customer support service of the sub-merchant business, in E.164 format.
  entity_type
  Type of business entity. One of the following:
  sole_prop - Sole proprietorship.
  partnership - Partnership.
  company - Company.
  government - Government agency.
  charity - Charity.
  NPO - Non-profit organization.
  association - Unincorporated business association.
  trust - Trust.
  establishment_date
  Date that the business was established. Format: YYYY-MM-DD.
  industry_category
  Name of the industry that this business belongs to. Alphanumeric string with no special characters.
  industry_sub_category
  Subcategory of the industry that this business belongs to.
  legal_entity_type
  Type of legal entity. Alphanumeric string.
  mcc
  Payment Facilitator (PayFac) only. Required when a PayFac creates a wallet for a sub-merchant. Four-digit merchant category code (MCC) of the sub-merchant business, as defined in ISO 18245.
  name
  Business name.
  registration_number
  Registration number.
  statement_descriptor
  Payment Facilitator (PayFac) only. Required when a PayFac creates a wallet for a sub-merchant. The sub-merchant name or business name. Maximum: 22 characters. If the maximum is exceeded, the INVALID_FIELDS error is returned. See General Errors.
  website_url
  Payment Facilitator (PayFac) only. Required when a PayFac creates a wallet for a sub-merchant. URL of the sub-merchant business website.
- contact_reference_id
- ID of a wallet contact, defined by the customer or end user. String. Must be unique and cannot start with cont_.
- country
- The two-letter ISO 3166-1 ALPHA-2 code for the country.
  To determine the code for a country, see List Countries. A wallet must contain a contact with a valid country value.
- date_of_birth
- Date of birth of the individual. One of the following formats:
  - MM/DD/YYYY
  - YYYY-MM-DD
- 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.

Response Parameters

- 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. For more information about the fields of the 'address' object, see Create Address.
- business_details
- Describes additional information for business entities. Required when type is company.
  address
  Principal address of the business. See Create Address.
  annual_revenue
  Annual revenue of the business in US dollars. Maximum value: 100000000000000. Decimal.
  cnae_code
  Business activity code of the business, according to the Classificação Nacional de Atividades Econômicas of Brazil. Alphanumeric string. Maximum 7 characters.
  created_at
  Time of creation of the business_details object, in Unix time.
  customer_service_phone_number
  Phone number for contacting the customer support service of the sub-merchant business, in E.164 format. Relevant to Payment Facilitator (PayFac).
  entity_type
  Type of business entity. One of the following:
  sole_prop - Sole proprietorship.
  partnership - Partnership.
  company - Company.
  government - Government agency.
  charity - Charity.
  NPO - Non-profit organization.
  association - Unincorporated business association.
  trust - Trust.
  establishment_date
  Date that the business was established. Format: YYYY-MM-DD.
  id
  ID of the business_details object. String starting with busi_.
  industry_category
  Name of the industry that this business belongs to. Alphanumeric string with no special characters.
  industry_sub_category
  Subcategory of the industry that this business belongs to.
  legal_entity_type
  Type of legal entity. Alphanumeric string.
  mcc
  Four-digit merchant category code (MCC) of the sub-merchant business, as defined in ISO 18245. Relevant to Payment Facilitator (PayFac).
  name
  Business name.
  registration_number
  Registration number.
  statement_descriptor
  The sub-merchant name or business name.. Relevant to Payment Facilitator (PayFac).
  website_url
  URL of the sub-merchant business website. Relevant to Payment Facilitator (PayFac).
- compliance_profile
- Indicates the degree to which this contact can use the wallet. One of the following:
  - 1 - All transactions are allowed.
  - 0 - The wallet is limited, and the contact must complete the identity verification process.
  - -1 - The wallet is restricted and cannot be used for any transactions.
- contact_reference_id
- ID of a wallet contact, defined by the customer or end user. Must be unique. String. Cannot start with cont_.
- 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.
- created_at
- Time of creation of the contact object, in Unix time.
- date_of_birth
- Date of birth of the individual. Format: YYYY-MM-DD
- email
- Email address of the contact.
- ewallet
- ID of the Rapyd Wallet that this contact is associated with. String starting with ewallet_.
- 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.
- id
- ID of the contact object. String starting with cont_.
- 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.
- issued_card_data
- Describes additional information about the business contact for a company wallet.
  preferred_name
  The name of the contact person.
  transaction_permissions
  Indicates permissions for issuing transactions. Possible values:
  allowed
  not_allowed
  role_in_company
  The role of the named person. One of the following values:
  owner - Sole proprietor or partner.
  agent - Authorized agent or attorney in fact.
  employee - Authorized employee.
- 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.
- 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
            {
                string wallet = "ewallet_053d64c44834e1d3057ecb68a34c6b6c";
                string contact = "cont_f2b7f98b019af17df892dcc92abc3cc2";

                var metadata = new
                {
                    merchant_defined = "updated"
                };

                var requestObj = new
                {
                    phone_number = "+14155551237",
                    metadata,
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/ewallets/{wallet}/contacts/{contact}", 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 = {
      phone_number: '+14155551237',
      metadata: {
        merchant_defined: "updated"
      }
    };
    const result = await makeRequest(
      'POST',
      '/v1/ewallets/ewallet_053d64c44834e1d3057ecb68a34c6b6c/contacts/cont_f2b7f98b019af17df892dcc92abc3cc2',
      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 = [
    'phone_number' => '+14155551237',
    'metadata' => [
        'merchant_defined' => "updated"
    ]
  ];

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

Python

from pprint import pprint

from utilities import make_request

contact_details = {
    "phone_number": "+14155551237",
    "metadata": {
        "merchant_defined": "updated"
    }
}

results = make_request(method='post',
                       path=f'/v1/ewallets/ewallet_053d64c44834e1d3057ecb68a34c6b6c/contacts/cont_f2b7f98b019af17df892dcc92abc3cc2',
                       body=contact_details)
pprint(results)

/v1/ewallets/:wallet/contacts/:contact

Update PayFac Fields

curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets/ewallet_b355f1e8657f2a02ae38d060c9512dd6/contacts/cont_964aa848bf107c2ebe819fd8ce1a85a3' \
-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 '{
    "business_details": {
        "website_url": "https://updatedurl.com",
        "statement_descriptor": "updatewalletcontact",
        "mcc": "124",
        "customer_service_phone_number": "+14155551212",
        "address": {
            "zip": "54321",
            "city": "Anytown",
            "country": "US",
            "line_1": "789 Main Street",
            "line_2": "Apt 4E",
            "phone_number": "+14155555555",
            "name": "John Doe"
        }
    }
}'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "8af16a9f-a5de-4ed0-b7b6-1f267fe58209"
    },
    "data": {
        "id": "cont_18c0d881a3d0d2e9e54d4664c6b0022d",
        "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": "john.doe.162417@example.com",
        "identification_type": "",
        "identification_number": "",
        "issued_card_data": {
            "preferred_name": "",
            "transaction_permissions": "",
            "role_in_company": ""
        },
        "date_of_birth": null,
        "country": "US",
        "nationality": null,
        "address": null,
        "ewallet": "ewallet_b5320c566cc4aa01fe77440ad08693f7",
        "created_at": 1753881858,
        "metadata": {},
        "business_details": {
            "id": "busi_aba4330005786f053d25c46168d21fc4",
            "name": "",
            "registration_number": "",
            "entity_type": "n/a",
            "industry_category": "n/a",
            "industry_sub_category": "n/a",
            "address": {
                "id": "address_3c15646a8e2011f884c92eb416f52a02",
                "name": "John Doe",
                "line_1": "789 Main Street",
                "line_2": "Apt 4E",
                "line_3": "",
                "city": "Anytown",
                "state": "",
                "country": "US",
                "zip": "54321",
                "phone_number": "+14155555555",
                "metadata": {},
                "canton": "",
                "district": "",
                "created_at": 1755781052
            },
            "created_at": 1753881858,
            "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
    }
}

Update Personal Contact in Company Wallet

curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets/ewallet_b5320c566cc4aa01fe77440ad08693f7/contacts/cont_6b37bac42846c7046bdb9e24b89a5d05' \
-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 '{
    "phone_number": "+14155551997",
    "metadata": {
        "merchant_defined": "updated"
    }
}'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "e1bfc929-1860-47f3-a530-e7dc9276d5d3"
    },
    "data": {
        "id": "cont_6b37bac42846c7046bdb9e24b89a5d05",
        "first_name": "Jane",
        "last_name": "Doe",
        "middle_name": "",
        "second_last_name": "",
        "gender": "not_applicable",
        "marital_status": "not_applicable",
        "house_type": "",
        "contact_type": "personal",
        "phone_number": "+14155551997",
        "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_2c98c788eafe3a5a6b7541431e0ced5e",
            "name": "Jane Doe",
            "line_1": "123 Lake Forest Drive",
            "line_2": "",
            "line_3": "",
            "city": "Anytown",
            "state": "NY",
            "country": "",
            "zip": "12345",
            "phone_number": "+14155551234",
            "metadata": {
                "merchant_defined": true
            },
            "canton": "",
            "district": "",
            "created_at": 1754572956
        },
        "ewallet": "ewallet_b5320c566cc4aa01fe77440ad08693f7",
        "created_at": 1754572956,
        "metadata": {
            "merchant_defined": "updated"
        },
        "business_details": null,
        "compliance_profile": 0,
        "verification_status": "not verified",
        "send_notifications": false,
        "mothers_name": "",
        "contact_reference_id": null
    }
}

Update Contact Reference ID

curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets/ewallet_053d64c44834e1d3057ecb68a34c6b6c/contacts/cont_3625cb4fc18d005b12f9ccf0c466755e' \
-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 '{
    "contact_reference_id": "johndoe2025-11-03a"
}'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "6f0929be-0313-40c5-a8f3-24a82fd0dc85"
    },
    "data": {
        "id": "cont_6b37bac42846c7046bdb9e24b89a5d05",
        "first_name": "Jane",
        "last_name": "Doe",
        "middle_name": "",
        "second_last_name": "",
        "gender": "not_applicable",
        "marital_status": "not_applicable",
        "house_type": "",
        "contact_type": "personal",
        "phone_number": "+14155551997",
        "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_2c98c788eafe3a5a6b7541431e0ced5e",
            "name": "Jane Doe",
            "line_1": "123 Lake Forest Drive",
            "line_2": "",
            "line_3": "",
            "city": "Anytown",
            "state": "NY",
            "country": "",
            "zip": "12345",
            "phone_number": "+14155551234",
            "metadata": {
                "merchant_defined": true
            },
            "canton": "",
            "district": "",
            "created_at": 1754572956
        },
        "ewallet": "ewallet_b5320c566cc4aa01fe77440ad08693f7",
        "created_at": 1754572956,
        "metadata": {
            "merchant_defined": "updated"
        },
        "business_details": null,
        "compliance_profile": 0,
        "verification_status": "not verified",
        "send_notifications": false,
        "mothers_name": "",
        "contact_reference_id": "johndoe2025-11-03a"
    }
}

Bad Request - Wallet Disabled

curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets/ewallet_b5320c566cc4aa01fe77440ad08693f7/contacts/cont_6b37bac42846c7046bdb9e24b89a5d05' \
-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 '{
    "contact_reference_id": "johndoe2025-11-03a"
}'

{
    "status": {
        "error_code": "ERROR_EWALLET_DISABLED",
        "status": "ERROR",
        "message": "The request attempted an operation that requires a wallet, but the wallet is disabled. The request was rejected. Corrective action: Enable the wallet.",
        "response_code": "ERROR_EWALLET_DISABLED",
        "operation_id": "1d089df1-780f-4286-9b2d-0fe2caacade2"
    }
}

Bad Request - Wallet Contact Not Found

curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets/ewallet_d496b5377c6c6c1d8c0c9ba3fec1d073/contacts/cont_6b37bac42846c7046bdb9e24b89a5d05' \
-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 '{
    "contact_reference_id": "johndoe2025-11-03a"
}'

{
    "status": {
        "error_code": "ERROR_GET_EWALLET_CONTACT",
        "status": "ERROR",
        "message": "The request attempted an operation that requires a wallet contact, but the contact was not found. The request was rejected. Corrective action: In the path, specify the ID of a valid wallet, a string starting with 'ewallet_', and the ID of a valid contact belonging to that wallet, a string starting with 'cont_'.",
        "response_code": "ERROR_GET_EWALLET_CONTACT",
        "operation_id": "e26db2cc-7681-4eb2-a848-91f50224927b"
    }
}

Unauthorized

curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets/ewallet_053d64c44834e1d3057ecb68a34c6b6c/contacts/cont_3625cb4fc18d005b12f9ccf0c466755e' \
-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 '{
    "contact_reference_id": "johndoe2025-11-03a"
}'

{
    "status": {
        "error_code": "UNAUTHENTICATED_API_CALL",
        "status": "ERROR",
        "message": "The request was rejected due to an authentication issue. Corrective action: Check the status of your account in the 'Account Details' page of the Client Portal.",
        "response_code": "UNAUTHENTICATED_API_CALL",
        "operation_id": "b4a58037-119a-4629-ba05-d218dd88a081"
    }
}

In this section:

Documentation

Update Wallet Contact

Note

Parameters

Request Path Parameters

Request Header Parameters

Request Body Parameters

Note

Note

Response Parameters

Code Samples

Search results