Verify payment status

Verify the status of a payment transaction using the payment reference. This endpoint queries the payment provider’s API to get the current status.

⚠️ SECRET KEY REQUIRED

This endpoint requires a secret key (tybrite_sk_*). Publishable keys will return 403 Forbidden.

Why Secret Key? Payment verification accesses sensitive transaction data and provider APIs that should only be called from secure server-side environments. This prevents unauthorized access to payment status information.

Provider-Specific Verification:

Stripe:

• Queries Stripe Checkout Session API
• Returns payment status: pending, paid, failed, cancelled
• Includes payment intent details

Paystack:

• Queries Paystack Transaction Verification API
• Returns payment status and transaction details
• Includes gateway response and fees

M-Pesa:

• Queries M-Pesa STK Push Query API
• Returns transaction status from Safaricom
• Includes M-Pesa receipt number if successful

Airtel Money:

• Queries Airtel Money Transaction Status API
• Returns transaction status and details
• Includes Airtel transaction ID if successful

Note: Despite using POST method (for request body), this is a read operation that queries external payment provider APIs.

Key Type Support:

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

POST /v1/payments/verify

cURL

stripe

curl --request POST \
  --url https://api.tybritelabs.com/v1/payments/verify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider": "stripe",
  "reference": "PAY-12345678-ABC123"
}
'

200

stripe_success

{
  "provider": "stripe",
  "reference": "cs_test_a1b2c3...",
  "status": "success",
  "amount": 100,
  "currency": "usd",
  "customer_email": "[e-mail]",
  "payment_intent": "pi_3ABC123...",
  "metadata": {
    "payment_reference": "PAY-12345678-ABC123",
    "order_id": "880e8400-e29b-41d4-a716-446655440003"
  }
}

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.

Body

application/json

provider · enum<string> · required

Payment provider used for initialization

Available options: stripe, paystack, mpesa, airtel

Example:

"stripe"

reference · string · required

Payment reference returned from initialization

Example:

"PAY-12345678-ABC123"

Response

200

application/json

Payment verification successful

Option 1

Option 2

Option 3

Option 4

Stripe verification response

provider · string

Example:

"stripe"

reference · string

Stripe Checkout Session ID

Example:

"cs_test_a1b2c3..."

status · string

Normalized status. Returns success when Stripe payment_status === 'paid', otherwise the raw Stripe payment_status (e.g., unpaid, no_payment_required).

Example:

"success"

amount · number<float> | null

Amount in major currency units (converted from Stripe's minor units)

Example:

100

currency · string

Example:

"usd"

customer_email · string | null

Example:

"[e-mail]"

payment_intent · string | null

Stripe Payment Intent ID

Example:

"pi_3ABC123..."

metadata · object

Stripe session metadata (with store_id stripped)