Billing

CastBrick uses a pre-paid credit system. You purchase an SMS pack, and each message sent deducts from your balance. Credits never expire.

Get balance

GET /billing/balance

Returns your current SMS credit balance and low-balance alert settings.

Response `200`

{
  "balance": 1850.00,
  "lowBalanceThreshold": 200.00,
  "alertEmail": "admin@yourapp.com",
  "lastAlertSentAt": "2026-05-01T08:00:00Z"
}

Field	Description
`balance`	Current balance in SMS credits
`lowBalanceThreshold`	Alert is triggered when balance falls below this value
`alertEmail`	Email that receives low-balance notifications
`lastAlertSentAt`	When the last low-balance alert was sent

Code sample

curl https://api.castbrick.co/v1/billing/balance \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

List packages

GET /billing/packages

Returns the available SMS credit packs. No authentication required.

Response `200`

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Starter",
    "credits": 500,
    "price": 10.00,
    "currency": "AOA",
    "pricePerSms": 0.020
  },
  {
    "id": "4ab96e75-6828-573d-c4gd-3d3d74h77bfb",
    "name": "Growth",
    "credits": 2000,
    "price": 10.00,
    "currency": "AOA",
    "pricePerSms": 0.005
  },
  {
    "id": "5bc07f86-7939-684e-d5he-4e4e85i88cgc",
    "name": "Scale",
    "credits": 20000,
    "price": 190.00,
    "currency": "AOA",
    "pricePerSms": 0.0095
  }
]

Code sample

curl https://api.castbrick.co/v1/billing/packages

Initiate a payment

POST /billing/payments/initiate

Starts a payment session to purchase an SMS pack. Returns a redirect URL to complete the payment.

Request body

{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "provider": "Stripe",
  "method": "Card",
  "currency": "USD",
  "returnUrl": "https://yourapp.com/billing",
  "cancelUrl": "https://yourapp.com/billing/cancel",
  "successUrl": "https://yourapp.com/billing/success",
  "failureUrl": "https://yourapp.com/billing/failure"
}

Field	Type	Required	Description
`packageId`	`UUID`	Yes	ID of the package to purchase
`provider`	`string`	Yes	Payment provider: `Stripe`
`method`	`string`	Yes	Payment method: `Card`
`currency`	`string`	Yes	ISO 4217 currency code (e.g. `USD`, `AOA`)
`returnUrl`	`string`	Yes	URL user is redirected to after payment attempt
`cancelUrl`	`string`	Yes	URL if user cancels
`successUrl`	`string`	Yes	URL after successful payment
`failureUrl`	`string`	Yes	URL after failed payment

Response `200`

{
  "paymentUrl": "https://checkout.stripe.com/c/pay/cs_live_...",
  "providerRef": "cs_live_a1b2c3d4",
  "paymentId": "pay-uuid"
}

Redirect the user to paymentUrl to complete the purchase.

Code sample

curl -X POST https://api.castbrick.co/v1/billing/payments/initiate \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "provider": "Stripe",
    "method": "Card",
    "currency": "USD",
    "returnUrl": "https://yourapp.com/billing",
    "cancelUrl": "https://yourapp.com/billing/cancel",
    "successUrl": "https://yourapp.com/billing/success",
    "failureUrl": "https://yourapp.com/billing/failure"
  }'

List payments

GET /billing/payments

Returns your payment history with optional filters.

Query parameters

Parameter	Default	Description
`cursor`	—	Pagination cursor from the previous response
`limit`	`50`	Results per page
`status`	—	Filter: `pending`, `completed`, `failed`, `refunded`
`from`	—	Start date (ISO 8601)
`to`	—	End date (ISO 8601)

Code sample

curl "https://api.castbrick.co/v1/billing/payments?limit=20&status=completed" \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

List transactions

GET /billing/transactions

Returns a credit ledger — every debit (message sent) and credit (top-up) on your account.

Query parameters

Parameter	Default	Description
`cursor`	—	Pagination cursor

Code sample

curl https://api.castbrick.co/v1/billing/transactions \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxx"

Credit consumption

Each SMS message sent deducts credits from your balance:

Scenario	Credits used
1 SMS (1 segment, 1 recipient)	1
1 SMS (2 segments, 1 recipient)	2
1 broadcast to 1,000 contacts	1,000
1 broadcast to 1,000 contacts, 2 segments	2,000

A segment is 160 characters for GSM-7 encoding or 70 characters for UCS-2 (unicode). Messages over one segment are split and billed per segment.

Billing

On this page