TagPayTagPay

Guides

Customers

A Customer is a persistent record of someone who buys from you. TagPay can run perfectly well without them — every charge already carries an email — but explicit customers give you a real handle in the dashboard, surface lifetime totals, and unlock features like subscriptions and stored payment methods.

When to create one

You don't need a customer record for one-off payments. Create one when the relationship is going to outlive a single charge:

  • Subscriptions and recurring billing. A customer is the anchor a subscription attaches to.
  • Loyalty programmes. You want to know what someone has spent across all their charges; total_spend handles that.
  • Reconciliation in the dashboard. Ops can search by name or phone instead of having to know an email.
  • Stored payment methods. Reusing a card across sessions needs a customer to bind it to.

For a simple one-shot "buy this thing", skip the customer object. The email on the charge is enough.

Attaching charges

There are two ways to link a charge to a customer record. Both work — pick whichever fits your code.

By customer_id: if you've already created the customer, reference the ID. The cleanest option when you have it.

curl https://gwt.tagpay.ng/v1/transactions/initialize \
  -H "Authorization: Bearer $TAGPAY_SECRET_KEY" \
  -d '{
    "amount": 500000,
    "email": "[email protected]",
    "customer_id": "cus_5Lp8WkQzR"
  }'

By email: just pass the email on the charge. TagPay finds an existing customer with that email (or creates one lazily if none exists) and links the charge to it. Useful when your codepath has the email but not the ID handy.

curl https://gwt.tagpay.ng/v1/transactions/initialize \
  -H "Authorization: Bearer $TAGPAY_SECRET_KEY" \
  -d '{
    "amount": 500000,
    "email": "[email protected]"
  }'

Dedupe by email

Email is unique per merchant. Two customers cannot share an email in your account. If you try to POST /v1/customers with an email that already exists, you get EMAIL_EXISTS (HTTP 409) instead of a duplicate record.

Different merchants in your organisation can each have their own customer record for the same email — uniqueness is scoped per merchant, not globally.

Updating

PUT /v1/customers/:id accepts a partial body — send only the fields you want to change. Name, phone, metadata, and even email can be updated; you cannot change the customer ID, the creation timestamp, or the aggregate totals.

curl -X PUT https://gwt.tagpay.ng/v1/customers/cus_5Lp8WkQzR \
  -H "Authorization: Bearer $TAGPAY_SECRET_KEY" \
  -d '{
    "first_name": "Adaeze",
    "phone": "+2348098765432"
  }'

Updating the email re-checks the uniqueness rule — you'll get EMAIL_EXISTS if another customer in your account already uses the new value.

See the Customers API reference for every field and error code.