Customers

Keep the people who pay you in one place, with their cards, totals and any credit you owe them.

A customer groups the payments of one person: their name, mobile number and email, the last four digits of the cards they paid from, how many payments succeeded and for how much, and any credit from an overpayment you kept for them.

Where customers come from

You create them, in the dashboard under Customers or with POST /v1/customers.
A payment created with customer_details that succeeds finds the customer with that mobile number, or creates one.
A payment created with customer: "cus_…" belongs to that customer from the start.

A mobile number is unique among the customers of one mode: creating a second customer with the same number is refused with customer_phone_taken. Numbers are stored as 09xxxxxxxxx whatever way they were typed.

curl https://a.bezanbecard.com/v1/customers \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: customer-09900001234" \
  -H "Content-Type: application/json" \
  -d '{"name":"Test Customer","phone":"09900001234","email":"[email protected]"}'

Finding a customer

GET /v1/customers lists customers newest first and filters by phone (any typed form) and email. GET /v1/customers/:id returns one, and GET /v1/payments?customer=cus_… their payments.

Credit

credit is the rial you hold for the customer from overpayments resolved as credited (see overpayments). It is a record, not a balance Bezanbecard spends: honour it on a later order in your own way.

Updating and deleting

POST /v1/customers/:id changes name, phone, email and metadata. DELETE /v1/customers/:id deletes a customer and answers { "id": "cus_…", "object": "customer", "deleted": true }; while any of their payments is still open it is refused with customer_payments_open. Their finished payments keep their own copy of the customer's details.

Changes emit customer.created, customer.updated and customer.deleted.