​
API Essentials

The Fermata API is located at https://api.gofermata.com

Authentication is done with HTTP Basic Authentication with your company ID in the username and your API key in the password.

Example:

​
Accounts

Billing a customer through Fermata requires your app to create an account in Fermata’s database. Emit an event when your customer uses your platform and Fermata will use the plan your setup in the platform to determine when to capture payment.

​
Create an account

Create a new account when a user registers.

POST /v1/companies/{company_id}/accounts

Payload
{
  "name": "John Smith",
  "email": "john@gofermata.com",
  "metadata": { "organization_id": 500 }, // Put whatever you want in here that you might want to track.
  "plan_id": "p_awer1234" // The ID of the plan to assign to the account
}

You’ll get a response back with a whole account object like this:

{
  "data": {
    "id": "a_4oh5nh06",
    "name": "John Smith",
    "email": "john@gofermata.com",
    "company_id": "c_1tlgsnhr",
    "plan_id": "p_awer1234",
    "plan_renewal_cadence": "MONTHLY",
    "billing_address_id": null,
    "stripe_id": "cus_Pay5IXbX1Waenk",
    "created_at": "2024-02-20 05:46:11.769107+00",
    "updated_at": null,
    "metadata": { "organization_id": 500 },
    "last_plan_renewal": null,
    "next_plan_renewal": null,
    "plan_status": "NONE"
  }
}

If you already have a Stripe account for the customer you can pass the Stripe customer id in the stripe_id parameter. If you leave this off, then we will create a Stripe customer for you in your Stripe account. If you have a Stripe card element generating tokens, you can pass that token in a token parameter to assign the card to this account.

We can gather credit card information for the account by generating a link that you can pass to your user which will present them with a whole credit card form. Pass in the parameter "enable_card_collector":1 and you’ll get back the URL on the output.

​
Send an event

Send events to Fermata to charge customer balances in real-time. The logic for how that event gets billed sits within Fermata so your app doesn’t need to do any calculations on transactions or balances. Or you can send a specific cost for the event to override any billing logic on our end.

POST /v1/accounts/{account_id}/events

{
  "type": "QUERY",
  "cost_override_amount": 1, // leave this and the next one out to do automatic billing
  "cost_override_denomination": "token",
  "gate_on_balance": true // Push will fail if not enough balance
}

The gate_on_balance parameter will cause the API call to response with a 402 error if the user doesn’t have enough balance to pay for the event. Fermata will keep track of the gated event in a separate location for record keeping purposes but their balance will not be charged. If you don’t specify the gate_on_balance parameter then every event will be billed and the user will be allowed to go into a negative balance. Fermata will notify your system via webhooks if you have those configured.

Also note, you’re unlimited in the number of events you send to Fermata so you can do things like capture all events you may want to bill against, but only bill against those that are configured in plans.

​
View Events

To view all events on your company:

GET /v1/companies/{company_id}/events

​
Change plan

Fermata handles all the calculations required for mid-cycle plan upgrades.

To change a plan:

POST /v1/accounts/{account_id}/changeplan

{
  "plan_id": "p_zxcv3456"
}

​
Webhooks

Fermata supports registering multiple webhooks for an account that can subscribe to various events so that your system will be alerted in realtime when important things happen.

First register a URL with us:

POST /v1/companies/{company_id}/webhooks

{
  "url": "https://api.yourwebsite.com/billing/webhooks",
  "username": "fermata",
  "password": "somepassw0rd"
}

The response will have the webhook ID starting with w_.

The username and password are used to prevent anyone from spoofing our requests. Fermata will send those with HTTP Basic Authentication on every request.

Once you have the webhook ID, you can subscribe the webhook to various events.

POST /v1/companies/{company_id}/webhooks/{webhook_id}/subscribe/{topic}

An example of a topic would be pause_balance to indicate that the user is out of balance on an account.

A webhook payload to your application would look something like this:

{
  "webhook_id": "w_er46th52",
  "topic": "pause_balance",
  "account_id": "a_4oh5nh06",
  "denomination": "tokens",
  "balance": "-2"
}
Capturing Payment