Getting started

Authentication

TagPay APIs are authenticated with API keys. Each merchant has two pairs — one for sandbox, one for live — and each pair has a public and a secret half.

Public vs secret keys

Public keys identify your account but cannot move money. Safe to embed in frontend code, mobile apps, or share publicly.

Secret keys can create charges, issue refunds, and read sensitive data. Server-side only. Treat them like passwords.

Key prefixes

The prefix tells you the key type and mode at a glance:

Prefix	Mode	Role
`pk_test_*`	Sandbox	Public
`sk_test_*`	Sandbox	Secret
`pk_live_*`	Live	Public
`sk_live_*`	Live	Secret

See Sandbox vs Live for how mode is determined.

Authorization header

Pass your secret key in the Authorization header as a Bearer token:

curl https://gwt.tagpay.ng/v1/checkout/sessions \
  -H "Authorization: Bearer $TAGPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 500000, "reference": "ord_1184", "customer_email": "[email protected]"}'

Rotating keys

Rotate a leaked or stale key in Developers → API keys → Rotate. The new key is shown once — save it. Rotation is atomic: the old key stops working the moment the new one is minted, so deploy the new key everywhere before you click rotate.

Storing keys safely

Use a secrets manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault).
Inject via environment variables — never read from a file in your repo.
Use different keys per environment (dev, staging, prod).
Restrict by IP allowlist where possible (Dashboard → Developers → API keys).