Create a customer account

Issues a permanent bank account number in your customer’s own name.

Send your secret key: Authorization: Bearer sk_live_…. See authentication.

The endpoint the whole product is for.

curl https://api.paymonetra.com/v1/customer_accounts \
  -H "Authorization: Bearer sk_live_..." \
  -d customer_reference=cus_9f21 \
  -d customer_name="Ngozi Nwosu" \
  -d customer_email=ngozi@example.com \
  -d customer_phone=08031234567

JSON or form encoding, both accepted.

{
  "customer_reference": "cus_9f21",
  "customer_name": "Ngozi Nwosu",
  "customer_email": "ngozi@example.com",
  "customer_phone": "08031234567",
  "account_number": "8021234567",
  "account_name": "MONETRA - Samifunds (Ngozi Nwosu)",
  "bank_name": "Payrep MFB",
  "status": "active",
  "mode": "live",
  "credits": 0,
  "collected_total": 0,
  "last_credit_at": null,
  "created_at": "2026-08-28T19:18:33+01:00"
}

201 on a new account, 200 when one already exists for that reference. Same body either way, so no branching. Calling it twice is safe and is the intended way to be idempotent.

customer_reference is the merchant's own key. Letters, numbers and . _ : - only, up to 80 characters, because it comes back in every webhook and appears in URLs.

customer_email is required for a new account from 21 October 2026. Until then an account without one still opens, and the response carries a warning:

"warnings": [{ "code": "customer_email_missing",
  "message": "Send customer_email for this customer. From 21 October 2026 a new customer account without one is refused. Sending this customer_reference again with customer_email adds it." }]

From 21 October a new customer_reference without customer_email answers 422 invalid_request with field: "customer_email". Accounts that already exist keep working without one.

customer_phone is optional. 7 to 15 digits with an optional leading +; spaces, dashes and brackets are stripped before it is stored.

Adding them to an existing account: send the same customer_reference again with customer_email and/or customer_phone. The account and number do not change; only the fields you send are filled in, and an empty field never clears a stored one. An integration that already calls this endpoint each time a customer opens their funding page picks the emails up as customers return.

A bad email or phone is refused with 422 invalid_request and field naming it. Every customer account shape, here and on GET, carries both fields (empty strings when not given).

Account limit. Your business can hold 500 active customer accounts, plus 2 more for every account that has received a payment. The limit grows on its own as your customers pay. At the limit a new customer_reference answers 403 account_limit, and so does POST /payments naming a new customer_reference. Customers who already have an account are unaffected. Create an account when a customer is ready to pay, not at signup, and reuse it every time after that. Test keys are not limited.

Refused names. A customer_name that impersonates a bank or Paymonetra (for example "Paymonetra Support") answers 422 bad_name with field: "customer_name", here and on POST /payments.

Customer accounts has the context around this call.