Create Client

Endpoint

POST /api/v1/clients

Important behavior

• The partner is inferred from your API key. You must use a key scoped to your partner_id (platform-wide keys are rejected).
• You do not send partner_id in the body.
• After creating a client here, you can use the same client_id in transaction endpoints (for example /transactions/checkout-intent) once the client is in an acceptable state for payments.

Authentication and required headers

Same controls as partner transaction mutation endpoints:

Header	Required	Example
Content-Type	Yes	application/json
x-api-key	Yes	cp_live_partner_xxx
x-clive-hmac	Yes	40f3...
idempotency-key	Yes	client-AIRPEACE001-v1

See Authentication and Security for HMAC and idempotency details.

Request body

{
  "client_id": "AIRPEACE001",
  "legal_name": "Air Peace Ltd",
  "status": "active",
  "partner_fee_percentage": 4.0,
  "partner_fee_flat_usd": 0.5
}

Field details

Field	Type	Required	Description
client_id	string	Yes	Your stable merchant identifier (min length 3)
legal_name	string	Yes	Legal or display name (min length 2)
status	string	No	active, suspended, or pending_kyc (default active)
partner_fee_percentage	number	No	Optional override; must not be below your partner Clive fee percentage
partner_fee_flat_usd	number	No	Optional flat fee in USD (0–10)

Success response

201 Created

{
  "id": "cm8s6abc123",
  "partner_id": "ECHEZONA001",
  "client_id": "AIRPEACE001",
  "legal_name": "Air Peace Ltd",
  "status": "active",
  "partner_fee_percentage": 4.0,
  "partner_fee_flat_usd": 0.5,
  "created_at": "2026-03-05T15:21:35.222Z",
  "updated_at": "2026-03-05T15:21:35.222Z"
}

Error responses

400 Validation / business rule

• VALIDATION_ERROR — invalid body fields.
• CLIENT_FEE_BELOW_CLIVE_FEE — partner_fee_percentage is lower than the partner’s configured Clive fee.

401 / 403

• API_KEY_INVALID, HMAC_INVALID, IDEMPOTENCY_KEY_MISSING, etc. — see Authentication and Security.
• API_KEY_SCOPE_FORBIDDEN — key is not tied to a partner.
• PARTNER_SUSPENDED — partner account is suspended.

409 Conflict

• CLIENT_EXISTS — a client with the same client_id already exists for this partner.

cURL example

BODY='{"client_id":"AIRPEACE001","legal_name":"Air Peace Ltd","status":"active"}'
SIG=$(node -e "const c=require('crypto');console.log(c.createHmac('sha256', process.env.CLIVE_HMAC_SECRET).update(process.argv[1]).digest('hex'))" "$BODY")

curl -X POST "$CLIVE_API_BASE_URL/clients" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CLIVE_API_KEY" \
  -H "x-clive-hmac: $SIG" \
  -H "idempotency-key: client-AIRPEACE001-v1" \
  -d "$BODY"