Authentication

All requests to the Direct Payments API must be authenticated using your API Key and API Secret.

Your Credentials

After onboarding you will receive:

Credential	Format / Prefix	Example	Usage
Merchant ID	UUID	`a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8`	Identification only
API Key (Public)	`pk_...`	`pk_live_abc123xyz789`	Sent in headers/body
API Secret (Private)	`sk_...`	`sk_live_def456uvw012`	Never exposed publicly

Never share or expose your API Secret.

Authentication Methods

Method 1 – HTTP Headers (Recommended)

X-API-Key: pk_live_abc123xyz789
X-API-Secret: sk_live_def456uvw012
Content-Type: application/json

Method 2 – Request Body (Still supported)

{
  "api_key": "pk_live_abc123xyz789",
  "api_secret": "sk_live_def456uvw012",
  "phone_number": "254708374149",
  "amount": 1000.00,
  ...
}

Use headers whenever possible – it keeps credentials out of the request payload and logs.

Full cURL Example (Headers)

curl -X POST https://payments.pesavoucher.com/api/v1/stk_push \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_abc123xyz789" \
  -H "X-API-Secret: sk_live_def456uvw012" \
  -d '{
    "phone_number": "254708374149",
    "amount": 1500.00,
    "account_reference": "ORD-2025-001"
  }'

Environment-Specific Keys

Environment	Key Prefix Example	Base URL
Sandbox	`pk_test_...` / `sk_test_...`	`https://sandbox.payments.pesavoucher.com/api/v1`
Production	`pk_live_...` / `sk_live_...`	`https://payments.pesavoucher.com/api/v1`

Never use test keys in production or live keys in sandbox.

Best Security Practices

Store credentials only in server-side environment variables
Never hard-code keys in source code or client-side JavaScript
Use different keys for sandbox and production
Rotate keys every 90 days (contact support for rotation)
Restrict keys by IP whitelist in the merchant dashboard
Enable 2FA on your merchant portal account
Monitor API usage and set up alerts for unusual activity

Example `.env` file

# Sandbox
PAYMENT_API_KEY_SANDBOX=pk_test_abc123xyz789
PAYMENT_API_SECRET_SANDBOX=sk_test_def456uvw012

# Production
PAYMENT_API_KEY=pk_live_abc123xyz789
PAYMENT_API_SECRET=sk_live_def456uvw012

Common Authentication Errors

HTTP Code	Error Message	Solution
401	Invalid API credentials	Double-check key/secret
401	API key not found	Use the correct environment key
403	IP address not whitelisted	Add your server IP in merchant portal
403	Account suspended	Contact support

That’s everything you need for api authentication.