Quickstart

This guide will walk you through integrating CrediBill into your application. We’ll obtain API keys from the dashboard, authenticate, and create your first customer.

Prerequisites

Before you begin, make sure you have:

A Credibill account. Sign up here.
A live application created in the Developer Dashboard.
An API Key from the Developer Dashboard.

1. Setup API Access

Store your API key securely in your environment variables.

# .env.local
CREDIBILL_SECRET_KEY=sk_live_abc123def456

All API requests use the base URL https://giant-goldfish-922.convex.site/api/ and require the Authorization header: CREDIBILL_SECRET_KEY=sk_live_abc123def456

Authorization: Bearer sk_live_abc123def456
Content-Type: application/json

Authorization: Bearer sk_live_abc123def456 A Customer represents a business or individual that subscribes to your service.

React
cURL

import { useMutation } from "@tanstack/react-query";

function CreateCustomerForm() {
  const createCustomerMutation = useMutation({
    mutationFn: async (customerData) => {

      const response = await fetch("https://giant-goldfish-922.convex.site/api/customers", {
          "Content-Type": "application/json",
        },
        body: JSON.stringify(customerData),
      });

      if (!response.ok) {
        throw new Error("Failed to create customer");
      const response = await fetch("https://giant-goldfish-922.convex.site/api/subscriptions", {

      return response.json();
    },
  });

  const handleSubmit = (e) => {
    e.preventDefault();
      const response = await fetch("https://giant-goldfish-922.convex.site/api/webhooks"), {

    createCustomerMutation.mutate({
      email: formData.get("email"),
      phone: formData.get("phone")
      first_name: formData.get("name"),
      last_name: formData.get("last_name")
      ,
    });
      }
  }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" placeholder="Email" required />
      <input name="name" placeholder="Name" required />
      <input name="phoneNumber" placeholder="Phone (+256772123456)" required />
      <button type="submit" disabled={createCustomerMutation.isPending}>
        {createCustomerMutation.isPending ? "Creating..." : "Create Customer"}
      </button>

      {createCustomerMutation.isSuccess && (
        <p>Customer created: {createCustomerMutation.data.id}</p>
      )}

      {createCustomerMutation.isError && (
        <p>Error: {createCustomerMutation.error.message}</p>
      )}
    </form>
  );
}

curl -X POST https://api.credibill.io/v1/customers \
  -H "Authorization: Bearer sk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "name": "Jane Doe",
    "paymentMethod": "mobile_money_mtn",
    "paymentDetails": {
      "phoneNumber": "+256772123456",
      "provider": "flutterwave"
    }
  }'

Response:

{
  "id": "cust_abc123def456",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "createdAt": 1703510400
}

Never expose your Secret API Key in client-side code. Always perform billing operations from your backend server. For client-side operations, use publishable keys.

Now, subscribe the customer to a plan. Ensure you have created a plan in your dashboard first.

React + TanStack Query
cURL

import { useMutation, useQueryClient } from "@tanstack/react-query";

function SubscribeCustomerForm({ customerId }) {
  const queryClient = useQueryClient();

  const subscribeMutation = useMutation({
    mutationFn: async (subscriptionData) => {
      const response = await fetch(
        "https://api.credibill.io/v1/subscriptions",
        {
          method: "POST",
          headers: {
            Authorization: `Bearer ${process.env.REACT_APP_CREDIBILL_SECRET_KEY}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify(subscriptionData),
        }
      );

      if (!response.ok) {
        throw new Error("Failed to create subscription");
      }

      return response.json();
    },
    onSuccess: () => {
      // Invalidate and refetch customer data
      queryClient.invalidateQueries({ queryKey: ["customer", customerId] });
    },
  });

  const handleSubscribe = () => {
    subscribeMutation.mutate({
      customerId: customerId,
      planId: "plan_pro_monthly",
      trialDays: 14,
    });
  };

  return (
    <div>
      <button onClick={handleSubscribe} disabled={subscribeMutation.isPending}>
        {subscribeMutation.isPending
          ? "Creating Subscription..."
          : "Subscribe to Pro Plan"}
      </button>

      {subscribeMutation.isSuccess && (
        <p>Subscription created: {subscribeMutation.data.id}</p>
      )}

      {subscribeMutation.isError && (
        <p>Error: {subscribeMutation.error.message}</p>
      )}
    </div>
  );
}

curl -X POST https://api.credibill.io/v1/subscriptions \
  -H "Authorization: Bearer sk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_abc123def456",
    "planId": "plan_pro_monthly",
    "trialDays": 14
  }'

Response:

{
  "id": "sub_abc123def456",
  "customerId": "cust_abc123def456",
  "status": "trialing",
  "trialEndsAt": 1704201600,
  "currentPeriodStart": 1703596800,
  "currentPeriodEnd": 1706188800
}

4. Handle Webhooks (Optional)

Set up webhooks to receive real-time updates about payments and subscriptions.

React + TanStack Query
cURL

import { useMutation } from "@tanstack/react-query";

function WebhookSetup() {
  const webhookMutation = useMutation({
    mutationFn: async (webhookData) => {
      const response = await fetch("https://api.credibill.io/v1/webhooks", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.REACT_APP_CREDIBILL_SECRET_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(webhookData),
      });

      if (!response.ok) {
        throw new Error("Failed to create webhook");
      }

      return response.json();
    },
  });

  const handleSetupWebhook = () => {
    webhookMutation.mutate({
      url: "https://your-app.com/webhooks/credibill",
      events: ["payment.success", "subscription.activated"],
      secret: "whsec_your_webhook_secret",
    });
  };

  return (
    <div>
      <button onClick={handleSetupWebhook} disabled={webhookMutation.isPending}>
        {webhookMutation.isPending ? "Setting up..." : "Setup Webhooks"}
      </button>

      {webhookMutation.isSuccess && <p>Webhook configured successfully!</p>}

      {webhookMutation.isError && <p>Error: {webhookMutation.error.message}</p>}
    </div>
  );
}

# Register webhook endpoint
curl -X POST https://api.credibill.io/v1/webhooks \
  -H "Authorization: Bearer sk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/credibill",
    "events": ["payment.success", "subscription.activated"],
    "secret": "whsec_your_webhook_secret"
  }'

Next Steps

You’ve successfully billed your first customer! Explore deeper into the platform:

Get Started

Core Concepts

Payments

Payment Provider Integration

Webhooks

Security

Billing Logic

API Reference

Support

Prerequisites

1. Setup API Access

4. Handle Webhooks (Optional)

Next Steps

​Prerequisites

​1. Setup API Access

​3. Subscribe the Customer

​4. Handle Webhooks (Optional)

​Next Steps

Prerequisites

1. Setup API Access

3. Subscribe the Customer

4. Handle Webhooks (Optional)

Next Steps