Skip to content
ShaBaas Pay / Docs
Payment Initiation

Initiate Direct Debit Payment Request

Create direct debit initiation and process settlement workflow.

Error Codes

CodeStatusReasonWhat to do
PAS_AMT_REQUIRED400Amount is requiredInclude amount in direct debit payload.
PAS_AMT_INVALID400Amount format is invalidUse a valid numeric amount format.
R104422Consent is missing or invalidSet consent_received to "true" and retry.
R101422Amount exceeds allowed thresholdReduce amount and retry.
R801422Similar debit attempted within cooldown periodWait for cooldown window and retry.
R102422Daily spend limit exceededRetry later or reduce amount.
R100422Daily transaction count exceededRetry next day or after account review.
R103422Destination payout not enabledUpdate merchant payout settings or remove destination.
R803422Direct debit initiation failed upstreamRetry; if repeated, contact support with request details.
MOV_INVALID_BANK_ACCOUNT400Bank account does not belong to current institutionCorrect payer account details and retry.
MOV_INVALID_BSB400Invalid BSB numberProvide valid 6-digit BSB and retry.
MOV_REQUEST_TIMEOUT408Request timed outRetry after a short delay.
post/api/public/payment_initiation/direct_debit

Initiate Direct Debit Payment Request

Create direct debit initiation and process settlement workflow.

Error Codes

CodeStatusReasonWhat to do
PAS_AMT_REQUIRED400Amount is requiredInclude amount in direct debit payload.
PAS_AMT_INVALID400Amount format is invalidUse a valid numeric amount format.
R104422Consent is missing or invalidSet consent_received to "true" and retry.
R101422Amount exceeds allowed thresholdReduce amount and retry.
R801422Similar debit attempted within cooldown periodWait for cooldown window and retry.
R102422Daily spend limit exceededRetry later or reduce amount.
R100422Daily transaction count exceededRetry next day or after account review.
R103422Destination payout not enabledUpdate merchant payout settings or remove destination.
R803422Direct debit initiation failed upstreamRetry; if repeated, contact support with request details.
MOV_INVALID_BANK_ACCOUNT400Bank account does not belong to current institutionCorrect payer account details and retry.
MOV_INVALID_BSB400Invalid BSB numberProvide valid 6-digit BSB and retry.
MOV_REQUEST_TIMEOUT408Request timed outRetry after a short delay.

Servers

Staging: https://dev-api.shabaas.com

Production: https://api.shabaas.com

Authentication

BearerAuthAuthorization: Bearer <token>

Bearer token returned by /api/public/authorization.

Request Body

Required
application/json
object

Properties

direct_debitRequiredobject

Request payload used to create and initiate direct debit flow.

object

Properties

idOptionalstring

Optional internal reference id.

string
Example
"DD-REF-1001"
phone_numberRequiredstring

Payer mobile number.

string
Example
"+61422020901"
nameRequiredstring

Payer account holder name.

stringminLength: 2maxLength: 140
Example
"John Smith"
tokenOptionalstring

Optional token passed from prior payer flow.

string
Example
"tok_abc123"
maximum_amountOptional

Optional max amount metadata for agreement creation stage.

oneOf

string
number
Example
"100.00"
typeOptionalstring

Payer identifier/account type hint.

stringallowed: "bsb", "email", "phone", "abn", "org"
Example
"bsb"
bsbRequiredstring

Payer BSB. Use 802985.

stringdefault: "802985"minLength: 6maxLength: 6
Example
"802985"
account_numberRequiredstring

Payer account number. Use 818694776.

stringdefault: "818694776"minLength: 4maxLength: 12
Example
"818694776"
pay_idOptionalstring

Optional payer PayID.

Sandbox suggestions (Staging). Production requires a real PayID.

  • email: sample@shabaas.com, sample@sbpay.au
  • phone: 61491570006, 61491570156
  • abn: 12345678901, 13579246810
  • org: 123456789, 135792468
string
checkout_pageOptionalstring

Optional checkout page marker/reference.

string
Example
"direct_debit"
notesOptionalstring

Optional note attached to the debit initiation.

stringmaxLength: 140
Example
"Membership debit"
amountRequired

Debit amount requested.

oneOf

string
number
Example
"50.00"
consent_receivedRequiredstring

Must be the string value "true".

stringallowed: "true"
destinationOptionalobject

Destination payout account details used when instant payout is enabled.

object

Properties

bsbOptionalstring

Destination BSB (6 digits).

stringminLength: 6maxLength: 6
Example
"123456"
account_numberOptionalstring

Destination account number.

stringminLength: 4maxLength: 12
Example
"12345678"

Responses

200Direct debit initiation created successfully.
application/json

Standard success envelope for payment initiation APIs.

object

Properties

messageOptionalstring

Human-readable outcome message.

string
Example
"Success"
dataOptionalobject

Payment initiation object returned by create/get initiation APIs.

object

Properties

payment_initiation_idOptionalstring

Unique payment initiation identifier.

string
Example
"12345PI1714316400"
payment_agreement_idOptionalstring

Linked payment agreement identifier.

string
Example
"3652PA20260428120000123"
amountOptional

Debit amount for this initiation.

oneOf

string
number
Example
"10.00"
currencyOptionalstring

Currency of this initiation.

string
Example
"AUD"
operation_idOptionalstring

Present when the request included Idempotency-Key. Use it to retrieve the original operation.

string · nullable
Example
"op_2f1c0c4e-7b2a-4d3e-9a11-6c5b2a1d0e44"
merchant_referenceOptionalstring

Merchant reference stored with the idempotency key. Null when the request omitted it.

string · nullable
Example
"invoice-4201"
state_versionOptionalinteger

Monotonic version of this payment record.

integer
Example
1
statusOptionalstring

Current initiation processing status.

string
Example
"accp"
created_atOptionalstring

Initiation creation timestamp in ISO8601 format.

stringformat: date-time
Example
"2026-04-28T13:45:00.000Z"
settledOptionalboolean

Indicates whether the initiation has settled.

boolean
Example
false
transferOptionalstring

Transfer state/classification when available.

string · nullable
Example
null
failure_codeOptionalstring

Provider/business failure code.

string
Example
"R803"
messageOptionalstring

Failure or status message supplied by processing system.

string
Example
"Similar payment attempted within last 24 hours"
split_percentage_feeOptionalnumber

Bookkeeper retain percentage when set (greater than 0 and less than 100). Retained share stays on the business ledger for end-of-day transfer.

number · nullable
Example
20
refund_amountOptionalstring

Total of Ok and Pending refunds reserved against this payment. Null when no refund has reserved an amount.

string · nullable
Example
"1.0"
refundsOptionalarray

Refunds for this payment, oldest first. Empty when none exist.

array
Array item schema

One refund of a payment initiation.

object

Properties

idOptionalinteger

Refund row id.

integer
Example
41
amountOptionalstring

Dollars sent, or reserved, for this refund.

string
Example
"1.0"
statusOptionalstring

Ok is paid. Pending is still in progress. Failed did not pay the customer.

string
Example
"Ok"
notesOptionalstring

Caller-supplied reason. Scheme errors are not stored here.

string · nullable
Example
"Customer requested a refund"
created_atOptionalstring
stringformat: date-time
Example
"2026-04-28T15:00:00.000Z"
completed_atOptionalstring

Reserved timestamp. Currently null even when status is Ok.

string · nullableformat: date-time
Example
null
transaction_idOptionalstring

Scheme transaction id once the refund is accepted.

string · nullable
Example
"90010001"
failure_codeOptionalstring

Scheme failure code. Null on Ok and Pending.

string · nullable
failure_messageOptionalstring

Scheme failure message. Null on Ok and Pending.

string · nullable
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/json
object

Properties

messageRequiredstring
string
Example
"Payee account cannot receive NPP Payments"
error_codeRequiredstring
string
Example
"MOV_NPP_PAYMENT_NOT_SUPPORTED"
dataRequiredobject
object
Example
{
  "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`."
      }
    }
  }
}
Download endpoint OpenAPI JSON →
← Back to API Reference