Implement a per-transaction pricing model like Stripe, the leading payments infrastructure company, including fees based on the total amount and number of transactions. In this article, you will learn how to build a per-transaction billing system with Lago, where a single event can trigger instant charges. This template is suitable for companies whose pricing depends on transactions, such as fintechs and marketplaces that deduct their fees from their customers’ revenue.

Pricing structure

Stripe offers “pay-as-you-go” pricing based on successful card charges processed via its platform. Stripe’s API includes many payment options. Rates and fixed fees per transaction vary depending on the payment method.
Payment MethodPercentage Charge (based on transaction amount)Fixed Fee (per transaction)
Card payments (online)2.9%$0.30
Card payments (in-person)2.7%$0.05
As Stripe supports more 20 payment methods in the US and most of them share the same charge model, we will focus on card payments.

Get started

1

Set up Lago

LAGO_URL="https://api.getlago.com"
API_KEY="__API_KEY__"
2

Create a billable metric

Create a billable metric to track transaction usage for each payment method.
  1. Set the aggregation_type to sum_agg to sum transaction amounts
  2. Set the field_name to amount to track transaction values
  3. Add a unique code for your billable metric
  4. Configure filters to distinguish between payment types
curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "billable_metric": {
      "name": "Transaction Amount",
      "code": "__BILLABLE_METRIC_CODE__",
      "description": "Total amount of transactions processed",
      "aggregation_type": "sum_agg",
      "field_name": "amount",
      "filters": [
        {
          "key": "type",
          "values": ["online", "in-person"]
        }
      ]
    }
  }'
Refer to the API reference and guide on filters to learn more.
3

Create a plan

Create a plan with percentage-based charges that are paid in advance.
  1. Set the amount_cents to 0 since there is no subscription fee
  2. Configure charge_model to percentage for percentage-based pricing
  3. Enable pay_in_advance for instant charging
  4. Set invoiceable to false to avoid creating invoices for the charges
  5. Set charges with different rates for online vs in-person payments
curl --location --request POST "$LAGO_URL/api/v1/plans" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "plan": {
      "name": "Payment Processing Plan",
      "code": "__PLAN_CODE__",
      "description": "Per-transaction pricing for payment processing",
      "amount_cents": 0,
      "amount_currency": "USD",
      "pay_in_advance": true,
      "charges": [
        {
          "billable_metric_id": "__BILLABLE_METRIC_ID__",
          "invoice_display_name": "Online Card Payment",
          "charge_model": "percentage",
          "invoiceable": false,
          "filters": [
            {
              "invoice_display_name": "Online Card Payment",
              "values": { "type": ["online"] },
              "properties": {
                "rate": "2.9",
                "fixed_amount": "0.30"
              }
            },
            {
              "invoice_display_name": "In-person Card Payment",
              "values": { "type": ["in-person"] },
              "properties": {
                "rate": "2.7",
                "fixed_amount": "0.05"
              }
            }
          ]
        }
      ]
    }
  }'
Refer to the API reference and guide on percentage charges to learn more.
4

Create a customer

Create a customer with a unique external_id.
curl --location --request POST "$LAGO_URL/api/v1/customers" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customer": {
      "external_id": "__EXTERNAL_CUSTOMER_ID__",
      "name": "Acme Inc",
      "email": "john@acme.com",
      "currency": "USD",
      "timezone": "America/New_York"
    }
  }'
Refer to the API reference to create a customer.
5

Create a subscription

Create a subscription for the customer with the plan’s code.
curl --location --request POST "$LAGO_URL/api/v1/subscriptions" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "subscription": {
      "external_customer_id": "__EXTERNAL_CUSTOMER_ID__",
      "plan_code": "__PLAN_CODE__",
      "external_id": "__EXTERNAL_SUBSCRIPTION_ID__"
    }
  }'
Refer to the API reference to create a subscription.Refer to API reference and guide on assigning plans in the documentation.
6

Ingest transactions via events

Send transaction events to Lago for instant processing and charging.
  1. Set the code to match your billable metric code
  2. Use external_customer_id to identify the customer
  3. Include amount in properties for the transaction value
  4. Add type property to specify online or in-person payment
curl --location --request POST "$LAGO_URL/api/v1/events" \
 --header "Authorization: Bearer $API_KEY" \
 --header 'Content-Type: application/json' \
 --data-raw '{
   "event": {
     "transaction_id": "__TRANSACTION_ID__",
     "code": "__BILLABLE_METRIC_CODE__",
     "external_subscription_id": "__EXTERNAL_SUBSCRIPTION_ID__",
     "properties": {
       "amount": 200,
       "type": "online"
     }
   }
 }'
Refer to the API reference to create an event.
7

Estimate fees for future transactions

Calculate transaction fees before processing to show users expected costs.
  1. Use external_subscription_id to identify the subscription
  2. Set the code to match your billable metric code
  3. Include amount for the transaction value to estimate
  4. Add type to get accurate rates for payment method
curl --location --request POST "$LAGO_URL/api/v1/events/estimate_fees" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "event": {
      "external_subscription_id": "__EXTERNAL_SUBSCRIPTION_ID__",
      "code": "__BILLABLE_METRIC_CODE__",
      "properties": {
        "amount": 1200,
        "type": "online"
      }
    }
  }'
Refer to the API reference to estimate fees.

Wrap-up

For fintech companies like Stripe, implementing a per-transaction pricing model is a good way to increase revenue as customers grow and capture value everytime a transaction is processed. With Lago, you can create your own billable metrics and use the percentage charge model paid instantly to adapt this template to your products and services. Give it a try, click here to get started!