Aksal Black Enrollment

This endpoint allows Aksal to enroll a customer into the Aksal Black program by phone number. If the customer does not yet exist in Kenzup, they are created automatically. The system generates and returns the customer's Aksal Black ID and card number.

Authentication

• Uses signature authentication

Header	Description
X-SIGNATURE	The signature header of the request

See 2-security.md for signature generation details.

Endpoint

POST /api/v1/partner/aksal/black-card/enroll

Request Body

{
  "phone_number": "+212612345678"
}

Field	Type	Required	Description
phone_number	string	Yes	Customer's phone number. Accepts E.164 format (+212612345678) or local Moroccan format (0612345678).

Sample Request

POST https://app.kenzup.com/api/v1/partner/aksal/black-card/enroll

{
  "phone_number": "+212612345678"
}

Response

Status Code: 201 — Customer successfully enrolled (new enrollment)

{
  "aksal_black_id": "BLK2000627",
  "aksal_black_card": "220006320000006279"
}

Status Code: 200 — Customer was already enrolled (idempotent — safe to call multiple times)

{
  "aksal_black_id": "BLK2000627",
  "aksal_black_card": "220006320000006279"
}

Field	Type	Description
aksal_black_id	string	The customer's unique Aksal Black identifier. Format: BLK2000 followed by a sequential number. This is the primary identifier used for all program operations.
aksal_black_card	string	The customer's Aksal Black card number. Format: 18-digit numeric string derived from the ID. Used for display in the app.

Status Code: 400

Returned when phone_number is missing or not a valid phone number.

{
  "detail": "phone_number is required."
}

{
  "detail": "Invalid phone number format."
}

Status Code: 403

Returned when the signature is invalid or the client_id is not authorized.

ID and Card Generation

IDs are assigned sequentially. Each new enrollment receives the next available number:

• aksal_black_id: BLK2000 + N (e.g. BLK2000627 for N=627)
• aksal_black_card: 22000632 + zero-padded(N × 10 + check digit, 10 digits)
  • Check digit formula: (N × 7) % 10

The sequence continues from the highest existing ID in the database at the time of enrollment.