Bookkeeper API
Bookkeeper API — PayTo payout with optional split retain on the business ledger.
HTTP: POST /api/public/payment_initiation
When split_percentage_fee is set (for example 20 or "20%"):
- For amount
$100,$80is paid out immediately (todestinationwhen provided, otherwise the merchant payout account) $20remains on the business ledger and is transferred end of day
split_percentage_fee and destination are both optional.
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| PAM_SB_PAG_NOT_FOUND_ERROR | 404 | Payment agreement not found | Verify payment_agreement_id and merchant ownership. |
| PAS_AGREEMENT_STATUS_INACTIVE | 422 | Agreement is not active | Activate agreement before initiating payment. |
| R804 | 422 | Duplicate/too-soon payment initiation detected | Wait for cooldown window and retry once eligible. |
| R101 | 422 | Amount exceeds per-transaction/agreement limit | Reduce amount to allowed limit. |
| R103 | 422 | Destination payout not allowed for merchant settings | Enable eligible payout settings or remove destination. |
| R803 | 422 | Upstream initiation failed | Retry; if persistent, contact support with request metadata. |
| CREDITS_EXHAUSTED | 402 | Developer credits exhausted | Top up developer credits and retry. |
| GN-0000 | 422 | Invalid split_percentage_fee | Use a number greater than 0 and less than 100 (e.g. 20 or "20%"). |
/payment_initiationBookkeeper API
Bookkeeper API — PayTo payout with optional split retain on the business ledger.
HTTP: POST /api/public/payment_initiation
When split_percentage_fee is set (for example 20 or "20%"):
- For amount
$100,$80is paid out immediately (todestinationwhen provided, otherwise the merchant payout account) $20remains on the business ledger and is transferred end of day
split_percentage_fee and destination are both optional.
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| PAM_SB_PAG_NOT_FOUND_ERROR | 404 | Payment agreement not found | Verify payment_agreement_id and merchant ownership. |
| PAS_AGREEMENT_STATUS_INACTIVE | 422 | Agreement is not active | Activate agreement before initiating payment. |
| R804 | 422 | Duplicate/too-soon payment initiation detected | Wait for cooldown window and retry once eligible. |
| R101 | 422 | Amount exceeds per-transaction/agreement limit | Reduce amount to allowed limit. |
| R103 | 422 | Destination payout not allowed for merchant settings | Enable eligible payout settings or remove destination. |
| R803 | 422 | Upstream initiation failed | Retry; if persistent, contact support with request metadata. |
| CREDITS_EXHAUSTED | 402 | Developer credits exhausted | Top up developer credits and retry. |
| GN-0000 | 422 | Invalid split_percentage_fee | Use a number greater than 0 and less than 100 (e.g. 20 or "20%"). |
Servers
Staging: https://dev-api.shabaas.com/api/public
Production: https://api.shabaas.com/api/public
Authentication
Authorization: Bearer <token>Bearer token returned by /api/public/authorization.
Request Body
Requiredapplication/jsonBookkeeper request body for POST /api/public/payment_initiation.
Send split_percentage_fee inside payment_initiation to retain a share on the ledger for EOD.
Properties
payment_initiationRequiredPay from
oneOf
Properties
payment_agreement_idRequiredstringExisting active payment agreement identifier i.e payid or payment_agreement_id
"3652PA20260428120000123"amountRequiredDebit amount to initiate for this request.
oneOf
100notesOptionalstringOptional note attached to the initiation.
"Bookkeeper payout"split_percentage_feeOptionalOptional retain percentage (e.g. 20 or "20%").
Must be greater than 0 and less than 100 when provided.
For $100 with 20, $80 is paid out now and $20 stays on the business ledger for EOD.
oneOf
20Properties
payidRequiredstringExisting active payment agreement identifier i.e payid or payment_agreement_id
"TES307400@SBPAY.AU"amountRequiredDebit amount to initiate for this request.
oneOf
100notesOptionalstringOptional note attached to the initiation.
"Bookkeeper payout"split_percentage_feeOptionalOptional retain percentage (e.g. 20 or "20%").
Must be greater than 0 and less than 100 when provided.
For $100 with 20, $80 is paid out now and $20 stays on the business ledger for EOD.
oneOf
20destinationOptionalobjectDestination payout account details used when instant payout is enabled.
Properties
bsbOptionalstringDestination BSB (6 digits).
"123456"account_numberOptionalstringDestination account number.
"12345678"Bookkeeper with 20% ledger retain
{
"payment_initiation": {
"payment_agreement_id": "3652PA20260408123221550",
"amount": 100,
"notes": "Bookkeeper payout",
"split_percentage_fee": 20
},
"destination": {
"bsb": "802985",
"account_number": "516610025"
}
}Split fee without destination
{
"payment_initiation": {
"payment_agreement_id": "3652PA20260408123221550",
"amount": 100,
"split_percentage_fee": 20
}
}Responses
200Bookkeeper payment initiation created successfully.
application/jsonStandard success envelope for payment initiation APIs.
Properties
messageOptionalstringHuman-readable outcome message.
"Success"dataOptionalobjectPayment initiation object returned by create/get initiation APIs.
Properties
payment_initiation_idOptionalstringUnique payment initiation identifier.
"12345PI1714316400"payment_agreement_idOptionalstringLinked payment agreement identifier.
"3652PA20260428120000123"amountOptionalDebit amount for this initiation.
oneOf
"10.00"currencyOptionalstringCurrency of this initiation.
"AUD"operation_idOptionalstringPresent when the request included Idempotency-Key. Use it to retrieve the original operation.
"op_2f1c0c4e-7b2a-4d3e-9a11-6c5b2a1d0e44"merchant_referenceOptionalstringMerchant reference stored with the idempotency key. Null when the request omitted it.
"invoice-4201"state_versionOptionalintegerMonotonic version of this payment record.
1statusOptionalstringCurrent initiation processing status.
"accp"created_atOptionalstringInitiation creation timestamp in ISO8601 format.
"2026-04-28T13:45:00.000Z"settledOptionalbooleanIndicates whether the initiation has settled.
falsetransferOptionalstringTransfer state/classification when available.
nullfailure_codeOptionalstringProvider/business failure code.
"R803"messageOptionalstringFailure or status message supplied by processing system.
"Similar payment attempted within last 24 hours"split_percentage_feeOptionalnumberBookkeeper retain percentage when set (greater than 0 and less than 100). Retained share stays on the business ledger for end-of-day transfer.
20refund_amountOptionalstringTotal of Ok and Pending refunds reserved against this payment.
Null when no refund has reserved an amount.
"1.0"refundsOptionalarrayRefunds for this payment, oldest first. Empty when none exist.
Array item schema
One refund of a payment initiation.
Properties
idOptionalintegerRefund row id.
41amountOptionalstringDollars sent, or reserved, for this refund.
"1.0"statusOptionalstringOk is paid. Pending is still in progress. Failed did not pay the customer.
"Ok"notesOptionalstringCaller-supplied reason. Scheme errors are not stored here.
"Customer requested a refund"created_atOptionalstring"2026-04-28T15:00:00.000Z"completed_atOptionalstringReserved timestamp. Currently null even when status is Ok.
nulltransaction_idOptionalstringScheme transaction id once the refund is accepted.
"90010001"failure_codeOptionalstringScheme failure code. Null on Ok and Pending.
failure_messageOptionalstringScheme failure message. Null on Ok and Pending.
Bookkeeper initiation accepted
{
"message": "Success",
"data": {
"payment_initiation_id": "12345PI1714316400",
"settled": false,
"status": "accp",
"transfer": null,
"split_percentage_fee": 20,
"created_at": "2026-04-28T13:45:00.000Z"
}
}401Invalid or missing bearer token.
application/jsonProperties
messageRequiredstring"Payee account cannot receive NPP Payments"error_codeRequiredstring"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobject{
"response_time": "2026-04-08T12:28:26.759Z"
}Additional properties are supported; see the endpoint definition for their schema.
402Developer credit balance is insufficient for this operation.
application/jsonProperties
messageRequiredstring"Payee account cannot receive NPP Payments"error_codeRequiredstring"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobject{
"response_time": "2026-04-08T12:28:26.759Z"
}Additional properties are supported; see the endpoint definition for their schema.
404Referenced payment agreement was not found for this merchant.
application/jsonProperties
messageRequiredstring"Payee account cannot receive NPP Payments"error_codeRequiredstring"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobject{
"response_time": "2026-04-08T12:28:26.759Z"
}Additional properties are supported; see the endpoint definition for their schema.
422Validation or business rule failure.
application/jsonProperties
messageRequiredstring"Payee account cannot receive NPP Payments"error_codeRequiredstring"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobject{
"response_time": "2026-04-08T12:28:26.759Z"
}Additional properties are supported; see the endpoint definition for their schema.
Full endpoint OpenAPI definition
{
"openapi": "3.0.3",
"info": {
"title": "ShaBaasPay Public API",
"version": "1.0.0",
"description": "Describes public REST endpoints for authorization, payment agreements, payment initiations,\nrefunds, webhooks, and PayID collection APIs.\n"
},
"servers": [
{
"url": "https://dev-api.shabaas.com",
"description": "Staging"
},
{
"url": "https://api.shabaas.com",
"description": "Production"
}
],
"tags": [
{
"name": "B2B Collections",
"x-displayName": "B2B Collections",
"description": "Create inbound PayID collections, verify PayID status, and Bookkeeper API payout\nwith optional split retain on the business ledger.\n"
}
],
"x-tagGroups": [
{
"name": "SHABAASPAY PUBLIC API",
"tags": [
"API Keys",
"Payment Agreement",
"Payment Initiation",
"Checkout",
"B2B Collections",
"Webhooks"
]
},
{
"name": "Internal",
"tags": [
"Clients"
]
}
],
"security": [
{
"BearerAuth": []
}
],
"paths": {
"/payment_initiation": {
"post": {
"servers": [
{
"url": "https://dev-api.shabaas.com/api/public",
"description": "Staging"
},
{
"url": "https://api.shabaas.com/api/public",
"description": "Production"
}
],
"tags": [
"B2B Collections"
],
"summary": "Bookkeeper API",
"operationId": "bookkeeperInitiatePayment",
"description": "**Bookkeeper API** — PayTo payout with optional split retain on the business ledger.\n\n**HTTP:** `POST /api/public/payment_initiation`\n\nWhen `split_percentage_fee` is set (for example `20` or `\"20%\"`):\n- For amount `$100`, **`$80` is paid out** immediately (to `destination` when provided,\n otherwise the merchant payout account)\n- **`$20` remains on the business ledger** and is transferred end of day\n\n`split_percentage_fee` and `destination` are both optional.\n\n### Error Codes\n| Code | Status | Reason | What to do |\n| ---- | ------ | ------ | ---------- |\n| PAM_SB_PAG_NOT_FOUND_ERROR | 404 | Payment agreement not found | Verify `payment_agreement_id` and merchant ownership. |\n| PAS_AGREEMENT_STATUS_INACTIVE | 422 | Agreement is not active | Activate agreement before initiating payment. |\n| R804 | 422 | Duplicate/too-soon payment initiation detected | Wait for cooldown window and retry once eligible. |\n| R101 | 422 | Amount exceeds per-transaction/agreement limit | Reduce `amount` to allowed limit. |\n| R103 | 422 | Destination payout not allowed for merchant settings | Enable eligible payout settings or remove destination. |\n| R803 | 422 | Upstream initiation failed | Retry; if persistent, contact support with request metadata. |\n| CREDITS_EXHAUSTED | 402 | Developer credits exhausted | Top up developer credits and retry. |\n| GN-0000 | 422 | Invalid `split_percentage_fee` | Use a number greater than 0 and less than 100 (e.g. `20` or `\"20%\"`). |\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateBookkeeperPaymentBody"
},
"examples": {
"with_split": {
"summary": "Bookkeeper with 20% ledger retain",
"value": {
"payment_initiation": {
"payment_agreement_id": "3652PA20260408123221550",
"amount": 100,
"notes": "Bookkeeper payout",
"split_percentage_fee": 20
},
"destination": {
"bsb": "802985",
"account_number": "516610025"
}
}
},
"split_only": {
"summary": "Split fee without destination",
"value": {
"payment_initiation": {
"payment_agreement_id": "3652PA20260408123221550",
"amount": 100,
"split_percentage_fee": 20
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Bookkeeper payment initiation created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessPaymentInitiationResponse"
},
"examples": {
"created": {
"summary": "Bookkeeper initiation accepted",
"value": {
"message": "Success",
"data": {
"payment_initiation_id": "12345PI1714316400",
"settled": false,
"status": "accp",
"transfer": null,
"split_percentage_fee": 20,
"created_at": "2026-04-28T13:45:00.000Z"
}
}
}
}
}
}
},
"401": {
"description": "Invalid or missing bearer token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "Developer credit balance is insufficient for this operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Referenced payment agreement was not found for this merchant.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation or business rule failure.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"CreateBookkeeperPaymentBody": {
"type": "object",
"description": "Bookkeeper request body for `POST /api/public/payment_initiation`.\nSend `split_percentage_fee` inside `payment_initiation` to retain a share on the ledger for EOD.\n",
"required": [
"payment_initiation"
],
"properties": {
"payment_initiation": {
"$ref": "#/components/schemas/CreateBookkeeperPaymentInitiationRequest"
},
"destination": {
"$ref": "#/components/schemas/DestinationAccount"
}
}
},
"CreateBookkeeperPaymentInitiationRequest": {
"description": "Pay from",
"oneOf": [
{
"title": "payment_agreement_id",
"type": "object",
"required": [
"payment_agreement_id",
"amount"
],
"properties": {
"payment_agreement_id": {
"type": "string",
"description": "Existing active payment agreement identifier i.e payid or payment_agreement_id",
"example": "3652PA20260428120000123"
},
"amount": {
"oneOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "Debit amount to initiate for this request.",
"example": 100
},
"notes": {
"type": "string",
"maxLength": 140,
"description": "Optional note attached to the initiation.",
"example": "Bookkeeper payout"
},
"split_percentage_fee": {
"oneOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "Optional retain percentage (e.g. `20` or `\"20%\"`).\nMust be greater than 0 and less than 100 when provided.\nFor `$100` with `20`, `$80` is paid out now and `$20` stays on the business ledger for EOD.\n",
"example": 20
}
}
},
{
"title": "payid",
"type": "object",
"required": [
"payid",
"amount"
],
"properties": {
"payid": {
"type": "string",
"description": "Existing active payment agreement identifier i.e payid or payment_agreement_id",
"example": "TES307400@SBPAY.AU"
},
"amount": {
"oneOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "Debit amount to initiate for this request.",
"example": 100
},
"notes": {
"type": "string",
"maxLength": 140,
"description": "Optional note attached to the initiation.",
"example": "Bookkeeper payout"
},
"split_percentage_fee": {
"oneOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "Optional retain percentage (e.g. `20` or `\"20%\"`).\nMust be greater than 0 and less than 100 when provided.\nFor `$100` with `20`, `$80` is paid out now and `$20` stays on the business ledger for EOD.\n",
"example": 20
}
}
}
]
},
"DestinationAccount": {
"type": "object",
"description": "Destination payout account details used when instant payout is enabled.",
"properties": {
"bsb": {
"type": "string",
"minLength": 6,
"maxLength": 6,
"description": "Destination BSB (6 digits).",
"example": "123456"
},
"account_number": {
"type": "string",
"minLength": 4,
"maxLength": 12,
"description": "Destination account number.",
"example": "12345678"
}
}
},
"SuccessPaymentInitiationResponse": {
"type": "object",
"description": "Standard success envelope for payment initiation APIs.",
"properties": {
"message": {
"type": "string",
"description": "Human-readable outcome message.",
"example": "Success"
},
"data": {
"$ref": "#/components/schemas/PaymentInitiation"
}
}
},
"PaymentInitiation": {
"type": "object",
"description": "Payment initiation object returned by create/get initiation APIs.",
"properties": {
"payment_initiation_id": {
"type": "string",
"description": "Unique payment initiation identifier.",
"example": "12345PI1714316400"
},
"payment_agreement_id": {
"type": "string",
"description": "Linked payment agreement identifier.",
"example": "3652PA20260428120000123"
},
"amount": {
"oneOf": [
{
"type": "string"
},
{
"type": "number"
}
],
"description": "Debit amount for this initiation.",
"example": "10.00"
},
"currency": {
"type": "string",
"description": "Currency of this initiation.",
"example": "AUD"
},
"operation_id": {
"type": "string",
"nullable": true,
"description": "Present when the request included `Idempotency-Key`. Use it to retrieve the original operation.\n",
"example": "op_2f1c0c4e-7b2a-4d3e-9a11-6c5b2a1d0e44"
},
"merchant_reference": {
"type": "string",
"nullable": true,
"description": "Merchant reference stored with the idempotency key. Null when the request omitted it.",
"example": "invoice-4201"
},
"state_version": {
"type": "integer",
"description": "Monotonic version of this payment record.",
"example": 1
},
"status": {
"type": "string",
"description": "Current initiation processing status.",
"example": "accp"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Initiation creation timestamp in ISO8601 format.",
"example": "2026-04-28T13:45:00.000Z"
},
"settled": {
"type": "boolean",
"description": "Indicates whether the initiation has settled.",
"example": false
},
"transfer": {
"type": "string",
"description": "Transfer state/classification when available.",
"nullable": true,
"example": null
},
"failure_code": {
"type": "string",
"description": "Provider/business failure code.",
"example": "R803"
},
"message": {
"type": "string",
"description": "Failure or status message supplied by processing system.",
"example": "Similar payment attempted within last 24 hours"
},
"split_percentage_fee": {
"type": "number",
"nullable": true,
"description": "Bookkeeper retain percentage when set (greater than 0 and less than 100).\nRetained share stays on the business ledger for end-of-day transfer.\n",
"example": 20
},
"refund_amount": {
"type": "string",
"nullable": true,
"description": "Total of `Ok` and `Pending` refunds reserved against this payment.\nNull when no refund has reserved an amount.\n",
"example": "1.0"
},
"refunds": {
"type": "array",
"description": "Refunds for this payment, oldest first. Empty when none exist.",
"items": {
"$ref": "#/components/schemas/Refund"
}
}
}
},
"Refund": {
"type": "object",
"description": "One refund of a payment initiation.",
"properties": {
"id": {
"type": "integer",
"description": "Refund row id.",
"example": 41
},
"amount": {
"type": "string",
"description": "Dollars sent, or reserved, for this refund.",
"example": "1.0"
},
"status": {
"type": "string",
"description": "`Ok` is paid. `Pending` is still in progress. `Failed` did not pay the customer.",
"example": "Ok"
},
"notes": {
"type": "string",
"nullable": true,
"description": "Caller-supplied reason. Scheme errors are not stored here.",
"example": "Customer requested a refund"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2026-04-28T15:00:00.000Z"
},
"completed_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Reserved timestamp. Currently null even when status is `Ok`.",
"example": null
},
"transaction_id": {
"type": "string",
"nullable": true,
"description": "Scheme transaction id once the refund is accepted.",
"example": "90010001"
},
"failure_code": {
"type": "string",
"nullable": true,
"description": "Scheme failure code. Null on `Ok` and `Pending`."
},
"failure_message": {
"type": "string",
"nullable": true,
"description": "Scheme failure message. Null on `Ok` and `Pending`."
}
}
},
"ErrorResponse": {
"type": "object",
"required": [
"message",
"error_code",
"data"
],
"properties": {
"message": {
"type": "string",
"example": "Payee account cannot receive NPP Payments"
},
"error_code": {
"type": "string",
"example": "MOV_NPP_PAYMENT_NOT_SUPPORTED"
},
"data": {
"type": "object",
"additionalProperties": true,
"example": {
"response_time": "2026-04-08T12:28:26.759Z"
}
}
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "Bearer token returned by `/api/public/authorization`."
}
}
}
}