docs

Get customer by ID

Retrieves customer lifecycle information (id, type, name, email, phone, address, metadata). Response shape is identical to the `customer.*` webhook payload. For transaction counts + payment methods, call `GET /customers/:id/stats`.

GET
/customers/{id}

Retrieves customer lifecycle information (id, type, name, email, phone, address, metadata). Response shape is identical to the customer.* webhook payload. For transaction counts + payment methods, call GET /customers/:id/stats.

Authorization

api-key
AuthorizationBearer <token>

API key for merchant integrations. Send as Authorization: Bearer <your key>.

In: header

Path Parameters

id*string

Customer ID

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customers/string"
{
  "id": "cus_abc123xyz",
  "object": "customer",
  "type": "registered",
  "createdAt": "string",
  "updatedAt": "string",
  "name": "string",
  "email": "string",
  "phone": "string",
  "address": {},
  "guestFingerprint": {},
  "metadata": {},
  "merchantId": "string"
}
{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "No valid API key provided.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#authentication_required"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "permission_denied",
    "message": "The API key does not have permission to perform this action.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#permission_denied"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such customer: cus_abc123",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#resource_missing"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again or contact support.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#internal_error"
  },
  "request_id": "req_abc123def456"
}

Create a customer POST

Creates a new customer record. At least one contact method (email or phone) is required. Customers are environment-specific (test vs live database).

List payment links GET

Lists payment links with filtering, pagination, and search. Features: - Filter by active status - Search by product name, description, or unit label - Filter by amount (equal, between, greater, less) - Filter by date (last period, equal, between, after, before) - Pagination support