Payments

The PaymentsService class (accessed via client.payments) handles the core initialization and status verification for diverse payment providers including Stripe, PayPal, Paystack, and M-Pesa.

Sandbox test mode: When you use a tybrite_sk_test_* key, all payment providers are automatically switched to their test/sandbox credentials — regardless of what your store’s payment settings show. Stripe uses test mode, PayPal uses its sandbox, Paystack uses test keys, and M-Pesa targets the Safaricom sandbox. No code changes are needed between sandbox and production; swap the key and the right environment follows. Every response includes a Tybrite-Environment: sandbox | production header confirming which environment resolved.

🔐 Security & Signing (HMAC & Idempotency)

To prevent unauthorized payment initiation and duplicate charges, initializePayment requires both an HMAC-SHA256 signature and a mandatory Idempotency Key.

Signing & Idempotency Process

Generate ID: Create a unique key for the transaction (e.g., payment-{order_id}-{timestamp}).
Generate Timestamp: Get the current Unix timestamp in seconds.
Prepare Payload: Concatenate timestamp and JSON body: timestamp + "." + JSON_body.
Generate Signature: Compute HMAC-SHA256 signature using your HMAC Secret.
Base64 Encode: The signature must be Base64 encoded.

Code Implementation (TypeScript)

import crypto from 'crypto';

// 1. Define Signing Helper
function generateHmacSignature(payload: string, secret: string): string {
  return crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('base64');
}

// 2. Prepare Data & Sign
const idempotencyKey = `payment-${orderId}-${Date.now()}`;
const timestamp = Math.floor(Date.now() / 1000);
const body = JSON.stringify(paymentData);
const payload = `${timestamp}.${body}`;
const signature = generateHmacSignature(payload, hmacSecret);

// 3. Initialize Payment
const response = await client.payments.initializePayment({
  idempotencyKey: idempotencyKey,
  xTimestamp: timestamp,
  xSignature: signature,
  requestBody: paymentData
});

// If response.idempotent is true, this was a duplicate request

Financial Integrity: Payment initialization triggers money movement. The Idempotency-Key prevents duplicate sessions and charges. Requests missing this header will return 400 missing_idempotency_key.

Methods

`getPaymentMethods`

Retrieve all active payment methods configured in GC Admin. This endpoint accepts both publishable (pk_*) and secret (sk_*) API keys — storefronts can safely call it client-side to discover available providers before checkout.

const { methods } = await client.payments.getPaymentMethods({
  fields: 'provider,display_name,type'
});

Response

{
  "methods": [
    {
      "provider": "cash",
      "display_name": "Cash on Delivery",
      "type": "manual",
      "environment": "production",
      "is_configured": true
    },
    {
      "provider": "stripe",
      "display_name": "Stripe",
      "type": "redirect",
      "environment": "test",
      "is_configured": true
    },
    {
      "provider": "acme_pay",
      "display_name": "Acme Pay",
      "type": "redirect",
      "environment": "production",
      "is_configured": true,
      "custom_provider": true
    }
  ]
}

Each method in the returned list includes:

Field	Description
`provider`	Provider identifier (e.g. `stripe`, `paypal`, `paystack`, `mpesa`). Not a fixed set — see the note below.
`display_name`	Human-friendly label to show at checkout.
`type`	How the buyer completes payment: `redirect`, `popup`, `stk_push`, or `manual`.
`environment`	`sandbox` or `production`, matching the key you used.
`is_configured`	`true` when the provider is fully set up and ready to accept payments.
`custom_provider`	Present and `true` when the store offers its own payment provider rather than a built-in one.

`initializePayment`

Create a payment session with your chosen provider. Requires a Secret Key, a valid HMAC signature, and a mandatory Idempotency-Key. On the first successful call this returns 201 Created; subsequent calls with the same idempotency key and identical payload return 200 OK with idempotent: true and the original session. A request refused before it reaches the payment provider — an invalid body, an unknown order, or an amount that does not match the order — does not use up its Idempotency-Key, so the corrected request can be sent with the same key. While another request with the same key is still being initialized, the call returns 409 idempotency_in_progress; sending it again shortly with the same key returns the session once it exists.

The mandatory Idempotency-Key also makes this call eligible for the SDK’s automatic retries: a transient failure is retried safely and returns the original session rather than starting a second charge.

Secret Key required. initializePayment will reject publishable keys with 403. Never call this from untrusted client environments — keep your sk_* key and HMAC secret server-side.

const paymentData = {
  provider: 'stripe',
  amount: 5000,
  currency: 'USD',
  email: 'john.doe@tybritelabs.com',
  success_url: 'https://example.com/thanks',
  cancel_url: 'https://example.com/checkout'
};

const timestamp = Math.floor(Date.now() / 1000);
const idempotencyKey = `pay-stripe-${Date.now()}`;
const signature = generateHmacSignature(`${timestamp}.${JSON.stringify(paymentData)}`, hmacSecret);

// HTTP 201 Created on first call; HTTP 200 OK with idempotent:true on replay
const response = await client.payments.initializePayment({
  idempotencyKey: idempotencyKey,
  xTimestamp: timestamp,
  xSignature: signature,
  requestBody: paymentData
});

// Example 201 response body
// {
//   "success": true,
//   "provider": "stripe",
//   "type": "redirect",
//   "reference": "PAY-61713784-F4TAOI",
//   "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1wkhn...",
//   "session_id": "cs_test_a1wkhnXDJL6XPIzS3rjHUeF0PxUb7yu6Nxw8WJsXpjIgzNG6lSe8x3uue0",
//   "environment": "test",
//   "expires_at": "2026-06-21T13:21:54.000Z"
// }

// Redirect to Stripe Checkout
window.location.href = (response as any).checkout_url;

const paymentData = {
  provider: 'mpesa',
  amount: 1500,
  phone: '254700111222'
};

const timestamp = Math.floor(Date.now() / 1000);
const idempotencyKey = `pay-mpesa-${Date.now()}`;
const signature = generateHmacSignature(`${timestamp}.${JSON.stringify(paymentData)}`, hmacSecret);

// HTTP 201 Created on first call
const response = await client.payments.initializePayment({
  idempotencyKey: idempotencyKey,
  xTimestamp: timestamp,
  xSignature: signature,
  requestBody: paymentData
});

// Example 201 response body — an STK push prompt is sent to the phone:
// {
//   "success": true,
//   "provider": "mpesa",
//   "type": "stk_push",
//   "reference": "PAY-12345678-ABC123",
//   "checkout_request_id": "ws_CO_123456789",
//   "merchant_request_id": "12345-67890-1",
//   "customer_message": "Success. Request accepted for processing"
// }

const paymentData = {
  provider: 'paypal',
  amount: 49.99,
  currency: 'USD'
};

const timestamp = Math.floor(Date.now() / 1000);
const idempotencyKey = `pay-paypal-${Date.now()}`;
const signature = generateHmacSignature(`${timestamp}.${JSON.stringify(paymentData)}`, hmacSecret);

// HTTP 201 Created on first call
const response = await client.payments.initializePayment({
  idempotencyKey: idempotencyKey,
  xTimestamp: timestamp,
  xSignature: signature,
  requestBody: paymentData
});

// Example 201 response body
// {
//   "provider": "paypal",
//   "type": "popup",
//   "order_id": "ord_01HX...",
//   "paypal_order_id": "5O190127TN364715T",
//   "client_id": "AeA1QIZ...",
//   "currency": "USD",
//   "environment": "sandbox"
// }

// Use client_id + paypal_order_id to render the PayPal Buttons popup in your
// storefront. After the buyer approves, call verifyPayment to capture.

`verifyPayment`

Retrieve the absolute source of truth for a transaction. This is a read operation and does not require HMAC signing.

Secret Key required. verifyPayment will reject publishable keys with 403. Verification responses include charge details (amounts, customer email, payment intents) and must not be exposed to untrusted clients.

For Stripe, the reference returned by initializePayment and its session_id identify the same payment, and either may be passed; a PaymentIntent id (pi_...) or charge id (ch_...) taken from a Stripe event is accepted too. The response names the Checkout Session in session_id and the order the payment was initialized for in order_id, and returns reference exactly as it was passed.

// Stripe: the reference from initializePayment, or its session_id
const result = await client.payments.verifyPayment({
  requestBody: {
    provider: 'stripe',
    reference: 'PAY-61713784-F4TAOI'
  }
});
// result.status === 'success' once the Checkout Session is paid;
// result.order_id is the order the payment was opened for.

Response

{
  "provider": "stripe",
  "reference": "PAY-61713784-F4TAOI",
  "session_id": "cs_test_a1wkhnXDJL6XPIzS3rjHUeF0PxUb7yu6Nxw8WJsXpjIgzNG6lSe8x3uue0",
  "order_id": "880e8400-e29b-41d4-a716-446655440003",
  "status": "success",
  "amount": 5000,
  "currency": "usd",
  "customer_email": "john.doe@example.com",
  "payment_intent": "pi_3Q...",
  "metadata": {
    "order_id": "880e8400-e29b-41d4-a716-446655440003"
  }
}

Response shape (per-provider `oneOf`)

The response shape depends on the provider field. The Stripe shape is shown above; the other providers return:

{
  "provider": "paystack",
  "reference": "T123456789",
  "status": "success",
  "amount": 250000,
  "currency": "NGN",
  "channel": "card",
  "customer_email": "john.doe@tybritelabs.com",
  "paid_at": "2026-05-20T10:24:11.000Z",
  "metadata": {
    "order_id": "ord_01HX..."
  }
}

{
  "provider": "mpesa",
  "reference": "ws_CO_20260520102411...",
  "status": "success",
  "result_code": "0",
  "result_description": "The service request is processed successfully.",
  "merchant_request_id": "29115-34620561-1"
}

{
  "provider": "paypal",
  "reference": "5O190127TN364715T",
  "status": "success",
  "amount": 49.99,
  "currency": "USD",
  "capture_id": "3C679366HH908993F"
}

Status semantics by provider:

Stripe — success when the Checkout Session is paid, otherwise Stripe’s own payment_status (unpaid, no_payment_required, etc.). amount is in major currency units; order_id is null when the payment was initialized without an order.
Paystack — Mirrors Paystack’s status field (success, failed, abandoned).
M-Pesa — Enum: pending | success | cancelled | failed. Result code 1032 (user cancelled on phone) maps to cancelled.
PayPal — verify captures the buyer-approved order and returns success once the capture completes. The reference you pass is the PayPal order id returned at initialization.

Provider Support Matrix

Provider	Best For	Requirement	Verification Method
Stripe	International Cards	Email	Session Query
PayPal	Global Wallet / Card	Order id	Capture
Paystack	African Cards	Email	Ref Verification
M-Pesa	Kenyan Mobile Money	Phone (254)	STK Query

Formatting Tip: For M-Pesa, always provide the phone number in international format without the + prefix (e.g., 2547...).

Response Codes

`initializePayment`

Code	Meaning
`201`	Payment session created (new on first call with idempotency key).
`200`	Idempotent replay — same key and identical payload, original initialization returned.
`400`	Invalid request (missing `provider`/`amount`, invalid phone format for mpesa).
`401`	Invalid API key, or invalid/expired HMAC signature (5-minute replay window).
`403`	Publishable key supplied — initialize requires a secret key.
`404`	`order_id` provided but no matching order exists.
`409`	`provider_not_live` — the payment method is still configured with test credentials, so it cannot take a real payment. The merchant switches it to live mode in their dashboard. Sandbox requests are unaffected.
`409`	`idempotency_in_progress` — another request with the same `Idempotency-Key` is still being initialized. Retry shortly with the same key.
`429`	Rate limit exceeded (100 / hour per API key on initialize).
`500`	Upstream payment provider error or server configuration error.
`502`	`provider_unavailable` — a payment method the merchant added themselves did not complete the request. Retry, or offer another method.
`504`	`provider_timeout` — the provider did not respond in time. Safe to retry.

`verifyPayment`

Code	Meaning
`200`	Verification result returned. `status` field varies per provider — see shapes above.
`400`	Invalid request, or provider returned a validation error.
`401`	Invalid API key.
`403`	Publishable key supplied — verify requires a secret key.
`404`	No payment matches the `reference`.
`429`	Rate limit exceeded.
`500`	Server error.
`502`	`provider_unavailable` — a payment method the merchant added themselves did not complete the verification. The payment’s real state is unchanged; retry.
`504`	`provider_timeout` — the provider did not respond in time. Safe to retry.

`getPaymentMethods`

Code	Meaning
`200`	List of configured payment methods.
`400`	Invalid `fields` parameter.
`401`	Invalid API key.
`429`	Rate limit exceeded.
`500`	Server error.

Get Started

Core Commerce

Discovery

Checkout & Logistics

Agents

Marketplace

B2B (Wholesale)

Account & Support

System & Store

Integrations

🔐 Security & Signing (HMAC & Idempotency)

Signing & Idempotency Process

Code Implementation (TypeScript)

Methods

`getPaymentMethods`

`initializePayment`

`verifyPayment`

Response shape (per-provider `oneOf`)

Provider Support Matrix

Response Codes

`initializePayment`

`verifyPayment`

`getPaymentMethods`

​🔐 Security & Signing (HMAC & Idempotency)

​Signing & Idempotency Process

​Code Implementation (TypeScript)

​Methods

​getPaymentMethods

​initializePayment

​verifyPayment

​Response shape (per-provider oneOf)

​Provider Support Matrix

​Response Codes

​initializePayment

​verifyPayment

​getPaymentMethods

🔐 Security & Signing (HMAC & Idempotency)

Signing & Idempotency Process

Code Implementation (TypeScript)

Methods

`getPaymentMethods`

`initializePayment`

`verifyPayment`

Response shape (per-provider `oneOf`)

Provider Support Matrix

Response Codes

`initializePayment`

`verifyPayment`

`getPaymentMethods`