Customers

Customers represent buyers and sellers in Kashia transactions. Use the Get or Create endpoint before creating payment links. If a customer with the same email already exists, the existing record is returned.

Customers are global across Kashia — the same person can transact with multiple merchants using one identity.

Endpoints

POST/api/v1/external/customers

Create a new customer or return an existing one by email.

Parameters
Parameter	Type	Required	Description
`email`	string	Yes	Customer's email address
`first_name`	string	Yes	Customer's first name
`last_name`	string	Yes	Customer's last name
`middle_name`	string	No	Customer's middle name
`phone_number`	string	No	Customer's phone number

Request example

bash

curl -X POST https://vault-api.kashiahq.com/api/v1/external/customers \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "+2348012345678"
  }'

Response

json

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "+2348012345678",
    "is_new": true
  }
}

The is_new field is true if the customer was just created, and false if they already existed. Optional fields (middle_name, phone_number) are absent from the response when unset — not null.

Single-vendor merchants

You only need to create a customer for the buyer. The seller is automatically set to your merchant's owner account — do not pass seller_user_id when creating payment links; passing any user other than yourself is refused with 400.

Marketplace merchants

Create customers for both the buyer and the seller, then pass both IDs when creating a payment link.