Credits & Billing

Credits are deducted each time you perform a billable action — submitting an invoice, verifying a TIN, creating a buyer, and so on. Your plan allocates monthly credits, and you can purchase more as needed.

How credits work

Every API action that costs credits is listed in the public credit cost catalog. You can fetch it at any time:

bash

curl https://gateway.useyona.com/b/v1/plans/credit-costs

Here are the current costs:

Action	Credits	What it does
Create invoice	1	Draft an invoice in the system
Submit invoice	5	Submit to the tax authority
Validate invoice	1	Validate against jurisdiction rules without saving
Query invoice status	1	Poll the tax authority for latest status
Cancel invoice	3	Cancel by issuing a credit note
Download invoice PDF	1	Generate a signed PDF
Add a seller	1	Register a seller party
Add a buyer	1	Register a buyer party
Verify tax number	2	Verify a TIN with the tax authority
Taxpayer lookup	1	Look up a taxpayer in the tax authority directory
Send SMS	1	Send an SMS (2FA, OTP, alerts)
Webhook delivery	1	Deliver a webhook event to your endpoint
Bulk report export	1	Export a large CSV/spreadsheet report

💡 Costs may change

Credit costs are read from the server at request time and may be adjusted. Always fetch the catalog programmatically rather than hardcoding values.

Credit pools

Pool	Description
`subscriptionCredits`	Allocated monthly by your plan
`paygCredits`	Purchased as one-time packages
`creditBalance`	`subscriptionCredits` + `paygCredits`

Subscription credits are consumed first, then PAYG credits.

Plans

Plan	Monthly credits
Free	200
Starter	5,000
Professional	25,000
Business	50,000

The Free plan is sandbox-only (liveApiAccess: false). You need a paid plan to submit real invoices.

Checking your balance

bash

curl https://gateway.useyona.com/b/v1/billing-accounts/me \
  -H "Authorization: Bearer sk_test_your_key_here"


{
  "data": {
    "creditBalance": 4200,
    "subscriptionCredits": 4000,
    "paygCredits": 200
  }
}

Purchasing credits

bash

curl -X POST https://gateway.useyona.com/b/v1/payments/purchase \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "packageId": "pkg_1000_credits", "currency": "NGN" }'

The response includes a checkoutUrl — redirect the user there to complete payment.

Credit transfers (B2B2B)

Parent organizations can transfer PAYG credits to child orgs:

bash

curl -X POST https://gateway.useyona.com/b/v1/payments/transfer \
  -H "Authorization: Bearer sk_live_partner_key" \
  -H "Content-Type: application/json" \
  -d '{
    "targetOrganizationId": "e5f6a7b8-c9d0-1234-5678-90abcdef1234",
    "amount": 1000,
    "description": "Monthly credit allocation"
  }'

Both organizations must be in payg or hybrid billing mode.

Low balance alerts

Set up a webhook for billing_account.low_balance to get notified when your balance drops below a threshold.

💡 SDK available

See SDK — Billing for the programmatic interface.