Documentation Index
Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
Use this file to discover all available pages before exploring further.
Billing Events
Billing events notify you when invoices are generated, paid, or overdue, and when crypto deposits are detected or confirmed on-chain. Subscribe to these events to automate billing workflows and avoid service interruptions.
All billing events share the same outer envelope:
{
"event": "BILLING_INVOICE_CREATED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": { ... }
}
BILLING_INVOICE_CREATED
When it fires
Fires when FYATU generates a new billing invoice for your business. Invoices are generated monthly on the first of each month. You can view and pay invoices in the FYATU portal under Billing.
Payload
{
"event": "BILLING_INVOICE_CREATED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-06-01T00:00:00Z",
"data": {
"invoiceId": "inv_01HXYZ1111ABCDEF0000",
"programId": "prg_01HXYZ9876ABCDEF0000",
"amountCents": 4999,
"currency": "USD",
"dueDate": "2026-06-15",
"status": "PENDING",
"lineItems": [
{ "description": "Monthly platform fee", "amountCents": 2999 },
{ "description": "Card issuance fees (12)", "amountCents": 1200 },
{ "description": "Transaction fees", "amountCents": 800 }
],
"createdAt": "2026-06-01T00:00:00Z"
}
}
Payload fields
| Field | Type | Description |
|---|
invoiceId | string | Unique invoice identifier |
programId | string | The program this invoice is for |
amountCents | integer | Total invoice amount in cents |
currency | string | Currency code (ISO 4217) |
dueDate | string | Payment due date (YYYY-MM-DD) |
status | string | Always PENDING at creation |
lineItems | array | Individual charges that make up the invoice |
lineItems[].description | string | Human-readable charge description |
lineItems[].amountCents | integer | Line item amount in cents |
createdAt | string | ISO 8601 creation timestamp |
Common use cases
- Notify your finance team that a new invoice is ready for payment
- Sync invoice data into your accounting software (QuickBooks, Xero, etc.)
- Trigger an automated payment if you use auto-pay
BILLING_INVOICE_PAID
When it fires
Fires when an invoice is fully paid — either via a crypto deposit that covered the invoice amount, or manually from the portal.
Payload
{
"event": "BILLING_INVOICE_PAID",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-06-05T14:00:00Z",
"data": {
"invoiceId": "inv_01HXYZ1111ABCDEF0000",
"programId": "prg_01HXYZ9876ABCDEF0000",
"amountCents": 4999,
"currency": "USD",
"status": "PAID",
"paidAt": "2026-06-05T14:00:00Z",
"paymentRef": "dep_01HXYZ2222ABCDEF1111"
}
}
Payload fields
| Field | Type | Description |
|---|
invoiceId | string | The paid invoice ID |
programId | string | The program this invoice was for |
amountCents | integer | Total amount paid in cents |
currency | string | Currency code |
status | string | Always PAID |
paidAt | string | ISO 8601 payment timestamp |
paymentRef | string | Reference to the payment transaction |
Common use cases
- Mark the invoice as paid in your accounting system
- Confirm that your CaaS service access remains uninterrupted
BILLING_INVOICE_OVERDUE
When it fires
Fires when an invoice passes its due date without being paid. Unpaid invoices may result in service restrictions — contact support if you need an extension.
Overdue invoices that remain unpaid for more than 7 days may result in program suspension. Set up webhook monitoring on this event to avoid service disruption.
Payload
{
"event": "BILLING_INVOICE_OVERDUE",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-06-16T00:00:00Z",
"data": {
"invoiceId": "inv_01HXYZ1111ABCDEF0000",
"programId": "prg_01HXYZ9876ABCDEF0000",
"amountCents": 4999,
"currency": "USD",
"dueDate": "2026-06-15",
"status": "OVERDUE",
"daysOverdue": 1
}
}
Payload fields
| Field | Type | Description |
|---|
invoiceId | string | The overdue invoice ID |
programId | string | The program this invoice is for |
amountCents | integer | Outstanding amount in cents |
currency | string | Currency code |
dueDate | string | Original due date (YYYY-MM-DD) |
status | string | Always OVERDUE |
daysOverdue | integer | Number of days past the due date |
Common use cases
- Send an urgent alert to your finance team
- Trigger an automated payment retry
- Log the overdue event for compliance and audit records
BILLING_DEPOSIT_DETECTED
When it fires
Fires when an inbound crypto transfer to your program’s deposit address is detected on-chain. The deposit is not yet credited — wait for BILLING_DEPOSIT_CONFIRMED before treating the funds as available.
This event is informational. Do not credit balances or mark invoices as paid based on BILLING_DEPOSIT_DETECTED. Always wait for BILLING_DEPOSIT_CONFIRMED.
Payload
{
"event": "BILLING_DEPOSIT_DETECTED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-06-05T13:58:00Z",
"data": {
"depositId": "dep_01HXYZ2222ABCDEF1111",
"amount": 49.99,
"currency": "USDT",
"network": "TRON",
"txHash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
"timestamp": "2026-06-05T13:58:00Z"
}
}
Payload fields
| Field | Type | Description |
|---|
depositId | string | Unique deposit identifier assigned by FYATU |
amount | number | Deposit amount (in dollars) |
currency | string | USDT or USDC |
network | string | TRON (TRC20) or ETH (ERC20) |
txHash | string | Blockchain transaction hash |
timestamp | string | ISO 8601 timestamp |
Common use cases
- Show a “Deposit incoming — awaiting confirmation” notice in your portal
- Log the transaction hash for reconciliation before it confirms
BILLING_DEPOSIT_CONFIRMED
When it fires
Fires when an incoming crypto deposit reaches 3 on-chain confirmations and has been credited to your program ledger. For deposits that match a pending invoice, the invoice is automatically marked as paid first; any surplus goes directly to the program balance.
Payload
{
"event": "BILLING_DEPOSIT_CONFIRMED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-06-05T14:00:00Z",
"data": {
"depositId": "dep_01HXYZ2222ABCDEF1111",
"programId": "prg_01HXYZ9876ABCDEF0000",
"amount": 100.00,
"balanceCents": 10250000,
"timestamp": "2026-06-05T14:00:00Z"
}
}
Payload fields
| Field | Type | Description |
|---|
depositId | string | Unique deposit identifier |
programId | string | The program that received the deposit |
amount | number | Deposit amount credited (in dollars) |
balanceCents | integer | Program ledger balance after this deposit (in cents) |
timestamp | string | ISO 8601 timestamp |
Common use cases
- Confirm that a deposit has been received and the program is funded
- Show an updated program balance in your portal dashboard
- Resume card funding operations that were paused due to low balance
Once you receive BILLING_DEPOSIT_CONFIRMED, the funds are immediately available for card funding. Check balanceCents to confirm the new available balance before issuing new loads.
