Initiate Direct Debit Payment Request
Create direct debit initiation and process settlement workflow.
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| PAS_AMT_REQUIRED | 400 | Amount is required | Include amount in direct debit payload. |
| PAS_AMT_INVALID | 400 | Amount format is invalid | Use a valid numeric amount format. |
| R104 | 422 | Consent is missing or invalid | Set consent_received to "true" and retry. |
| R101 | 422 | Amount exceeds allowed threshold | Reduce amount and retry. |
| R801 | 422 | Similar debit attempted within cooldown period | Wait for cooldown window and retry. |
| R102 | 422 | Daily spend limit exceeded | Retry later or reduce amount. |
| R100 | 422 | Daily transaction count exceeded | Retry next day or after account review. |
| R103 | 422 | Destination payout not enabled | Update merchant payout settings or remove destination. |
| R803 | 422 | Direct debit initiation failed upstream | Retry; if repeated, contact support with request details. |
| MOV_INVALID_BANK_ACCOUNT | 400 | Bank account does not belong to current institution | Correct payer account details and retry. |
| MOV_INVALID_BSB | 400 | Invalid BSB number | Provide valid 6-digit BSB and retry. |
| MOV_REQUEST_TIMEOUT | 408 | Request timed out | Retry after a short delay. |
/api/public/payment_initiation/direct_debitInitiate Direct Debit Payment Request
Create direct debit initiation and process settlement workflow.
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| PAS_AMT_REQUIRED | 400 | Amount is required | Include amount in direct debit payload. |
| PAS_AMT_INVALID | 400 | Amount format is invalid | Use a valid numeric amount format. |
| R104 | 422 | Consent is missing or invalid | Set consent_received to "true" and retry. |
| R101 | 422 | Amount exceeds allowed threshold | Reduce amount and retry. |
| R801 | 422 | Similar debit attempted within cooldown period | Wait for cooldown window and retry. |
| R102 | 422 | Daily spend limit exceeded | Retry later or reduce amount. |
| R100 | 422 | Daily transaction count exceeded | Retry next day or after account review. |
| R103 | 422 | Destination payout not enabled | Update merchant payout settings or remove destination. |
| R803 | 422 | Direct debit initiation failed upstream | Retry; if repeated, contact support with request details. |
| MOV_INVALID_BANK_ACCOUNT | 400 | Bank account does not belong to current institution | Correct payer account details and retry. |
| MOV_INVALID_BSB | 400 | Invalid BSB number | Provide valid 6-digit BSB and retry. |
| MOV_REQUEST_TIMEOUT | 408 | Request timed out | Retry after a short delay. |
Servers
Staging: https://dev-api.shabaas.com
Production: https://api.shabaas.com
Authentication
Authorization: Bearer <token>Bearer token returned by /api/public/authorization.
Request Body
Requiredapplication/jsonProperties
direct_debitRequiredobjectRequest payload used to create and initiate direct debit flow.
Properties
idOptionalstringOptional internal reference id.
"DD-REF-1001"phone_numberRequiredstringPayer mobile number.
"+61422020901"nameRequiredstringPayer account holder name.
"John Smith"tokenOptionalstringOptional token passed from prior payer flow.
"tok_abc123"maximum_amountOptionalOptional max amount metadata for agreement creation stage.
oneOf
"100.00"typeOptionalstringPayer identifier/account type hint.
"bsb"bsbRequiredstringPayer BSB. Use 802985.
"802985"account_numberRequiredstringPayer account number. Use 818694776.
"818694776"pay_idOptionalstringOptional payer PayID.
Sandbox suggestions (Staging). Production requires a real PayID.
email:sample@shabaas.com,sample@sbpay.auphone:61491570006,61491570156abn:12345678901,13579246810org:123456789,135792468
checkout_pageOptionalstringOptional checkout page marker/reference.
"direct_debit"notesOptionalstringOptional note attached to the debit initiation.
"Membership debit"amountRequiredDebit amount requested.
oneOf
"50.00"consent_receivedRequiredstringMust be the string value "true".
destinationOptionalobjectDestination payout account details used when instant payout is enabled.
Properties
bsbOptionalstringDestination BSB (6 digits).
"123456"account_numberOptionalstringDestination account number.
"12345678"Responses
200Direct debit 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.
Direct debit initiation accepted
{
"message": "Success",
"data": {
"payment_initiation_id": "DD12345PI1714316400",
"settled": false,
"status": "acsc",
"transfer": null,
"created_at": "2026-04-28T14:00:00.000Z"
}
}422Validation or business-rule error during direct debit initiation.
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.
consent_required
{
"message": "Consent is required",
"error_code": "R104",
"data": {
"response_time": "2026-04-10T12:00:00.000Z"
}
}cooldown_23h
{
"message": "Similar payment attempted within last 23 hours",
"error_code": "R801",
"data": {
"response_time": "2026-04-10T12:00:00.000Z"
}
}upstream_failed
{
"message": "Failed to initiate payment.",
"error_code": "R803",
"data": {
"response_time": "2026-04-10T12:00:00.000Z"
}
}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": "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`."
}
}
}
}