Skip to main content

Documentation Index

Fetch the complete documentation index at: https://apidocs.paylias.xyz/llms.txt

Use this file to discover all available pages before exploring further.

The Customers API allows you to issue and manage payment aliases for both individual and business users. Once created, each customer is uniquely identified by an alias within your namespace and becomes eligible to send and receive payments on the Paylias network provided they are enabled. Customers can be created directly via API and managed over time using the Update Customer and Delete Customer endpoints. While the assigned alias is permanent and cannot be changed, you can update other attributes such as the customer’s first name, middle name, nickname, and their active status (enabled or disabled).

​
Creating a Customer

You can register a new customer by calling the Create Customer endpoint. This is the canonical way to issue a new alias within your namespace and associate it with an individual or business. By default, customers are created in a DISABLED state until explicitly enabled. 
curl --request POST \
     --url https://sandbox.paylias.xyz/gateway/api/v1/csp/customer \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-paylias-api-key: <API-KEY>' \
     --header 'x-org-id: <Org-ID>' \
     --header 'x-partner-id: <Partner-ID>' \
     --header 'idempotency-key: <uuid>' \
     --data '
{
  "type": "Individual",
  "first_name": "Ziyad",
  "last_name": "Parekh",
  "middle_name": "",
  "payment_address": "ziyadparekh@safepay",
  "phone_number": "+16461234567",
  "email": "ziyad@gmail.com",
  "status": "ENABLED"
}'
Depending on the type of customer you’re creating, you need to specify the right data to Paylias. The following table highlights which fields are applicable to which type of customer
PropertyIndividualBusiness
typeY RequiredY Required
payment_addressY RequiredY Required
phone_numberY RequiredO Optional
emailY RequiredY Required
statusY RequiredY Required
first_nameY RequiredN/A
middle_nameO OptionalN/A
last_nameY RequiredN/A
business_legal_nameN/AY Required
business_trade_nameN/AY Required
business_websiteN/AY Required
business_descriptionN/AO Optional
business_industryN/AY Required
Once created and enabled, a customer can begin sending or receiving payments using their assigned alias.

​
Updating a Customer

To update a customer’s details such as their name, nickname, or active status use the Update Customer endpoint. This is a partial update operation; only the fields included in the request body will be updated.
Update a customer
curl --request PATCH \
     --url https://sandbox.paylias.xyz/gateway/api/v1/csp/customer/{customer_id} \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-paylias-api-key: <API-KEY>' \
     --header 'x-org-id: <Org-ID>' \
     --header 'x-partner-id: <Partner-ID>' \
     --header 'idempotency-key: <uuid>' \
     --data '
{
  "middle_name": "Zubair",
  "nick_name": "ziyadparekh"
}
'
Note that the customer’s alias (payment_address) is immutable and cannot be changed once assigned. While the Update Customer endpoint is fairly flexible and allows easy updates to properties, we advise to use this endpoint with care. Switching a customer from an individual to business or vice versa frequently can be seen as a sign of fraud on the network. Similarly, frequent switching of the cusomter’s business_industry code can also be flagged by network partipants.

​
Deleting a Customer

If a customer no longer wishes to use Paylias or needs to be deactivated, you can perform a soft delete by calling the Delete Customer endpoint.
Archive a customer
curl --request DELETE \
     --url https://sandbox.paylias.xyz/gateway/api/v1/csp/customer/{customer_id} \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-paylias-api-key: <API-KEY>' \
     --header 'x-org-id: <Org-ID>' \
     --header 'x-partner-id: <Partner-ID>' \
     --header 'idempotency-key: <uuid>' \
Deletes are final. Once a customer is deleted, their alias is sent back to the pool of available aliases under your namespace. Deleted customers cannot be restored.
The Customers API is the foundation of identity on the Paylias network. It allows your platform to create and manage the individuals and businesses participating in your payment ecosystem—while keeping control over user lifecycle and compliance entirely within your infrastructure.