Create and store customer records tied to their merchant accounts.
Create Customer
The Create a Customer endpoint allows merchants to create and store customer records tied to their merchant accounts. This is essential for enabling streamlined future transactions without requiring repeated customer registration. Each customer created is assigned a unique identifier (customer_id) using a universally unique identifier (UUID).
Key Features
Store customer details such as name, email, and company information
Automatically assigns a unique customer_id for use in subsequent API calls
Supports ISO 3 code for address_country, sent to processing gateway when provided
Add customer-specific custom fields to capture additional data unique to your business
Data Validation
Requires at least one of the following fields to create a record: firstname, lastname, email, or company.
Required Fields
At least one of the following fields must be provided to successfully create a customer record:
firstname(string): Customer's first namelastname(string): Customer's last nameemail(string): Customer's email addresscompany(string): Company name associated with the customer
Optional Fields
address_country(string): The ISO 3 code for the customer's country. This will be sent to the processing gateway if provided. Example:USAfor the United Statesoptions(object): Additional configuration options including custom fields specific to your customer record
Custom Fields with Options Parameter
The options parameter allows you to add custom fields that are specific to your customer record. These custom fields can capture additional customer information that's unique to your business requirements.
Important Notes:
- Custom field values are always stored as strings regardless of the specified type
- The type field indicates how the value should be interpreted and validated
- Custom fields are unique to your customer record and don't affect other customer records
Response Structure
| Code | Response | Description |
|---|---|---|
| 201 | Success | Customer successfully created. Returns the customer_id and data. |
| 400 | Bad Request | Missing or invalid required fields. |
| 401 | Unauthorized | API key invalid or missing. |
| 500 | Internal Server Error | An unexpected error occurred. |
Important Considerations
Field Validation: Ensure at least one required field (firstname, lastname, email, company) is present in the payload.
Duplicate Customers: Creating a customer with duplicate details (e.g., email) will generate a new customer record with a unique customer_id. It does not merge existing records.
Country Code Format: If using address_country, confirm it matches the ISO 3 standard to avoid validation errors.
Future Transactions: The customer_id can be used for associating payment methods, transactions, or invoices with this customer.
Use meaningful and unique data for customer identification (e.g., email or company)
Keep customer information updated by utilizing the Update a Customer endpoint
Always verify the API key and ensure your implementation complies with PCI DSS standards
