Appearance
paystack
13 endpoints.
GET /api/v1/settings/paystack
Get Paystack
The site's Paystack settings, secret key withheld.
200 — Successful Response
json
{}PUT /api/v1/settings/paystack
Update Paystack
Upsert the Paystack settings, then return the refreshed (masked) view.
Request body
json
{
"properties": {
"public_key": {
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
],
"title": "Public Key"
},
"secret_key": {
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
],
"title": "Secret Key"
},
"currency": {
"anyOf": [
{
"type": "string",
"maxLength": 8
},
{
"type": "null"
}
],
"title": "Currency"
},
"subaccount": {
"anyOf": [
{
"type": "string",
"maxLength": 64
},
{
"type": "null"
}
],
"title": "Subaccount"
},
"disabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Disabled"
}
},
"type": "object",
"title": "PaystackIn",
"description": "Partial update for the site's Paystack settings. A field omitted\n(``None``) is left untouched; an empty string clears that field."
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/settings/paystack/test
Test Paystack
Live-check the currently-saved secret key against the Paystack API (a lightweight, read-only call). Charges nothing. Returns {ok, detail}.
200 — Successful Response
json
{}GET /api/v1/paystack/pay/{token}
Paystack Pay Link
Public "Pay Now" link embedded in the invoice PDF/email (see app.apps.erp.services.accounting_pdf) — no login required. The invoice is looked up by its opaque, unguessable pay_token (see :func:app.apps.erp.services.accounting_payment_paystack.ensure_pay_token); that token IS the authorization, exactly like an Invitation.token link. Starts a fresh Paystack checkout on every click (so the link never goes stale, unlike a baked-in checkout URL) and redirects the browser to it — for the customer's amount due (their positive GL balance, matching the ageing total shown on the PDF), not this one invoice's own figure: the invoice only identifies whose account to settle.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
token | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/paystack/account-return
Paystack Account Return
Where Paystack sends the payer back after an account "Pay Now" / "Debit Order" checkout (it appends ?trxref=…&reference=…). Books the payment right here, before redirecting on to /portal, so a paid account is settled — and unsuspended by the receipt's submit — the moment the payer returns, not whenever a webhook arrives (2026-10-13: the hub's webhook had stopped receiving anything). Never blocks the redirect: any failure is left to the webhook and the paystack_account_settle sweep.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
reference | query | no | ||
trxref | query | no |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/paystack/debit-order/{token}
Paystack Debit Order Link
Public "Debit Order" signup link embedded in the invoice PDF/email — the exact same Paystack checkout as :func:paystack_pay_link (collects the customer's amount due), except the transaction is flagged debit_order so the webhook vaults the returned authorization code as a standing debit-order mandate (last_source="debit_order") for future off-session charges.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
token | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/paystack/pay-statement/{token}
Paystack Pay Statement Link
Public "Pay Now" link embedded in the Statement of Account PDF/web view — a one-time charge of the customer's amount due, no standing mandate. Looked up by statement_token (the statement web view's own token, see :mod:app.api.public_documents) instead of an invoice pay_token. Sibling of :func:paystack_pay_statement_debit_order_link, which is the same checkout with debit_order=True.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
token | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/paystack/debit-order-statement/{token}
Paystack Pay Statement Debit Order Link
Public "Pay Now & Auto-Charge Monthly" link embedded in the Statement of Account PDF/email — looked up by the customer's statement_token (the statement web view's own token, see :mod:app.api.public_documents) instead of an invoice pay_token. Same checkout + settlement as :func:paystack_pay_statement_link above: the customer's amount due (positive GL balance — exactly the statement's closing figure) — except the transaction is flagged debit_order so the webhook also vaults the returned authorization code as a standing mandate for future off-session monthly charges.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
token | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/paystack/save-card/{token}
Paystack Save Card Page
Public "Add Card" link (emailed by card_on_file — the activation gate, the abandoned-checkout chase, and Customers → Send Paystack Link Request). A short page that says plainly what is about to happen — a small charge, refunded at once, and the card kept for the monthly debit order — before the customer is sent to Paystack. That page IS the debit-order consent, which is why this is not a straight redirect like the pay links.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
token | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/paystack/save-card/{token}/start
Paystack Save Card Start
The consent page's button — starts the Save Card checkout (:func:app.apps.erp.services.card_on_file.init_card_save) and redirects to Paystack.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
token | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/paystack/save-card/{token}/done
Paystack Save Card Done
Where Paystack returns the customer. Verifies the charge with Paystack and settles it here and now (vault + refund), so the card is saved even when the webhook never arrives. Safe alongside the webhook: a refunded charge is no longer success, so whichever runs second does nothing.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
token | path | yes | string | |
reference | query | no | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/paystack/pay-quote/{token}
Paystack Pay Quote Link
Public "Pay Now" deposit link embedded in a Quotation/Sales Order PDF/email (see app.apps.erp.services.accounting_pdf) — no login required. Looked up across both doctypes by pay_token (see :func:app.apps.erp.services.accounting_payment_paystack.ensure_quote_like_pay_token). Unlike the invoice link, this pays the document's own grand_total as a deposit — there's no "open balance" to settle since a quote/order isn't an invoice yet (see :func:app.apps.erp.services.accounting_payment_paystack.init_quote_like_payment).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
token | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/paystack/webhook
Paystack Webhook
200 — Successful Response
json
{}