Skip to main content
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:
  1. A Credibill account. Sign up here.
  2. A live application created in the Developer Dashboard.
  3. 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. 
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>
  );
}
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.

​
3. Subscribe the Customer

Now, subscribe the customer to a plan. Ensure you have created a plan in your dashboard first. 
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>
  );
}

​
4. Handle Webhooks (Optional)

Set up webhooks to receive real-time updates about payments and subscriptions. 
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>
  );
}

​
Next Steps

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