API Documentation v1.0

Overview

secure.checkout.best provides a complete checkout infrastructure for e-commerce platforms. It handles payment processing via Stripe Connect, inventory management with row-level locking, and provides embeddable widgets for any website.

Base URL

https://secure.checkout.best

Integration Flow

Authentication

Internal API (app.buildmyonlinestore.com)

All internal API endpoints require the X-Internal-Secret header:

X-Internal-Secret: your_internal_api_secret

Consumer Authentication

Consumer endpoints use JWT Bearer tokens:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

GFAVIP SSO (Merchants)

Merchant authentication flows through GFAVIP Simple SSO. Include the token in internal API calls:

X-GFAVIP-Token: gfavip_token_here

Quick Start Guide

For app.buildmyonlinestore.com

When a merchant creates a store, provision it in secure.checkout.best:

POST /api/internal/stores
Content-Type: application/json
X-Internal-Secret: your_secret

{
  "name": "My Store",
  "catalog_id": "550e8400-e29b-41d4-a716-446655440000",
  "gfavip_user_id": "user_123",
  "email": "merchant@example.com",
  "webhook_url": "https://app.buildmyonlinestore.com/webhooks/checkout"
}

For db.51exports.com

secure.checkout.best proxies product data from your catalog API:

GET /api/v1/products/{catalog_id}/{sku}
# Proxies to: db.51exports.com/api/products/{catalog_id}/{sku}

Store Management

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "merchant_id": "550e8400-e29b-41d4-a716-446655440002",
  "name": "My Store",
  "catalog_id": "550e8400-e29b-41d4-a716-446655440000",
  "stripe_account_id": "acct_1234567890",
  "brand_color": "#3b82f6",
  "created_at": "2025-11-25T12:00:00Z"
}

Widget Integration

Add the checkout widget to any website with a single script tag:

<script src="https://secure.checkout.best/widget.js" data-store="YOUR_STORE_ID"></script>

Add to Cart Buttons

Opens the cart overlay and adds the product:

<button class="checkout-best-add" 
        data-sku="PROD-001" 
        data-name="Product Name" 
        data-price="19.99">
  Add to Cart
</button>

Buy Now Buttons

Adds the product and immediately proceeds to checkout:

<button class="checkout-best-buy" 
        data-sku="PROD-001" 
        data-name="Product Name" 
        data-price="19.99">
  Buy Now
</button>

Button Classes

Button Data Attributes

JavaScript API

// Add item programmatically
CheckoutBest.addToCart({
  sku: 'PROD-001',
  name: 'Product Name',
  price_cents: 1999,
  quantity: 1,
  image_url: 'https://example.com/image.jpg'
});

// Open cart overlay
CheckoutBest.openCart();

// Get cart contents
const cart = CheckoutBest.getCart();

// Clear cart
CheckoutBest.clearCart();

Checkout Sessions

{
  "store_id": "550e8400-e29b-41d4-a716-446655440001",
  "cart": [
    {
      "sku": "PROD-001",
      "name": "Product Name",
      "price_cents": 1999,
      "quantity": 2,
      "image_url": "https://example.com/image.jpg",
      "catalog_id": "cat_001",
      "catalog_owner_id": "user_xyz",
      "product_cost_cents": 1200
    }
  ],
  "metadata": {
    "source": "chatgpt",
    "conversation_id": "conv_abc123",
    "agent_type": "acp"
  }
}

{
  "session_id": "550e8400-e29b-41d4-a716-446655440003",
  "checkout_url": "https://secure.checkout.best/checkout/gAAAAABk...",
  "expires_at": "2025-11-26T12:00:00Z",
  "source": "chatgpt"
}

Products API

Product data is proxied from db.51exports.com with 60-second caching.

Inventory Management

Inventory operations use row-level database locking to prevent overselling.

{
  "session_id": "550e8400-e29b-41d4-a716-446655440003",
  "catalog_id": "550e8400-e29b-41d4-a716-446655440000",
  "items": [
    { "sku": "PROD-001", "quantity": 2 },
    { "sku": "PROD-002", "quantity": 1 }
  ]
}

{
  "success": true,
  "reservations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440005",
      "sku": "PROD-001",
      "quantity": 2,
      "status": "reserved"
    }
  ]
}

Payments

{ "order_id": "550e8400-e29b-41d4-a716-446655440004" }

{
  "client_secret": "pi_xxx_secret_xxx",
  "payment_intent_id": "pi_xxx",
  "amount": 3998,
  "currency": "usd"
}

Webhooks

Stripe Webhook

Order Sync Webhook (to app.buildmyonlinestore.com)

When an order is paid, we POST to the store's webhook_url:

POST {store.webhook_url}
Content-Type: application/json
X-Webhook-Source: checkout.best

{
  "event": "order.paid",
  "order_id": "550e8400-e29b-41d4-a716-446655440004",
  "store_id": "550e8400-e29b-41d4-a716-446655440001",
  "total_cents": 3998,
  "currency": "usd",
  "customer_email": "customer@example.com",
  "items": [
    {
      "sku": "PROD-001",
      "name": "Product Name",
      "quantity": 2,
      "price_cents": 1999,
      "catalog_id": "cat_001",
      "catalog_owner_id": "user_xyz",
      "product_cost_cents": 1200
    }
  ],
  "shipping_address": { ... },
  "source": "chatgpt",
  "conversation_id": "conv_abc123",
  "created_at": "2025-11-25T12:30:00Z"
}

Webhook Item Fields

Webhook Metadata Fields

Error Handling

All errors return JSON with consistent format:

{
  "error": "Human-readable error message",
  "error_code": "MACHINE_READABLE_CODE"
}

Common Error Codes

Rate Limits