Customer wallets

Process description

This functionality is a convenient and effective tool for managing users and their multi-deposit addresses. With it you can create users and edit information about them. Each user will receive their own multi-deposit address for replenishment with several currencies available within the same blockchain and supported by our service.

Example - a user received an address and regularly replenishes it with different currencies, for example: ETH, USDT_BSC, POL. Such replenishments come to identical addresses but in different blockchains.

To make a deposit you need to create a client and get an address for him, these and other functional steps are described below.

Names of requests on the scheme indicate certain payment API methods.

Customers

• Create a customer - POST customer

• Update or add details to a client - POST update

Create customer request example

Example of the create customer request:

Pass your account ID as a parameter - "account".

Example of the create customer response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "string",
  "description": "string",
  "externalId": "string",
  "blocked": true
}

The following options are also available to you:

• Block customer - POST block Allows you to transfer the client to the "blocked" status. The client's addresses remain active for receipts. The merchant can receive funds to blocked addresses, but receives a notification via webhook that these are receipts from a blocked user. - CUSTOMER_PURSE_FUNDS_RECEIVED_FOR_PURSE ("blocked": true)

  Funds received at the blocked client's addresses:

  • Are credited to the merchant's account.

  • The merchant is notified by webhook with transaction details and the client's status ("blocked").

  • The decision on further distribution of funds remains with the merchant and his agreement with the client.

• Unblock customer - POST unblock Allows the merchant to restore the client to an active state. Once unblocked, the client can continue to use their addresses without restrictions.

Block/unblock customer request example

Example of the block customer request:

Pass your account ID as a parameter - "account","customerId".

Example of the block customer response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "string",
  "description": "string",
  "externalId": "string",
  "blocked": true
}

Purse (address)

• Get deposit address for customer - GET purse

  • If the deposit address has not been replenished for 30 days, it will expire, you will receive a webhook - CUSTOMER_PURSE_EXPIRED

Get purse request example:

Example of the get purse request:

• Pass the required parameters in the request - "account/customerId/currency".

Example of the get purse response:

• In response you will receive an address for deposits, and purseId (address id).

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "address": "string"
}

Purse statuses

Status	Description
PENDING_PAYMENT	The address is active for replenishment of the customer to which it is linked.
ARCHIEVED	The address is not active for replenishing this customer account.
DECLINED	The address is blocked due to receipt of illegal funds; using the address and replenishing it is not possible.

Deposit

When Calypso receives a client deposit you will receive webhooks with transaction statuses:

• The transaction pending in the mempool - CUSTOMER_PURSE_MEM_POOL_FOUND

• Transaction under compliance check - CUSTOMER_PURSE_PENDING_COMPLIANCE

• The transaction failed compliance check and the deposit address is blocked for further deposits - CUSTOMER_PURSE_COMPLIANCE_DECLINED

• Transaction received successfully - CUSTOMER_PURSE_FUNDS_RECEIVED_FOR_PURSE

• After receiving a webhook that the transaction has been successfully received, you need to get the transaction data using the method - GET purse-transaction

Get transaction request example:

Example of the get transaction data request:

• Pass the required parameters in the request - "account/transactionId".

Example of the get transaction data response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amount": 0,
  "currency": "string",
  "transactionHash": "string",
  "transactionState": "MEM_POOL_FOUND",
  "complianceState": "UNCHECKED",
  "translationToAccountCompleted": true,
  "createdDate": "2024-10-16T09:48:06.245Z"
}

Transaction statuses:

Status	Сompliance State	Description
MEM_POOL_FOUND	UNCHECKED	The transaction pending in the mempool.
PENDING_COMPLIANCE_CHECK	IN_PROGRESS	Transaction under compliance check.
DECLINED	DECLINE	The transaction failed compliance check.
CONFIRMED	CHECKED	Transaction received successfully.