{"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`."}}}}