Customer Service

Manages customer accounts, onboarding, document verification, and profile management.

Initiate Customer Creation

POST /v1/customers/initiate

Starts the customer creation process by sending an OTP to the provided phone number.

Request Body:

{
  "phone_number": "+258830000000"
}

Field	Type	Required	Description
phone_number	string	Yes	Phone number in E.164 format

Response:

{
  "object": "phone_verification_session",
  "session_id": "pvs_abc12345",
  "otp": "123456"
}

---

Verify Customer Phone

POST /v1/customers

Verifies the customer's phone number using the OTP code and creates the customer account.

Request Body:

{
  "session_id": "pvs_abc12345",
  "verification_code": "123456"
}

Field	Type	Required	Description
session_id	string	Yes	Session ID from initiation (pattern: pvs_*)
verification_code	string	Yes	6-digit OTP code

Response:

{
  "object": "verification",
  "customer_id": "cus_abc12345",
  "verified": true
}

---

Get Customer

GET /v1/customers/{id}

Retrieves customer details by ID.

Path Parameters:

Parameter	Type	Description
id	string	Customer ID (pattern: usr_*)

Response:

{
  "object": "customer",
  "customer": {
    "customer_id": "cus_abc12345",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+258830000000",
    "address": {
      "street": "Av. Julius Nyerere",
      "city": "Maputo",
      "country": "Mozambique",
      "postal_code": "1100"
    },
    "nationality": "Mozambican",
    "sex": "M",
    "date_of_birth": "1990-01-15T00:00:00Z",
    "customer_segment": "personal",
    "kyc_status": "verified",
    "status": "active",
    "nationality_id": "***encrypted***",
    "tax_id": "***encrypted***",
    "nuib": "***encrypted***",
    "profile_picture": {
      "file_id": "file_123",
      "file_bucket": "profiles",
      "file_link": "/files/profiles/file_123"
    },
    "qrcode_id": "qr_abc123",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-06-15T10:30:00Z"
  }
}

---

Update Customer

PUT /v1/customers/{id}

Updates customer details. Only provided fields are updated.

Path Parameters:

Parameter	Type	Description
id	string	Customer ID (pattern: usr_*)

Request Body:

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "newemail@example.com",
  "business_name": "Doe Enterprises",
  "tax_id": "123456789",
  "address": "Av. Julius Nyerere^Maputo^Mozambique",
  "qrcode_id": "qr_abc123"
}

Field	Type	Required	Description
first_name	string	No	Customer's first name
last_name	string	No	Customer's last name
email	string	No	Email address
business_name	string	No	Business name (for business accounts)
tax_id	string	No	Tax ID (encrypted at rest)
address	string	No	Formatted as street^city^country
qrcode_id	string	No	QR code identifier

Response:

{
  "object": "customer",
  "customer": { ... }
}

---

Delete Customer

DELETE /v1/customers/{id}

Deletes a customer from the system.

Path Parameters:

Parameter	Type	Description
id	string	Customer ID (pattern: usr_*)

Response:

{
  "object": "customer"
}

---

List Customers

GET /v1/customers

Lists all customers with pagination.

Query Parameters:

Parameter	Type	Default	Description
page_size	integer	50	Max results per page (max: 100)
page_token	string	-	Token for next page

Response:

{
  "object": "list",
  "data": [
    {
      "customer_id": "cus_abc12345",
      "first_name": "John",
      "last_name": "Doe",
      ...
    }
  ],
  "has_more": true,
  "next_page_token": "token_xyz"
}

---

Upload ID Document

POST /v1/customers/{id}/upload-document

Uploads an identity document for KYC verification. Uses multipart/form-data.

Path Parameters:

Parameter	Type	Description
id	string	Customer ID (pattern: usr_*)

Request Body (multipart/form-data):

Field	Type	Required	Description
doc_type	string	Yes	Document type code (from supported docs endpoint)
image1	file	Yes	Front of the document
image2	file	Conditional	Back of the document (required if hasBack=true)

Response:

{
  "name": "John Doe",
  "date_of_birth": "1990-01-15",
  "id_number": "ABC123456",
  "issued_at": "2020-01-01",
  "expires_at": "2030-01-01",
  "address": "Av. Julius Nyerere, Maputo",
  "reference": "ref_abc123",
  "image1": "base64_encoded_image",
  "image2": "base64_encoded_image"
}

The reference field must be used when uploading the selfie in the next step.

---

Upload Selfie

POST /v1/customers/{id}/upload-selfie

Uploads a selfie for liveness detection and face matching against the ID document. Uses multipart/form-data.

Path Parameters:

Parameter	Type	Description
id	string	Customer ID (pattern: usr_*)

Request Body (multipart/form-data):

Field	Type	Required	Description
image	file	Yes	Selfie image
reference	string	Yes	Reference from document upload step

Response:

{
  "status": true,
  "result": null,
  "description": null
}

If verification fails:

{
  "status": false,
  "result": "match",
  "description": "Face does not match the document photo"
}

Result Value	Meaning
live	Selfie is not from a live person
match	Face does not match the document
processing	Error processing the image

---

Change Profile Picture

POST /v1/customers/{id}/profile/picture

Changes the customer's profile picture. Uses multipart/form-data.

Path Parameters:

Parameter	Type	Description
id	string	Customer ID

Request Body (multipart/form-data):

Field	Type	Required	Description
image	file	Yes	New profile picture

Response:

{
  "object": "customer",
  "customer": { ... }
}

---

Get Receiver Data

GET /v1/customers/get-receiver/{phone_number}

Retrieves basic receiver information by phone number (used for transfers).

Path Parameters:

Parameter	Type	Description
phone_number	string	Receiver's phone number

Response:

{
  "phone_number": "+258830000001",
  "first_name": "Jane",
  "last_name": "Smith",
  "sex": "F",
  "id": "cus_def67890",
  "profile_picture": {
    "file_id": "file_456",
    "file_bucket": "profiles",
    "file_link": "/files/profiles/file_456"
  }
}