Create Customer

POST/v1/customersRecommended

Create a customer record. externalId is unique per merchant.

Authentication

Signature Pattern

HMAC-SHA256(secretKey, "{timestamp}\nPOST\n/v1/customers\n{sha256(body)}")

Header	Value	Description
`X-Api-Key`	pk_live_a1b2c3d4e5f6g7h8	Merchant public API key
`X-Signature`	{hmac_sha256_hex}	Hex HMAC-SHA256 request signature
`X-Timestamp`	2026-04-13T10:00:00Z	ISO 8601 UTC request time (±5 min)

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

Request Example

JSONRequest Body

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

Response Parameters

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

Response Example

JSONResponse

{
  "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"
}

Status Codes

200Success

201Created

400Bad Request

401Unauthorized

404Not Found

429Rate Limited

Try itMock

POSThttps://api.pay.sandbox.kvell.group

Get Customer→