Customer

A Customer in the Paylias network represents an entity with a unique payment alias (address) issued by a Domain. These aliases function as digital addresses for sending and receiving payments, similar to traditional card numbers or PANs.

Overview

Each Customer:

Has a unique payment address
Is issued under a specific Domain
Maintains a status for payment operations
Supports personal identification details
Facilitates payment routing across the network

API Resource

Property	Type	Description	Notes
`token`	string	Unique identifier for the customer	Auto-generated upon creation
`partner_id`	string	Associated Domain ID	Links to Domain record
`first_name`	string	Customer's first name	Required
`middle_name`	string	Customer's middle name	Optional
`last_name`	string	Customer's last name	Required
`nick_name`	string	Customer's nickname	Optional
`payment_address`	string	Unique payment alias	Format: `identifier@domain`
`status`	enum	Current customer status	See Status Types
`created_at`	timestamp	Creation timestamp	Unix timestamp in seconds
`updated_at`	timestamp	Last update timestamp	Unix timestamp in seconds
`deleted_at`	timestamp	Deletion timestamp	Only present if deleted

Status Types

Status	Value	Description
`NONE`	0	No status assigned
`DISABLED`	1	Customer operations disabled
`ENABLED`	2	Customer fully operational
`DELETED`	3	Customer soft deleted

Authentication

All Customer operations require:

API Key in the X-Sfpy-Api-Key header
Organization ID in the X-Org-ID header
Domain ID in the X-Partner-ID header

API Endpoints

Create Customer

Creates a new customer with a payment address.

Required Parameters

Parameter	Type	Required	Description
`first_name`	string	Yes	Customer's first name
`middle_name`	string	No	Customer's middle name
`last_name`	string	Yes	Customer's last name
`nick_name`	string	No	Customer's nickname
`payment_address`	string	Yes	Unique payment alias
`status`	string	Yes	Initial status (ENABLED/DISABLED)

`POST /api/v1/csp/customer`

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/customer' \
--header 'X-Org-ID: org_ct239n420or249k5bo90' \
--header 'X-Partner-ID: part_ct23b6420or249k5boag' \
--header 'X-Sfpy-Api-Key: <api_key>' \
--data '{
    "first_name": "Ziyad",
    "middle_name": "",
    "last_name": "Parekh",
    "nick_name": "ziyad",
    "payment_address": "ziyadparekh@safepay-platinum",
    "status": "ENABLED"
}'

Example Response

{
    "ok": true,
    "data": {
        "token": "cust_cvink1420or763mhjesg",
        "partner_id": "part_ct23b6420or249k5boag",
        "first_name": "Ziyad",
        "last_name": "Parekh",
        "nick_name": "ziyad",
        "payment_address": "ziyadparekh@safepay-platinum",
        "status": 2,
        "created_at": {
            "seconds": 1743092228
        },
        "updated_at": {
            "seconds": 1743092228
        }
    }
}

Update Customer

Updates an existing customer's details.

Path Parameters

Parameter	Type	Required	Description
`paymentAddress`	string	Yes	Customer's payment address

Required Parameters

Parameter	Type	Required	Description
`first_name`	string	Yes	Updated first name
`middle_name`	string	No	Updated middle name
`last_name`	string	Yes	Updated last name
`nick_name`	string	No	Updated nickname
`status`	string	Yes	Updated status

`PATCH /api/v1/csp/customer/{paymentAddress}`

curl --location --request PATCH 'https://production.oysterapi.net/csp/api/v1/csp/customer/ziyadparekh@safepay-platinum' \
--header 'X-Org-ID: org_ct239n420or249k5bo90' \
--header 'X-Partner-ID: part_ct23b6420or249k5boag' \
--header 'X-Sfpy-Api-Key: <api_key>' \
--data '{
    "first_name": "Ziyad",
    "middle_name": "Zubair",
    "last_name": "Parekh",
    "nick_name": "ziyadparekh",
    "status": "ENABLED"
}'

Example Response

{
    "ok": true,
    "data": {
        "token": "cust_ct240ss20or24oulgfp0",
        "partner_id": "part_ct23b6420or249k5boag",
        "first_name": "Ziyad",
        "middle_name": "Zubair",
        "last_name": "Parekh",
        "nick_name": "ziyadparekh",
        "payment_address": "ziyad@safepay-platinum",
        "status": 2,
        "created_at": {
            "seconds": 1732526195
        },
        "updated_at": {
            "seconds": 1743095229
        }
    }
}

Find Customer

Retrieves details of a specific customer within the issuing Domain.

Path Parameters

Parameter	Type	Required	Description
`paymentAddress`	string	Yes	Customer's payment address

`GET /api/v1/csp/customer/{paymentAddress}`

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/customer/ziyadparekh@safepay-platinum' \
--header 'X-Org-ID: org_ct239n420or249k5bo90' \
--header 'X-Partner-ID: part_ct23b6420or249k5boag' \
--header 'X-Sfpy-Api-Key: <api_key>'

Example Response

{
    "ok": true,
    "data": {
        "token": "cust_cvink1420or763mhjesg",
        "partner_id": "part_ct23b6420or249k5boag",
        "first_name": "Ziyad",
        "middle_name": "Zubair",
        "last_name": "Parekh",
        "nick_name": "ziyadparekh",
        "payment_address": "ziyadparekh@safepay-platinum",
        "status": 2,
        "created_at": {
            "seconds": 1743092228
        },
        "updated_at": {
            "seconds": 1743093263
        }
    }
}

Search Customers

Retrieves a filtered list of customers with pagination support.

Query Parameters

Parameter	Type	Required	Description
`tokens`	string[]	No	Filter by customer tokens
`partner_ids`	string[]	No	Filter by Domain IDs
`first_names`	string[]	No	Filter by first names
`middle_names`	string[]	No	Filter by middle names
`last_names`	string[]	No	Filter by last names
`nick_names`	string[]	No	Filter by nicknames
`payment_addresses`	string[]	No	Filter by payment addresses
`status`	string[]	No	Filter by status
`limit`	integer	Yes	Results per page
`page`	integer	Yes	Page number

`GET /api/v1/csp/customer`

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/customer?payment_addresses=ziyadparekh%40safepay-platinum&limit=10&page=1&status=ENABLED' \
--header 'X-Org-ID: org_ct239n420or249k5bo90' \
--header 'X-Partner-ID: part_ct23b6420or249k5boag' \
--header 'X-Sfpy-Api-Key: <api_key>'

Example Response

{
    "ok": true,
    "data": {
        "count": 1,
        "customers": [
            {
                "token": "cust_cvink1420or763mhjesg",
                "partner_id": "part_ct23b6420or249k5boag",
                "first_name": "Ziyad",
                "middle_name": "Zubair",
                "last_name": "Parekh",
                "nick_name": "ziyadparekh",
                "payment_address": "ziyadparekh@safepay-platinum",
                "status": 2,
                "created_at": {
                    "seconds": 1743092228
                },
                "updated_at": {
                    "seconds": 1743093263
                }
            }
        ]
    }
}

Delete Customer

Soft deletes a customer by changing their status to DELETED.

Path Parameters

Parameter	Type	Required	Description
`paymentAddress`	string	Yes	Customer's payment address

`DELETE /api/v1/csp/customer/{paymentAddress}`

curl --location --request DELETE 'https://production.oysterapi.net/csp/api/v1/csp/customer/ziyadparekh@safepay-platinum' \
--header 'X-Org-ID: org_ct239n420or249k5bo90' \
--header 'X-Partner-ID: part_ct23b6420or249k5boag' \
--header 'X-Sfpy-Api-Key: <api_key>'

Example Response

{
    "ok": true
}

Resolve Customer

Validates a customer's existence and status across different Domains.

Path Parameters

Parameter	Type	Required	Description
`paymentAddress`	string	Yes	Customer's payment address

`GET /api/v1/csp/customer/{paymentAddress}/resolve`

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/customer/ziyadparekh@safepay-platinum/resolve' \
--header 'X-Org-ID: org_ct239n420or249k5bo90' \
--header 'X-Partner-ID: part_ct23b6420or249k5boag' \
--header 'X-Sfpy-Api-Key: <api_key>'

Example Response

{
    "ok": true,
    "data": {
        "token": "cust_ct240bk20or24oulgfog",
        "partner_id": "part_ct23c1420or249k5bocg",
        "first_name": "John",
        "last_name": "Collison",
        "nick_name": "john",
        "payment_address": "john@stripe-platinum",
        "status": 2,
        "created_at": {
            "seconds": 1732526126
        },
        "updated_at": {
            "seconds": 1732526126
        }
    }
}

Common Error Codes

Error Code	Description
`error.bad_request`	Invalid or missing required parameters
`error.resource_conflict`	Customer with payment address already exists
`error.resource_not_found`	Customer not found
`error.unauthorized_access`	Invalid or missing authentication
`500`, `502`, `503`, `504`	Server-side errors