Payments

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

PayPal:

Pass the PayPal order id as the reference
Captures the buyer-approved order
Returns status success once the capture completes

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

Note: Despite using POST method (for request body), this is a read operation for most providers; for PayPal it captures the approved order.

Key Type Support:

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

POST

payments

verify

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

{
  "provider": "stripe",
  "reference": "cs_test_a1b2c3...",
  "status": "success",
  "amount": 100,
  "currency": "usd",
  "customer_email": "[email protected]",
  "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,

paypal,

paystack,

mpesa

Example:

"stripe"

reference

string

required

Payment reference returned from initialization

Example:

"PAY-12345678-ABC123"

Response

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:

"[email protected]"

payment_intent

string | null

Stripe Payment Intent ID

Example:

"pi_3ABC123..."

metadata

object

Stripe session metadata (with store_id stripped)

Initialize payment

Get cart

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

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

Reference

System

Products

Taxonomy

Orders

Payments

Cart & Wishlist

Marketplace

Recommendations

Discovery

Events

Tax

Analytics

Search

Authentication

Customers

Gift Cards

Promotions

CMS

Pricing

Messaging

Shipping

GC Connect

Reviews

Returns

Disputes

B2B

Webhooks

Ingestion

Sandbox

Verify payment status

Authorizations

Body

Response