{"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":"Payment Initiation","x-displayName":"Payment Initiation","description":"Create and retrieve payment initiations, and refund a settled payment that belongs to the authenticated merchant."}],"x-tagGroups":[{"name":"SHABAASPAY PUBLIC API","tags":["API Keys","Payment Agreement","Payment Initiation","Checkout","B2B Collections","Webhooks"]},{"name":"Internal","tags":["Clients"]}],"security":[{"BearerAuth":[]}],"paths":{"/api/public/payment_initiation/direct_debit":{"post":{"tags":["Payment Initiation"],"summary":"Initiate Direct Debit Payment Request","description":"Create direct debit initiation and process settlement workflow.\n\n### Error Codes\n| Code | Status | Reason | What to do |\n| ---- | ------ | ------ | ---------- |\n| PAS_AMT_REQUIRED | 400 | Amount is required | Include `amount` in direct debit payload. |\n| PAS_AMT_INVALID | 400 | Amount format is invalid | Use a valid numeric amount format. |\n| R104 | 422 | Consent is missing or invalid | Set `consent_received` to `\"true\"` and retry. |\n| R101 | 422 | Amount exceeds allowed threshold | Reduce `amount` and retry. |\n| R801 | 422 | Similar debit attempted within cooldown period | Wait for cooldown window and retry. |\n| R102 | 422 | Daily spend limit exceeded | Retry later or reduce amount. |\n| R100 | 422 | Daily transaction count exceeded | Retry next day or after account review. |\n| R103 | 422 | Destination payout not enabled | Update merchant payout settings or remove destination. |\n| R803 | 422 | Direct debit initiation failed upstream | Retry; if repeated, contact support with request details. |\n| MOV_INVALID_BANK_ACCOUNT | 400 | Bank account does not belong to current institution | Correct payer account details and retry. |\n| MOV_INVALID_BSB | 400 | Invalid BSB number | Provide valid 6-digit BSB and retry. |\n| MOV_REQUEST_TIMEOUT | 408 | Request timed out | Retry after a short delay. |\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["direct_debit"],"properties":{"direct_debit":{"$ref":"#/components/schemas/DirectDebitInitiationRequest"},"destination":{"$ref":"#/components/schemas/DestinationAccount"}}}}}},"responses":{"200":{"description":"Direct debit initiation created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessPaymentInitiationResponse"},"examples":{"initiated":{"summary":"Direct debit initiation accepted","value":{"message":"Success","data":{"payment_initiation_id":"DD12345PI1714316400","settled":false,"status":"acsc","transfer":null,"created_at":"2026-04-28T14:00:00.000Z"}}}}}}},"422":{"description":"Validation or business-rule error during direct debit initiation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"consent_required":{"value":{"message":"Consent is required","error_code":"R104","data":{"response_time":"2026-04-10T12:00:00.000Z"}}},"cooldown_23h":{"value":{"message":"Similar payment attempted within last 23 hours","error_code":"R801","data":{"response_time":"2026-04-10T12:00:00.000Z"}}},"upstream_failed":{"value":{"message":"Failed to initiate payment.","error_code":"R803","data":{"response_time":"2026-04-10T12:00:00.000Z"}}}}}}}}}}},"components":{"schemas":{"DirectDebitInitiationRequest":{"type":"object","description":"Request payload used to create and initiate direct debit flow.","required":["name","phone_number","bsb","account_number","amount","consent_received"],"properties":{"id":{"type":"string","description":"Optional internal reference id.","example":"DD-REF-1001"},"phone_number":{"type":"string","description":"Payer mobile number.","example":"+61422020901"},"name":{"type":"string","minLength":2,"maxLength":140,"description":"Payer account holder name.","example":"John Smith"},"token":{"type":"string","description":"Optional token passed from prior payer flow.","example":"tok_abc123"},"maximum_amount":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"Optional max amount metadata for agreement creation stage.","example":"100.00"},"type":{"type":"string","description":"Payer identifier/account type hint.","enum":["bsb","email","phone","abn","org"],"example":"bsb"},"bsb":{"type":"string","minLength":6,"maxLength":6,"description":"Payer BSB. Use `802985`.","default":"802985","example":"802985"},"account_number":{"type":"string","minLength":4,"maxLength":12,"description":"Payer account number. Use `818694776`.","default":"818694776","example":"818694776"},"pay_id":{"type":"string","description":"Optional payer PayID.\n\nSandbox suggestions (Staging). Production requires a real PayID.\n- `email`: `sample@shabaas.com`, `sample@sbpay.au`\n- `phone`: `61491570006`, `61491570156`\n- `abn`: `12345678901`, `13579246810`\n- `org`: `123456789`, `135792468`\n"},"checkout_page":{"type":"string","description":"Optional checkout page marker/reference.","example":"direct_debit"},"notes":{"type":"string","maxLength":140,"description":"Optional note attached to the debit initiation.","example":"Membership debit"},"amount":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"Debit amount requested.","example":"50.00"},"consent_received":{"type":"string","enum":["true"],"description":"Must be the string value `\"true\"`."}}},"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`."}}}}