Quickstart

This guide gets you up and running with the Commerce API. You'll install an SDK, configure your API key, and make your first successful request to confirm everything is set up correctly.

Install the SDK

Commerce provides official SDKs for all major languages. Pick your language and install the SDK:

# cURL comes pre-installed on most systems
curl --version

Configure your API key

Set your API key as an environment variable to keep it secure:

# Linux/macOS
export COMMERCE_API_KEY=sk_test_your_key_here

# Windows (PowerShell)
$env:COMMERCE_API_KEY="sk_test_your_key_here"

Or create a .env file in your project:

COMMERCE_API_KEY=sk_test_your_key_here

Important: Add .env to your .gitignore to avoid committing secrets:

.env
.env.local
.env.production

Make your first request

Let's create a simple order to verify your setup. The Commerce API accepts and returns JSON (application/json). All requests must include your API key in the Authorization header as a bearer token.

curl https://api.zebo.dev/orders/new \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_data": {
      "name": "Akua Mensah",
      "phone_number": "+233544998605"
    },
    "payment_method_data": {
      "type": "mobile_money",
      "mobile_money": {
        "issuer": "mtn",
        "number": "0544998605"
      }
    },
    "line_items": [
      {
        "type": "product",
        "product": {
          "name": "Monthly Subscription",
          "price": {
            "currency": "ghs",
            "value": 5000
          },
          "quantity": 1
        }
      }
    ]
  }'

If the request succeeds, you'll receive a JSON response with the created order, including an order.id. This confirms your API key is valid and your environment is configured correctly.

What's next?

Great! You've successfully made your first API request. Now you're ready to integrate Commerce into your application. Here's where to go next:

Learn the fundamentals

• Authentication - How API keys, sessions, and security work
• Orders API - Complete reference for the Orders endpoint
• Errors - How to handle error responses

Build payment flows

These guides walk you through complete payment scenarios:

• Accept a payment - Complete guide to accepting one-time payments
• Charge repeat customers - Use saved payment methods for faster checkout
• Order now, pay later - Create orders without immediate payment
• Charge a different payment method - Handle payment retries and failures

Test your integration

Use test mode credentials for development:

• Test API key: sk_test_... (get yours from the dashboard)
• Test phone number: 0242000003 (MTN test number)
• Test OTP: 000000 (always works in test mode)

Test mode creates real Commerce resources but doesn't process actual payments. All test data is isolated from production.

Go to production

When you're ready to accept real payments:

1. Switch to your production API key (sk_live_...)
2. Test with real payment methods in production mode
3. Set up webhook endpoints for payment notifications
4. Monitor transactions in the Commerce dashboard

Get help

• Documentation - Browse the full API reference
• Dashboard - Manage API keys and view transactions
• Support - Contact us at support@zebo.dev

You're all set! Start building your integration with the Commerce API.