Invoices & billing¶
Invoices are created monthly for each account. An invoice holds the base price of the account type plus charges for API calls above the account's included calls; 15% VAT is added to the total. Payment is made through PayFast: the dashboard reads the payment details with Pay invoice and submits them to PayFast, which redirects the user back to the return or cancel URL.
Invoice status (status):
| Value | Meaning |
|---|---|
| unpaid | Created, not yet paid |
| pending | Payment started, not yet confirmed |
| paid | Payment completed |
| failed | Payment failed |
Account types:
| account_type | Name | Included API calls | Price per extra call (ZAR) |
|---|---|---|---|
| 1 | Basic (Free) | 200 000 | 0.015 |
| 2 | Start-up | 1 000 000 | 0.013 |
| 3 | Growth | 6 000 000 | 0.013 |
| 4 | Premium | unlimited | 0.011 |
| 5 | Enterprise | unlimited | 0 |
Get invoices¶
/invoices/infoReturns all invoices of the user
Request¶
Auth: api_key (query param or cookie)
Request body:
None
Request example:
https://spoilerinterface.com/interface/invoices/info?api_key=8f14e45fceea167a5a36dedd4bea2543
Response¶
{
"success": [
{
"invoice_id": "6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
"period_start": "2024-04-01T00:00:00",
"period_end": "2024-04-30T23:59:59",
"base_price": "30.0",
"call_charges": "0.0",
"created_at": "2024-05-01T00:05:00",
"due_date": "2024-05-15T00:00:00",
"amount": 30.0,
"status": "unpaid",
"first_name": "Jane",
"last_name": "Doe",
"email_address": "user@example.com",
"api_calls": 15230,
"per_call_price": 0.013,
"m_payment_id": "6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
"total_with_tax": "34.50",
"item_name": "Invoice 6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
"max_number_of_calls": 1000000
}
]
}
Field description¶
| Field name | Description | Type |
|---|---|---|
| invoice_id | Invoice ID | str |
| period_start / period_end | Billing period | str |
| base_price | Base price of the account type for the period (ZAR) | str |
| call_charges | Charges for API calls above the included calls (ZAR) | str |
| created_at | Creation date | str |
| due_date | Payment due date | str |
| amount | Invoice amount (ZAR) | float |
| status | Invoice status (see table above) | str |
| first_name / last_name / email_address | Account holder | str |
| api_calls | API calls recorded on the account | int |
| per_call_price | Price per extra API call (ZAR) | float |
| m_payment_id | Payment reference (same as invoice_id) |
str |
| total_with_tax | base_price + call_charges plus 15% VAT, two decimals |
str |
| item_name | Payment item name | str |
| max_number_of_calls | API calls included in the account type | int |
When the user has no invoices the response is {"failed": "No invoices found"}.
Get invoice¶
/invoices/info/{invoice_id}Returns a single invoice of the user
Request¶
Auth: api_key (query param or cookie)
Request body:
None. {invoice_id} is the invoice ID.
Request example:
https://spoilerinterface.com/interface/invoices/info/6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f?api_key=8f14e45fceea167a5a36dedd4bea2543
Response¶
An array with one invoice, using the same fields as Get invoices:
{
"success": [
{
"invoice_id": "6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
"period_start": "2024-04-01T00:00:00",
"period_end": "2024-04-30T23:59:59",
"base_price": "30.0",
"call_charges": "0.0",
"created_at": "2024-05-01T00:05:00",
"due_date": "2024-05-15T00:00:00",
"amount": 30.0,
"status": "unpaid",
"first_name": "Jane",
"last_name": "Doe",
"email_address": "user@example.com",
"api_calls": 15230,
"per_call_price": 0.013,
"m_payment_id": "6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
"total_with_tax": "34.50",
"item_name": "Invoice 6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
"max_number_of_calls": 1000000
}
]
}
An unknown invoice, or one belonging to another user, returns {"failed": "Invoice not found."}.
Pay invoice¶
/invoices/pay/{invoice_id}Returns the PayFast payment fields for an invoice
Request¶
Auth: None (identified by invoice_id)
Request body:
None. {invoice_id} is the invoice ID.
Request example:
https://spoilerinterface.com/interface/invoices/pay/6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f
Response¶
{
"success": {
"merchant_id": "<PAYFAST_MERCHANT_ID>",
"merchant_key": "<PAYFAST_MERCHANT_KEY>",
"return_url": "https://spoilerinterface.com/interface/invoices/return",
"cancel_url": "https://spoilerinterface.com/interface/invoices/cancel",
"notify_url": "https://spoilerinterface.com/interface/invoices/notify",
"first_name": "Jane",
"last_name": "Doe",
"email_address": "user@example.com",
"api_calls": 15230,
"per_call_price": 0.013,
"m_payment_id": "6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
"total_with_tax": "34.50",
"item_name": "Invoice 6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
"payfast_url": "https://spoilerinterface.com/dashboard/invoices?invoice_id=6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
"max_number_of_calls": 1000000,
"item_description": "Payment for Start-up account, 15230 API calls"
}
}
Field description¶
| Field name | Description | Type |
|---|---|---|
| merchant_id / merchant_key | PayFast merchant credentials configured on the server | str |
| return_url / cancel_url / notify_url | URLs PayFast redirects or posts to after payment | str |
| m_payment_id | Payment reference (the invoice ID) | str |
| total_with_tax | Amount to pay (ZAR, incl. 15% VAT) | str |
| item_name / item_description | Payment description shown by PayFast | str |
| payfast_url | Dashboard page for the invoice | str |
Failures: Invoice not found., User information not found, Failed to get invoice details.
The invoice status is updated by PayFast's server-to-server notification to notify_url, not by the endpoints on this page.
Payment return¶
/invoices/returnPage PayFast redirects the user to after a payment
Request¶
Auth: None
Request body:
None
Response¶
Payment cancel¶
/invoices/cancelPage PayFast redirects the user to when a payment is cancelled
Request¶
Auth: None
Request body:
None