Customers

Manage customer records and saved-card tokens, then charge saved cards without handling PANs.

9 endpoints

POST/v1/customersRecommended

Create a customer record. externalId is unique per merchant.

Request Parameters

Name	Type	Required	Description
`externalId`	string	Required	Your own unique id for this customer
`email`	string	Optional	Customer email (unique per merchant when set)
`phone`	string	Optional	Customer phone (+90…)
`name`	string	Optional	Customer name
`extraData`	object	Optional	Arbitrary merchant metadata

JSONRequest Example

{
  "externalId": "CUST-4821",
  "email": "buyer@example.com",
  "phone": "+905551112233",
  "name": "Ayşe Yılmaz"
}

JSONResponse Example

{
  "id": "cus_a1b2c3d4e5f6",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "externalId": "CUST-4821",
  "email": "buyer@example.com",
  "phone": "+905551112233",
  "name": "Ayşe Yılmaz",
  "extraData": {},
  "createdAt": "2026-04-13T10:00:00Z",
  "updatedAt": "2026-04-13T10:00:00Z"
}

GET/v1/customers/{id}Recommended

Retrieve a customer by id.

JSONResponse Example

{
  "id": "cus_a1b2c3d4e5f6",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "externalId": "CUST-4821",
  "email": "buyer@example.com",
  "phone": "+905551112233",
  "name": "Ayşe Yılmaz",
  "extraData": {},
  "createdAt": "2026-04-13T10:00:00Z",
  "updatedAt": "2026-04-13T10:00:00Z"
}

PUT/v1/customers/{id}Optional

Update a customer. Only the fields you send are changed.

Request Parameters

Name	Type	Required	Description
`email`	string	Optional	New email
`phone`	string	Optional	New phone
`name`	string	Optional	New name
`extraData`	object	Optional	Replace metadata

JSONRequest Example

{
  "name": "Ayşe Y. Demir"
}

JSONResponse Example

{
  "id": "cus_a1b2c3d4e5f6",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "externalId": "CUST-4821",
  "email": "buyer@example.com",
  "phone": "+905551112233",
  "name": "Ayşe Y. Demir",
  "extraData": {},
  "createdAt": "2026-04-13T10:00:00Z",
  "updatedAt": "2026-04-13T11:30:00Z"
}

GET/v1/customersRecommended

List customers with keyset pagination and optional email/phone filters.

Request Parameters

Name	Type	Required	Description
`email`	string	Optional	Filter by email
`phone`	string	Optional	Filter by phone
`limit`	integer	Optional	Page size
`cursor`	string	Optional	Opaque keyset cursor from a prior page

JSONResponse Example

{
  "items": [
    {
      "id": "cus_a1b2c3d4e5f6",
      "externalId": "CUST-4821",
      "email": "buyer@example.com",
      "name": "Ayşe Yılmaz",
      "createdAt": "2026-04-13T10:00:00Z"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA0LTEzVDEwOjAwOjAwWiJ9"
}

DELETE/v1/customers/{id}Optional

Soft-delete a customer. Returns 204 No Content.

JSONResponse Example

{}

POST/v1/customers/{id}/cardsRecommended

Attach a vault token to a customer for later saved-card charges. The token is bound to the customer inside card-vault in the same transaction.

Request Parameters

Name	Type	Required	Description
`cardToken`	string	Required	Vault token (tok_…) to attach
`isDefault`	boolean	Optional	Make this the customer default card

JSONRequest Example

{
  "cardToken": "tok_9f8e7d6c5b4a",
  "isDefault": true
}

JSONResponse Example

{
  "id": "cuc_2b3c4d5e6f70",
  "customerId": "cus_a1b2c3d4e5f6",
  "cardToken": "tok_9f8e7d6c5b4a",
  "last4": "4321",
  "bin": "415565",
  "brand": "visa",
  "expMonth": 12,
  "expYear": 2028,
  "isDefault": true,
  "createdAt": "2026-04-13T10:05:00Z"
}

GET/v1/customers/{id}/cardsRecommended

List a customer's saved card tokens (references only, never PANs).

JSONResponse Example

{
  "items": [
    {
      "id": "cuc_2b3c4d5e6f70",
      "customerId": "cus_a1b2c3d4e5f6",
      "cardToken": "tok_9f8e7d6c5b4a",
      "last4": "4321",
      "brand": "visa",
      "expMonth": 12,
      "expYear": 2028,
      "isDefault": true,
      "createdAt": "2026-04-13T10:05:00Z"
    }
  ]
}

GET/v1/customers/{id}/cards/defaultOptional

Return the customer's default saved card. 404 when the customer has no default card.

JSONResponse Example

{
  "cardToken": "tok_9f8e7d6c5b4a",
  "customerId": "cus_a1b2c3d4e5f6",
  "last4": "4321",
  "brand": "visa",
  "expMonth": 12,
  "expYear": 2028
}

DELETE/v1/customers/{id}/cards/{cardId}Recommended

Detach a saved card and revoke its token in card-vault. Returns 204 No Content.

JSONResponse Example

{}

Category Summary

Total Endpoints

Base Domain

api.pay.kvell.group