Skip to content

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

GET/invoices/info

Returns 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

GET/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

GET/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

GET/invoices/return

Page PayFast redirects the user to after a payment

Request

Auth: None

Request body:

None

Response

{
    "success": "Payment processed. Check your invoice status."
}

Payment cancel

GET/invoices/cancel

Page PayFast redirects the user to when a payment is cancelled

Request

Auth: None

Request body:

None

Response

{
    "success": "Payment cancelled."
}