Initialize payment

Initialize a payment transaction with HMAC signature verification and idempotency protection.

🔐 HMAC Signing (REQUIRED)

All payment initialization requests MUST include HMAC-SHA256 signature:

1. Generate Timestamp: Get current Unix timestamp in seconds
2. Create Payload: Concatenate timestamp + "." + JSON_body
3. Sign Payload: HMAC-SHA256(hmac_secret, payload) → base64 encode
4. Include Headers:
   • X-Timestamp: Unix timestamp (must be within 5 minutes)
   • X-Signature: Base64-encoded HMAC signature
   • Idempotency-Key: Unique key to prevent duplicate payments

🔄 Idempotency Protection (REQUIRED)

Include Idempotency-Key header to prevent duplicate payment initialization. If the same key is used, the original payment initialization is returned.

• Recommended format: payment-{timestamp}-{random}
• Must be unique per payment attempt
• Prevents duplicate charges on network retries
• Returns existing payment if key already used

Provider-Specific Flows:

Stripe (redirect):

1. Initialize payment with amount, currency, email
2. Redirect customer to checkout_url
3. Customer completes payment on Stripe
4. Stripe redirects to success/cancel URL
5. Verify payment status with /v1/payments/verify

Paystack (popup):

1. Initialize payment with amount, currency, email
2. Use returned public_key and reference to open Paystack popup
3. Customer completes payment in popup
4. Verify payment status with /v1/payments/verify

M-Pesa (STK Push):

1. Initialize payment with amount and phone (254XXXXXXXXX format)
2. Customer receives STK Push prompt on their phone
3. Customer enters M-Pesa PIN
4. Verify payment status with /v1/payments/verify

Airtel Money (Collection):

1. Initialize payment with amount, phone, and country code
2. Customer receives payment prompt
3. Customer authorizes payment
4. Verify payment status with /v1/payments/verify

Security Notes:

• HMAC secret is displayed in Settings → Integration Settings
• Never expose HMAC secret in client-side code
• Regenerate secret immediately if compromised
• Requests with invalid/missing signatures return 401 Unauthorized
• Timestamps older than 5 minutes are rejected (prevents replay attacks)

Rate Limiting:

• Additional 100 requests/hour limit for payment initialization
• Separate from global API rate limits

Key Type Support:

• ✅ Secret keys (full access)
• ❌ Publishable keys (forbidden - returns 403)

POST /v1/payments/initialize

cURL

stripe

curl --request POST \
  --url https://api.tybritelabs.com/v1/payments/initialize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Signature: <x-signature>' \
  --header 'X-Timestamp: <x-timestamp>' \
  --data '
{
  "provider": "stripe",
  "amount": 100,
  "currency": "usd",
  "email": "[e-mail]",
  "order_id": "880e8400-e29b-41d4-a716-446655440003",
  "success_url": "https://example.com/payment-success",
  "cancel_url": "https://example.com/payment-cancelled"
}
'

201

stripe

{
  "success": true,
  "provider": "stripe",
  "type": "redirect",
  "reference": "PAY-12345678-ABC123",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_...",
  "session_id": "cs_test_...",
  "environment": "test",
  "expires_at": "2026-02-10T12:00:00Z"
}

Authorizations

Authorization · string · header · required

API Key Authentication

Use your API key in the Authorization header:

Authorization: Bearer tybrite_sk_live_YOUR_KEY

Key Types:

Secret Keys (Server-Side Only):

• Format: tybrite_sk_live_* (production) or tybrite_sk_test_* (sandbox)
• Full read/write access to all endpoints
• ⚠️ NEVER expose in client-side code or public repositories
• Required for: write operations, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

• Format: tybrite_pk_live_* (production) or tybrite_pk_test_* (sandbox)
• Read-only access (GET requests only, plus POST semantic search)
• ✅ Safe for client-side JavaScript, mobile apps, and public code
• Allowed for: browsing products, search, CMS content, pricing queries

Endpoint-Specific Requirements:

• Authentication endpoints (/v1/auth/*): Secret key required
• Payment verification (POST /v1/payments/verify): Secret key required
• AI Recommendations (POST /v1/recommendations): Secret key required
• Semantic Search (POST /v1/search): Both key types allowed (read-only operation)
• All write operations: Secret key required
• All read operations: Both key types allowed

Using a publishable key for restricted operations returns 403 Forbidden.

Headers

Idempotency-Key · string · required

Unique key to prevent duplicate payment initialization (e.g., payment-{timestamp}-{random}). If you retry a request with the same key, the original payment initialization is returned.

X-Timestamp · integer · required

Unix timestamp in seconds (current time). Must be within 5 minutes of server time. Used to prevent replay attacks.

X-Signature · string · required

HMAC-SHA256 signature of the payload (timestamp + "." + request_body), base64-encoded. Sign using your HMAC secret from Settings → Integration Settings.

Body

application/json

provider · enum<string> · required

Payment provider to use

Available options: stripe, paystack, mpesa, airtel

Example:

"stripe"

amount · number<float> · required

Payment amount (must be greater than 0)

Required range: x >= 0.01

Example:

100

currency · string

Currency code (ISO 4217). Required for Stripe and Paystack.

• Stripe: Defaults to store's default currency
• Paystack: Must be one of NGN, GHS, ZAR, KES, USD
• M-Pesa: Always KES (ignored)
• Airtel: Determined by country code

Example:

"usd"

email · string<email>

Customer email (required for Stripe and Paystack)

Example:

"[e-mail]"

phone · string

Customer phone number (required for M-Pesa and Airtel Money)

• M-Pesa: Format 254XXXXXXXXX (Kenya)
• Airtel: Format {country_prefix}XXXXXXXXX (e.g., 254XXXXXXXXX for Kenya)

Example:

"254712345678"

country · string

Country code for Airtel Money (required for Airtel) Supported: KE (Kenya), UG (Uganda), TZ (Tanzania), RW (Rwanda)

Example:

"KE"

order_id · string<uuid>

Optional order ID to link payment to an order

Example:

"880e8400-e29b-41d4-a716-446655440003"

idempotency_key · string

Optional idempotency key to prevent duplicate payments

Example:

"pay-2026-02-10-abc123"

metadata · object

Optional metadata to attach to the payment

Show child attributes

Example:

{
  "customer_name": "John Doe",
  "order_number": "ORD-2026-001234"
}

success_url · string<uri>

Redirect URL after successful payment (Stripe only)

Example:

"https://example.com/payment-success"

cancel_url · string<uri>

Redirect URL after cancelled payment (Stripe only)

Example:

"https://example.com/payment-cancelled"

callback_url · string<uri>

Webhook callback URL (Paystack only)

Example:

"https://example.com/webhooks/paystack"

Response

201

application/json

Payment initialized successfully

Option 1

Option 2

Option 3

success · boolean

Example:

true

provider · string

Example:

"stripe"

type · string

Example:

"redirect"

reference · string

Example:

"PAY-12345678-ABC123"

checkout_url · string<uri>

Example:

"https://checkout.stripe.com/c/pay/..."

session_id · string

Example:

"cs_test_..."

environment · string

Example:

"test"

expires_at · string<date-time>