The Modem Pay API’s customer management is built to help you store and manage customer details efficiently. Below are detailed steps and example requests for creating, retrieving, updating, deleting, and listing customers, as well as listing their payment methods. This allows you to manage customer profiles and payment preferences seamlessly.

​
Create a Customer

To create a customer, use the modempay.customers.create() method, which allows you to add key information like the customer’s name, email, phone number, and an optional starting balance. The distinct option, when set to true, checks for existing customers with matching fields (e.g., email) to avoid duplicate entries. If distinct is omitted or set to false, a new customer entry will be created without duplicate checks.

Sample Request:

const customer = await modempay.customers.create(
    { name: "Caleb Okpara", email: "caleb@modempay.com", phone: "7000001" },
    { distinct: true }
);

Sample Response:

{
  "id": "8a8c8a0e-c5d2-4692-a94b-25284d36adc7",
  "balance": 0,
  "name": "Caleb Okpara",
  "email": "caleb@modempay.com",
  "phone": "7000001",
  "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
  "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
  "test_mode": true,
  "updatedAt": "2024-11-11T13:54:10.104Z",
  "createdAt": "2024-11-11T13:54:10.104Z"
}

​
Retrieve a Customer

To fetch a customer’s details, use modempay.customers.retrieve(customerId). Replace customerId with the customer’s unique ID.

Sample Request:

const customer = await modempay.customers.retrieve(
  "8a8c8a0e-c5d2-4692-a94b-25284d36adc7"
);

Sample Response:

{
  "id": "8a8c8a0e-c5d2-4692-a94b-25284d36adc7",
  "name": "Caleb Okpara",
  "email": "caleb@modempay.com",
  "phone": "7000001",
  "balance": 0,
  "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
  "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
  "test_mode": true,
  "createdAt": "2024-11-11T13:54:10.104Z",
  "updatedAt": "2024-11-11T13:54:10.104Z"
}

​
Update a Customer

Update a customer’s information using modempay.customers.update(customerId, params). Specify the customer ID and the fields to update.

Sample Request:

const customer = await modempay.customers.update(
    "8a8c8a0e-c5d2-4692-a94b-25284d36adc7",
    { name: "Chibuike Okpara" }
);

Sample Response:

{
  "id": "8a8c8a0e-c5d2-4692-a94b-25284d36adc7",
  "name": "Chibuike Okpara",
  "email": "caleb@modempay.com",
  "phone": "7000001",
  "balance": 0,
  "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
  "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
  "test_mode": true,
  "createdAt": "2024-11-11T13:54:10.104Z",
  "updatedAt": "2024-11-11T14:56:53.949Z"
}

​
Delete a Customer

Remove a customer from your records using modempay.customers.delete(customerId). This action is irreversible.

Sample Request:

await modempay.customers.delete("8a8c8a0e-c5d2-4692-a94b-25284d36adc7");

​
List All Customers

To view all customers, use modempay.customers.list(). This returns a list of customers, with pagination options if there are many entries.

Sample Request:

const customers = await modempay.customers.list({ limit: 2 });

// or list by matching terms
const customers = await modempay.customers.list({ limit:2, search: "caleb" })

Sample Response:

{
  "data": [
    {
      "id": "8a8c8a0e-c5d2-4692-a94b-25284d36adc7",
      "name": "Chibuike Okpara",
      "email": "caleb@modempay.com",
      "phone": "7000001",
      "balance": 0,
      "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
      "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
      "test_mode": true,
      "createdAt": "2024-11-11T13:54:10.104Z",
      "updatedAt": "2024-11-11T14:56:53.949Z"
    },
    {
      "id": "0f6e0912-2f2f-4d8b-bd68-ac8c97c44ae6",
      "name": "Caleb Okpara",
      "email": "calebchibuike@modempay.com",
      "phone": "7000002",
      "balance": 0,
      "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
      "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
      "test_mode": true,
      "createdAt": "2024-11-09T14:49:49.490Z",
      "updatedAt": "2024-11-09T14:49:49.490Z"
    }
  ],
  "meta": {
    "total": 3
  }
}

​
List Payment Methods for a Customer

To retrieve the payment methods associated with a specific customer, use their customer ID. This is useful to manage or display available payment methods during checkout.

Sample Request:

const paymentMethods = await modempay.customers.listPaymentMethods(
    "8a8c8a0e-c5d2-4692-a94b-25284d36adc7"
);

Sample Response:

{
  "data": [
    {
      "mobilepay": {
        "logo": "https://api.modempay.com/images/qcell.png",
        "type": "mobilepay",
        "group": "wallet-gm",
        "last4": "9944",
        "gateway": "qmoney",
        "fingerprint": "8d84c1b8ba568bce9b2590bfec618a65",
        "gateway_name": "QMoney"
      },
      "id": "ad47ccb9-687c-475b-90dc-1dd3b4cba68e",
      "type": "mobilepay",
      "customer": "8a8c8a0e-c5d2-4692-a94b-25284d36adc7",
      "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
      "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
      "test_mode": true,
      "has_been_detached": false,
      "createdAt": "2024-11-09T11:22:31.169Z",
      "updatedAt": "2024-11-09T11:22:31.169Z"
    }
  ],
  "meta": {
    "total": 1
  }
}
Handling ErrorsMandate