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:

Pass the reference returned by initialize, or its session_id; a PaymentIntent id (pi_...) or charge id (ch_...) from a Stripe event is also accepted
Returns success once the Checkout Session is paid, otherwise Stripe’s own payment_status (for example unpaid)
Includes the Checkout Session id, the order it was opened for, and the PaymentIntent

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": "PAY-12345678-ABC123"
}
'

{
  "provider": "stripe",
  "reference": "cs_test_a1b2c3...",
  "status": "success",
  "amount": 100,
  "currency": "usd",
  "customer_email": "john.doe@example.com",
  "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: every write a shopper does not make for themselves, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

Format: tybrite_pk_live_* (production) or tybrite_pk_test_* (sandbox)
Catalogue reads, plus the actions a shopper takes for themselves
✅ Safe for client-side JavaScript, mobile apps, and public code
Allowed for: browsing products, search, CMS content, pricing queries, cart and wishlist, reviews, storefront events, and the Agent API's quotes, cart drafts and checkout intents

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)
Shopper actions (cart, wishlist, reviews, storefront events, Agent API quotes, cart drafts and checkout intents): Both key types allowed
All other 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

The reference passed in the request, returned as given

Example:

"PAY-12345678-ABC123"

session_id

string

The Stripe Checkout Session the reference resolved to

Example:

"cs_test_a1b2c3..."

order_id

string<uuid> | null

The order the payment was initialized for, or null when it was initialized without one

Example:

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

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:

"john.doe@example.com"

payment_intent

string | null

Stripe Payment Intent ID

Example:

"pi_3ABC123..."

metadata

object

Stripe session metadata (with store_id stripped)

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"
}
'

{
  "provider": "stripe",
  "reference": "cs_test_a1b2c3...",
  "status": "success",
  "amount": 100,
  "currency": "usd",
  "customer_email": "john.doe@example.com",
  "payment_intent": "pi_3ABC123...",
  "metadata": {
    "payment_reference": "PAY-12345678-ABC123",
    "order_id": "880e8400-e29b-41d4-a716-446655440003"
  }
}

Reference

System

Store

Products

Taxonomy

Orders

Payments

Cart & Wishlist

Marketplace

Recommendations

Discovery

Events

Tax

Analytics

Agent

Search

Authentication

Customers

Gift Cards

Promotions

Campaigns

CMS

Pricing

Messaging

Shipping

GC Connect

Reviews

Returns

Disputes

B2B

Webhooks

Ingestion

Feeds

Sandbox

Verify payment status

Authorizations

Body

Response