MotapaPay
API Docs

Creating Customers

When creating customers, you need to provide their personal information including name, contact details, and address. This helps establish customer profiles in your system for future transactions.

If a customer with the same phone number or identification information already exists, the API will return the existing customer details instead of creating a duplicate.

Headers

  • Authorization: Bearer YOUR_SECRET_KEY
  • Content-Type: application/json

Body Parameters

first_name

Required - The first name of the customer.

last_name

Required - The last name of the customer.

emails

Optional - Array of email objects for the customer. At least one contact method (email or phone) is required.

  • email_address: Email address of the customer
  • is_primary: Boolean indicating if this is the primary email
  • is_verified: Boolean indicating if the email is verified

phones

Optional - Array of phone objects for the customer. At least one contact method (email or phone) is required.

  • phone_number: Phone number of the customer (e.g., +263771234567)
  • is_primary: Boolean indicating if this is the primary phone
  • is_verified: Boolean indicating if the phone is verified

street

Required - The street address of the customer.

city

Required - The city of the customer.

state

Required - The state or province of the customer.

country

Required - The country of the customer.

postal_code

Required - The postal code of the customer.

customer_reference

Optional - Your own reference ID for the customer. This can be used to identify the customer in your system.

identification

Optional - Array of objects containing identification details:

  • id_type: Type of identification ("passport", "national_id", "driver_license", "utility_bill", "bank_statement", "other")
  • id_number: Identification number
  • issuing_country: Optional - Country that issued the ID
  • expiry_date: Optional - Expiration date of the ID
  • document_link: Optional - Link to uploaded document

Response Parameters

result

Status of the customer creation.

customer_id

Customer ID of the newly created or existing customer.

customer_reference

Customer reference ID of the newly created or existing customer.

message

Message describing the result of the operation.

Sample Request to Create a Customer

curl -X POST https://api.motapa.africa/v1/customer \
-H "Authorization: Bearer mp_test_26PHem9AhJZvU623DfE1x4sd" \
-H "Content-Type: application/json" \
-d '{
  "first_name": "John",
  "last_name": "Doe",
  "street": "123 Main St",
  "city": "Harare",
  "state": "Harare",
  "country": "Zimbabwe",
  "postal_code": "00263",
  "customer_reference": "CUST-12345",
  "emails": [
    {
      "email_address": "john.doe@example.com",
      "is_primary": true,
      "is_verified": true
    }
  ],
  "phones": [
    {
      "phone_number": "+263771234567",
      "is_primary": true,
      "is_verified": true
    }
  ],
  "identification": [
    {
      "id_type": "passport",
      "id_number": "AB123456",
      "issuing_country": "Zimbabwe",
      "expiry_date": "2030-01-01",
      "document_link": "https://example.com/documents/passport.pdf"
    }
  ]
}'

Sample Responses

{
    "result": "success",
    "customer_id": "mp_customer_1234567890",
    "customer_reference": "CUST-12345",
    "message": "Customer created successfully."
}