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://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",
    "middle_name": null,
    "phone_number": "+2348012345678",
    "is_new": true
  }
}

The is_new field is true if the customer was just created, and false if they already existed.

Single-vendor merchants

You only need to create a customer for the buyer. The seller is automatically set to your merchant's owner account.

Marketplace merchants

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