Spectabill Checkouts

Spectabill checkouts is the way through which your SaaS solution interfaces with Spectabill. The process is aimed to be seamless so that most of the heavy lifting is done by Spectabill.

The process:

1. Customer interacts with your platform.
2. At the point of signing up, essential details are gathered for processing by the platform.
3. After initial backend processing, the platform will perform rrequests to Spectabill for the following:
   • Register customer with Spectabill. Customers and Products are at the center of reporting for Spectabill:

curl --location 'https://api.spectabill.com/v1/api/billing/customers' \
--header 'Content-Type: application/json' \
--header 'x-kc-token: XXXX.YYYY.ZZZZ' \
--header 'x-idempotency-id: 3478279-XXX-6365' \
--data-raw '{
    "identifier":"946739-long-id4537", 
    "first_name":"Franklin",
    "last_name":"Seth",
    "email":"franklinseth@mailinator.com"
    }'

• Initiate checkout session

    curl --location 'https://api.spectabill.com/v1/api/billing/checkout_sessions' \
--header 'Content-Type: application/json' \
--header 'x-idempotency-id: db6a4570-1a18-XXXX-ddb69568fd64' \
--header 'x-kc-token: XXX.YYYY.ZZZ' \
--data '{
    "customer": "e07713ab-39cc-42e7-ae3b-4ca3c22398ef",
    "product": "dba89ce0-e2a3-43b1-a9fc-89d4c2446a10",
    "expires_at": "2025-02-27T11:20:45.000Z",
    "action": "new_subscription",
    "selected_currency": 1,
    "selected_billing_cycle":"months-1"
}'

Note that you need to provide the target Spectabill product ID either from a previously stored reference or by querying Spectabill product APIs

You also need to provide a proper session expiry time, the default is 5 minutes from current time.

• Redirect customer - The response from the request above provides a checkout_session payload with an id . At this point redirect the customer to:

  https://app.spectabill.com/checkout/<session-id>

M-Ratiba Subscriptions

From this point onward (at least for the first release), the customer will be allowed to checkout securely through M-Ratiba.

Only the customer's phone number is required for this process. If the customer provides their M-Pesa pin in the prompt that appears on their phone, they will be officially enrolled for subscriptions to your product.

Spectabill then makes requests to the platform's registered callback for the following events:

• Subscription:
  • Renewal
  • Canceled
  • Paused
• Payment:
  • Completed
  • Failed
  • Canceled
• Refunds:
  • Initiated
  • Approved
  • Rejected
• Invoices:
  • Paid
  • Voided
  • Marked as uncollectable
  • Deleted