Customers
Managing customer records in Vivamo
Customer records are stored to support Vivamo services including payment method storage, fraud/AML monitoring, KYC verification, and more. A customer record must be created before initiating any payment or disbursement flow.
Creating a customer
Create a customer record using the Create Customer endpoint. The minimum required fields are externalCustomerId and data.email. While other fields are optional, providing complete customer data (name, phone, address) upfront reduces the number of prompts shown during the SDK flow.
Customer uniqueness
Customer records in Vivamo are unique across the entire platform. When a customer is created, Vivamo checks whether a record with the same email address or phone number already exists. If a match is found, the existing customer is automatically connected to your operator rather than creating a duplicate record. This means a single customer can be linked to multiple operators while maintaining one unified profile.
The externalCustomerId you provide must be unique within your integration. If you attempt to create a customer with an externalCustomerId that is already in use by your operator, the request will be rejected. Similarly, no two customers can use the same email address. You will receive an error if you attempt to create a customer with an existing email address.
Email restrictions (production-only)
Restrictions are only applied in the production environment. However, certain gateways will not accept +suffix emails in any environment. If you have payment failures, this will likely be the cause.
The following email restrictions are enforced when creating or updating customer records.
Disposable email domains
Email addresses from known disposable or temporary email providers are not accepted. This includes services such as Mailinator, Guerrilla Mail, 10 Minute Mail, YOPmail, and similar providers. Attempts to use a disposable email domain will be rejected with a relevant message.
Plus suffix addresses
Email addresses containing + characters in the local part (before the @) are not supported. For example, user+test@example.com will be rejected, while user@example.com is valid. This restriction prevents the creation of multiple accounts using email aliasing. Attempts to use a plus suffix address will be rejected with a relevant message.
Phone number format
Phone numbers should be provided in international format with a leading + and country code (e.g. +15551234567). If a number is provided without a + prefix and contains at least 10 digits, it is assumed to be a US number and +1 is prepended automatically.
While the phone field is optional during customer creation, a phone number is required for SMS verification during payment and disbursement flows. If the customer record does not include a phone number, the SDK prompts the customer to enter one.
Production environment: Phone numbers are validated to confirm they belong to a valid mobile device. Landlines, VOIP numbers, and other non-mobile numbers are rejected with the error: "Sorry, this phone number cannot be used. Please use a valid mobile number."
Updating customer data
Customer data can be updated at any time via the Update Customer endpoint. The same email restrictions (disposable domains and plus suffixes) apply when updating a customer's email address. Phone number validation (mobile-only) also applies when updating a customer's phone number.