How to create a Customer

Overview

Customer Purse API allows you to create and manage customer profiles that can receive deposits through customer purse addresses.

Use this guide to create a customer, update customer details, get customer information, and manage customer blocked status.

Integration flow

1. Create a customer by using the method - [POST] customer-purse/customer/create
2. Save the returned customer id in your system. It is required for address generation, transaction search, block, and unblock operations.
3. Optionally update customer data by using the method - [POST] customer-purse/customer/update
4. Optionally get customer details by customer ID or external ID.
5. If needed, block or unblock the customer by using the corresponding Customer Purse API methods.

Sequence

Names of requests on the scheme indicate Customer Purse API methods.

API methods

Create customer - [POST] customer-purse/customer/create

Request fields

Field	Type	Required	Description
account	string	Yes	Merchant account ID. The request will be sent for this account.
timestamp	number	Yes	Current Unix UTC timestamp in milliseconds. The value must not be less than 3 minutes in the past or greater than 3 minutes in the future.
payload	object	Yes	Object with customer creation data.

Payload fields

Field	Type	Required	Description
email	string	No	Customer email.
description	string	No	Customer description. Maximum length: 1000 characters.
externalId	string	No	Merchant-side customer ID. Maximum length: 255 characters.

Request example

{
  "account": "0x0000000000000000000000000000000000000000",
  "timestamp": 1761650432438,
  "payload": {
    "email": "customer@example.com",
    "description": "Customer profile",
    "externalId": "merchant-customer-123"
  }
}

Response fields

Field	Type	Description
id	string	Calypso customer ID.
email	string	Customer email, if provided.
description	string	Customer description, if provided.
externalId	string	Merchant-side customer ID, if provided.
blocked	boolean	Customer blocked status.

Response example 200 OK

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "customer@example.com",
  "description": "Customer profile",
  "externalId": "merchant-customer-123",
  "blocked": false
}

Optional methods

Method	Purpose	Payload
[POST] customer-purse/customer/update	Update customer email or description.	id, email, description
[POST] customer-purse/customer/get	Get customer by Calypso customer ID.	customerId
[POST] customer-purse/customer/external/get	Get customers by merchant-side external ID.	externalId
[POST] customer-purse/customer/block	Block customer.	customerId
[POST] customer-purse/customer/unblock	Unblock customer.	customerId

Blocked customer behavior

Case	Description
Customer is blocked	The customer receives blocked: true.
Deposits to blocked customer addresses	Addresses can still receive funds. The merchant receives a webhook with customerBlocked: true.
Merchant action	Decide how to process the received funds according to the merchant's agreement with the customer.
Customer is unblocked	The customer can continue using their addresses without the blocked flag.

Related docs

Document	Link
Get customer deposit address	How to get a deposit address for a customer
Process customer transactions	How to process Customer transactions
Customer Purse API reference	Customer Purse API
Customers webhooks	Customers webhooks