PovitoDevelopers
العربية

Phase: Phase 2 — coming

Customers and consent#

Not available yet

The customer endpoints are in the contract so you can design against them, but they return 404 today and customer.id on sessions is null. Saved-card reuse, addresses on file and consent management ship together in Phase 2.

The Povito ID#

A shopper who verifies a phone on any Povito checkout has a customer record keyed by that phone — one identity across every merchant on the platform, the way it works everywhere else in Povito. It holds their name, saved delivery addresses and tokenised payment instruments.

Other hosted checkouts share that data with every merchant by default. Povito does not: a merchant sees a customer only through a session that customer paid on, and only the fields the customer consented to share with that merchant. Consent is asked for on the page, recorded with a timestamp, and revocable.

What a session will carry#

Once profiles are live, customer.id on sessions is filled in after phone verification, and the page prefills name, address and saved cards from the profile (within consent) so a returning shopper pays in two taps.

json
"customer": { "id": "cus_9BC3DEFGH1JK7KQ4M2XA", "phone": "+9647800000000", "name": "Ali M. Ismail", "address": { "…": "…" } }

Endpoints#

All require the customers:read scope on your secret key.

Call Returns
GET /v1/customers/{id} { id, object: "customer", phone, name, addresses[], consent: { share_profile, share_addresses, granted_at } } — only the fields this customer consented to share with you; 404 customer_not_found if there is no consent or you never had a session with them.
GET /v1/customers/{id}/instruments { data: [{ id, object: "instrument", gateway, brand, last_four, expiry, status }] } — tokens are never returned.
DELETE /v1/customers/{id}/instruments/{instrument_id} Revokes the token at the gateway, then marks the instrument canceled; 204.
bash
curl https://api.checkout.povito.com/v1/customers/cus_9BC3DEFGH1JK7KQ4M2XA \
  -H "Authorization: Bearer $POVITO_SECRET_KEY"

Instruments#

An instrument is a gateway token for a card the shopper chose to save (fib_card or stripe — see saved instruments). It is encrypted at rest with Cloud KMS, charge-capable only through Povito, and shows up to you as brand and last_four. Events: customer.instrument.saved and customer.instrument.revoked.

Reuse happens on the hosted page (the charge flow), not through your API — you never hold anything that can be charged.

Data protection#

Phone numbers are hashed in logs; addresses are shared only under consent; a customer's right-to-erasure request revokes instruments at the gateways first, then deletes the profile. The retention schedule is in security and compliance; the customer-facing terms (L-05) and the data processing agreement between Povito and merchants (L-08) are drafted for Phase 2 — see legal.