Create PayTo Agreement
Create a PayTo payment agreement.
Sandbox PayID suggestions
On Staging, use one of these pay_id values for the matching type. Production requires a real PayID.
| type | Suggested pay_id |
|---|---|
sample@shabaas.com, sample@sbpay.au | |
| phone | 61491570006, 61491570156 |
| abn | 12345678901, 13579246810 |
| org | 123456789, 135792468 |
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| PAM_PAYER_ID_TYPE_FORBIDDEN | 400 | LinkedPayIdType prohibited without linkedPayID | Include pay_id |
| PAM_PAYER_BSB_REQUIRED | 400 | Payer BSB required when not using a PayID | Use bsb + account_number for bank payers, or switch to type: email / phone with pay_id for PayID. |
| PAM_REQUEST_EMPTY | 400 | Request payload is empty | Send payment_agreement object with required fields. |
| PAM_VALIDATION_ERROR | 400 | Request validation failed | Correct invalid/missing fields and retry. |
| PAM_PAYEE_MISSING | 400 | Payee details are missing | Provide PayID or valid account details. |
| PAM_PAYEE_ACCT_MISSING | 400 | Payee account details are missing | Include both BSB and account number when required. |
| PAM_PAYEE_BSB_INVALID | 400 | Payee BSB is invalid | Use a valid 6-digit BSB. |
| PAM_PAYEE_ACCT_INVALID | 400 | Payee account number is invalid | Provide a valid account number. |
| PAM_PMT_FREQ_INVALID | 400 | Frequency value is invalid | Use one of supported frequency values. |
| PAM_PAG_LIMIT_EXCEEDED | 400 | Merchant agreement limit exceeded | Reduce request volume or increase limit. |
| M101 | 422 | Amount exceeds platform single-agreement threshold | Reduce maximum_amount to supported threshold. |
| M100 | 422 | Amount exceeds merchant agreement limit | Update merchant limits or lower maximum_amount. |
| MOV_NPP_PAYMENT_NOT_SUPPORTED | 422 | Payee account cannot receive NPP payments | Use a valid PayID/account that can receive NPP payments. |
| MOV_PAYEE_DETAIL_ERROR | 404 | Payee details are incorrect | Correct PayID/BSB/account details. |
| MOV_INVALID_BSB | 400 | BSB is invalid | Provide a valid BSB and retry. |
| MOV_REQUEST_TIMEOUT | 408 | Provider request timed out | Retry with backoff and poll status if needed. |
| VALIDATION_ERROR | 422 | Invalid request fields (for example frequency) | Correct payload format and accepted enum values. |
| CREDITS_EXHAUSTED | 402 | Developer credits exhausted | Top up developer credits and retry. |
/api/public/payment_agreementCreate PayTo Agreement
Create a PayTo payment agreement.
Sandbox PayID suggestions
On Staging, use one of these pay_id values for the matching type. Production requires a real PayID.
| type | Suggested pay_id |
|---|---|
sample@shabaas.com, sample@sbpay.au | |
| phone | 61491570006, 61491570156 |
| abn | 12345678901, 13579246810 |
| org | 123456789, 135792468 |
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| PAM_PAYER_ID_TYPE_FORBIDDEN | 400 | LinkedPayIdType prohibited without linkedPayID | Include pay_id |
| PAM_PAYER_BSB_REQUIRED | 400 | Payer BSB required when not using a PayID | Use bsb + account_number for bank payers, or switch to type: email / phone with pay_id for PayID. |
| PAM_REQUEST_EMPTY | 400 | Request payload is empty | Send payment_agreement object with required fields. |
| PAM_VALIDATION_ERROR | 400 | Request validation failed | Correct invalid/missing fields and retry. |
| PAM_PAYEE_MISSING | 400 | Payee details are missing | Provide PayID or valid account details. |
| PAM_PAYEE_ACCT_MISSING | 400 | Payee account details are missing | Include both BSB and account number when required. |
| PAM_PAYEE_BSB_INVALID | 400 | Payee BSB is invalid | Use a valid 6-digit BSB. |
| PAM_PAYEE_ACCT_INVALID | 400 | Payee account number is invalid | Provide a valid account number. |
| PAM_PMT_FREQ_INVALID | 400 | Frequency value is invalid | Use one of supported frequency values. |
| PAM_PAG_LIMIT_EXCEEDED | 400 | Merchant agreement limit exceeded | Reduce request volume or increase limit. |
| M101 | 422 | Amount exceeds platform single-agreement threshold | Reduce maximum_amount to supported threshold. |
| M100 | 422 | Amount exceeds merchant agreement limit | Update merchant limits or lower maximum_amount. |
| MOV_NPP_PAYMENT_NOT_SUPPORTED | 422 | Payee account cannot receive NPP payments | Use a valid PayID/account that can receive NPP payments. |
| MOV_PAYEE_DETAIL_ERROR | 404 | Payee details are incorrect | Correct PayID/BSB/account details. |
| MOV_INVALID_BSB | 400 | BSB is invalid | Provide a valid BSB and retry. |
| MOV_REQUEST_TIMEOUT | 408 | Provider request timed out | Retry with backoff and poll status if needed. |
| VALIDATION_ERROR | 422 | Invalid request fields (for example frequency) | Correct payload format and accepted enum values. |
| CREDITS_EXHAUSTED | 402 | Developer credits exhausted | Top up developer credits and retry. |
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
payment_agreementRequiredobjectRequest payload used to create a recurring payment agreement for a payer.
Properties
phone_numberOptionalstringOptional payer phone number. When provided, the payer profile is looked up/created against this number.
"+61422020901"nameRequiredstringPayer display name used in agreement records and authorization flow.
"John Smith"typeRequiredstringIdentifier type for payer/payee details.
Sandbox pay_id suggestions for each type are listed on this endpoint and on the pay_id field.
"email"maximum_amountRequiredstringMaximum debit amount allowed per transaction under this agreement.
"500.00"maximum_overall_allowed_amountOptionalstringOptional. Overall collection cap for the agreement (cumulative amount that may be collected across all payment initiations).
When provided, it must be greater than or equal to maximum_amount. Once this total is reached, further payment initiations are rejected.
Leave empty for no overall cap.
"2000.00"frequencyRequiredstringStored codes (after normalization): ADHO, DAIL, FRTN, INDA, MIAN, MNTH, QURT, WEEK, YEAR. Aliases before save: DAILY→DAIL, ADHOC→ADHO.
"ADHO"number_of_transactions_permittedRequiredintegerMaximum number of debits permitted under this agreement.
10pay_idRequiredstringPayID used for payer authorization.
Sandbox suggestions (Staging). Production requires a real PayID.
email:sample@shabaas.com,sample@sbpay.auphone:61491570006,61491570156abn:12345678901,13579246810org:123456789,135792468
bsbOptionalBSB value when bank-account based setup is used.
oneOf
"123456"account_numberOptionalAccount number when bank-account based setup is used.
oneOf
"987654321"agreement_typeOptionalstringAgreement variation/type code used by downstream provider where applicable.
"VARI"start_dateOptionalstringOptional agreement start date in YYYY-MM-DD.
"2026-05-01"end_dateOptionalstringOptional agreement end date in YYYY-MM-DD. Leave empty for open-ended agreement.
"2026-12-31"Valid request (stored frequency code)
{
"payment_agreement": {
"name": "John Smith",
"type": "email",
"maximum_amount": "500",
"maximum_overall_allowed_amount": "2000",
"frequency": "ADHO",
"number_of_transactions_permitted": 10
}
}Alias normalized by API (DAILY→DAIL, ADHOC→ADHO)
{
"payment_agreement": {
"name": "John Smith",
"type": "email",
"maximum_amount": "500",
"frequency": "DAILY",
"number_of_transactions_permitted": 10
}
}Invalid frequency (e.g. DAY is not a valid code or alias)
{
"payment_agreement": {
"name": "Hamza Amin",
"type": "email",
"maximum_amount": "500",
"frequency": "DAY",
"number_of_transactions_permitted": 10
}
}Responses
200Payment agreement created and submitted for payer authorization.
application/jsonStandard success envelope for payment agreement APIs.
Properties
messageOptionalstringMessage for the request response.
"Payment Agreement created successfully, Please authorized payment agreement from your banking app."dataOptionalobjectPayment agreement object returned by create/get agreement APIs.
Properties
payment_agreement_idOptionalstringUnique agreement identifier. Use this value to retrieve, amend, resend, or cancel the agreement.
"3652PA20260428120000123"statusOptionalstringCurrent agreement state in the processing lifecycle.
"initiated"end_dateOptionalstringAgreement end date when set; null/omitted when open-ended.
"2026-12-31"created_atOptionalstringAgreement creation timestamp in ISO8601 format.
"2026-04-28T12:00:00.000Z"maximum_amountOptionalstringMaximum debit amount allowed per agreement.
"500.00"maximum_overall_allowed_amountOptionalstringOverall collection cap for the agreement when set (cumulative amount across all payment initiations).
"2000.00"extented_statusOptionalstringCompact composite status string used by existing clients.
"500-WEEK-10-initiated"messageOptionalstringPresent when agreement has a failure message from scheme
"Payee account cannot receive NPP Payments"failure_codeOptionalstringProvider/business failure code when the agreement fails.
"M100"Agreement created successfully
{
"message": "Payment Agreement created successfully, Please authorized payment agreement from your banking app.",
"data": {
"payment_agreement_id": "3652PA20260428120000123",
"status": "initiated",
"end_date": "2026-12-31",
"created_at": "2026-04-28T12:00:00.000Z",
"maximum_amount": "500.00",
"extented_status": "500-WEEK-10-initiated"
}
}400PayTo / payer validation error returned by the upstream provider. Examples: missing `pay_id` for email/phone type, or missing bank details for `type: bsb`.
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.
linkedPayIdType without linkedPayId (e.g. only type + frequency)
{
"message": ".linkedPayIdType prohibited without linkedPayId",
"error_code": "PAM_PAYER_ID_TYPE_FORBIDDEN",
"data": {
"response_time": "2026-05-04T10:52:05.218Z"
}
}type bsb without bsb/account (e.g. pay_id used like email)
{
"message": ".linkedBsb required if no linkedPayId",
"error_code": "PAM_PAYER_BSB_REQUIRED",
"data": {
"response_time": "2026-05-04T11:10:56.372Z"
}
}401Invalid or missing authorization context.
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.
Authorization failed
{
"message": "Unauthorized Access to an operation",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-28T12:00:00.000Z"
}
}402Developer credits exhausted
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.
developer_credits
{
"message": "Developer credits exhausted",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-10T12:00:00.000Z"
}
}404Related resource not found in current merchant context.
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.
Referenced entity not found
{
"message": "MONOOVA-monoova.PAM_SB_PAG_NOT_FOUND_ERROR",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-28T12:00:00.000Z"
}
}408Upstream provider timeout while processing agreement creation.
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.
Upstream timeout
{
"message": "Request Timeout",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-28T12:00:00.000Z"
}
}422Validation or business-rule failure for agreement creation.
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.
Frequency not accepted after normalization
{
"message": "Invalid frequency value",
"error_code": "VALIDATION_ERROR",
"data": {
"field": "frequency",
"stored_codes": [
"ADHO",
"DAIL",
"FRTN",
"INDA",
"MIAN",
"MNTH",
"QURT",
"WEEK",
"YEAR"
],
"aliases": {
"DAILY": "DAIL",
"ADHOC": "ADHO"
}
}
}Payee cannot receive NPP (example)
{
"message": "Payee account cannot receive NPP Payments",
"error_code": "MOV_NPP_PAYMENT_NOT_SUPPORTED",
"data": {
"response_time": "2026-04-08T12:28:26.759Z"
}
}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 Agreement",
"x-displayName": "Payment Agreement",
"description": "Create, retrieve, amend, resend, and cancel PayTo payment agreements."
}
],
"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_agreement": {
"post": {
"tags": [
"Payment Agreement"
],
"summary": "Create PayTo Agreement",
"description": "Create a PayTo payment agreement.\n\n### Sandbox PayID suggestions\nOn Staging, use one of these `pay_id` values for the matching `type`. Production requires a real PayID.\n\n| type | Suggested `pay_id` |\n| ---- | ------------------ |\n| email | `sample@shabaas.com`, `sample@sbpay.au` |\n| phone | `61491570006`, `61491570156` |\n| abn | `12345678901`, `13579246810` |\n| org | `123456789`, `135792468` |\n\n### Error Codes\n| Code | Status | Reason | What to do |\n| ---- | ------ | ------ | ---------- |\n| PAM_PAYER_ID_TYPE_FORBIDDEN | 400 | LinkedPayIdType prohibited without linkedPayID| Include `pay_id`|\n| PAM_PAYER_BSB_REQUIRED | 400 | Payer BSB required when not using a PayID | Use `bsb` + `account_number` for bank payers, or switch to `type: email` / phone with `pay_id` for PayID. |\n| PAM_REQUEST_EMPTY | 400 | Request payload is empty | Send `payment_agreement` object with required fields. |\n| PAM_VALIDATION_ERROR | 400 | Request validation failed | Correct invalid/missing fields and retry. |\n| PAM_PAYEE_MISSING | 400 | Payee details are missing | Provide PayID or valid account details. |\n| PAM_PAYEE_ACCT_MISSING | 400 | Payee account details are missing | Include both BSB and account number when required. |\n| PAM_PAYEE_BSB_INVALID | 400 | Payee BSB is invalid | Use a valid 6-digit BSB. |\n| PAM_PAYEE_ACCT_INVALID | 400 | Payee account number is invalid | Provide a valid account number. |\n| PAM_PMT_FREQ_INVALID | 400 | Frequency value is invalid | Use one of supported frequency values. |\n| PAM_PAG_LIMIT_EXCEEDED | 400 | Merchant agreement limit exceeded | Reduce request volume or increase limit. |\n| M101 | 422 | Amount exceeds platform single-agreement threshold | Reduce `maximum_amount` to supported threshold. |\n| M100 | 422 | Amount exceeds merchant agreement limit | Update merchant limits or lower `maximum_amount`. |\n| MOV_NPP_PAYMENT_NOT_SUPPORTED | 422 | Payee account cannot receive NPP payments | Use a valid PayID/account that can receive NPP payments. |\n| MOV_PAYEE_DETAIL_ERROR | 404 | Payee details are incorrect | Correct PayID/BSB/account details. |\n| MOV_INVALID_BSB | 400 | BSB is invalid | Provide a valid BSB and retry. |\n| MOV_REQUEST_TIMEOUT | 408 | Provider request timed out | Retry with backoff and poll status if needed. |\n| VALIDATION_ERROR | 422 | Invalid request fields (for example frequency) | Correct payload format and accepted enum values. |\n| CREDITS_EXHAUSTED | 402 | Developer credits exhausted | Top up developer credits and retry. |\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"payment_agreement"
],
"properties": {
"payment_agreement": {
"$ref": "#/components/schemas/CreatePaymentAgreementRequest"
}
}
},
"examples": {
"valid": {
"summary": "Valid request (stored frequency code)",
"value": {
"payment_agreement": {
"name": "John Smith",
"type": "email",
"maximum_amount": "500",
"maximum_overall_allowed_amount": "2000",
"frequency": "ADHO",
"number_of_transactions_permitted": 10
}
}
},
"frequency_alias": {
"summary": "Alias normalized by API (DAILY→DAIL, ADHOC→ADHO)",
"value": {
"payment_agreement": {
"name": "John Smith",
"type": "email",
"maximum_amount": "500",
"frequency": "DAILY",
"number_of_transactions_permitted": 10
}
}
},
"invalid_frequency": {
"summary": "Invalid frequency (e.g. DAY is not a valid code or alias)",
"value": {
"payment_agreement": {
"name": "Hamza Amin",
"type": "email",
"maximum_amount": "500",
"frequency": "DAY",
"number_of_transactions_permitted": 10
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Payment agreement created and submitted for payer authorization.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessPaymentAgreementResponse"
},
"examples": {
"created": {
"summary": "Agreement created successfully",
"value": {
"message": "Payment Agreement created successfully, Please authorized payment agreement from your banking app.",
"data": {
"payment_agreement_id": "3652PA20260428120000123",
"status": "initiated",
"end_date": "2026-12-31",
"created_at": "2026-04-28T12:00:00.000Z",
"maximum_amount": "500.00",
"extented_status": "500-WEEK-10-initiated"
}
}
}
}
}
}
},
"400": {
"description": "PayTo / payer validation error returned by the upstream provider.\nExamples: missing `pay_id` for email/phone type, or missing bank details for `type: bsb`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"payer_id_type_without_linked_pay_id": {
"summary": "linkedPayIdType without linkedPayId (e.g. only type + frequency)",
"value": {
"message": ".linkedPayIdType prohibited without linkedPayId",
"error_code": "PAM_PAYER_ID_TYPE_FORBIDDEN",
"data": {
"response_time": "2026-05-04T10:52:05.218Z"
}
}
},
"payer_bsb_required": {
"summary": "type bsb without bsb/account (e.g. pay_id used like email)",
"value": {
"message": ".linkedBsb required if no linkedPayId",
"error_code": "PAM_PAYER_BSB_REQUIRED",
"data": {
"response_time": "2026-05-04T11:10:56.372Z"
}
}
}
}
}
}
},
"401": {
"description": "Invalid or missing authorization context.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"unauthorized": {
"summary": "Authorization failed",
"value": {
"message": "Unauthorized Access to an operation",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-28T12:00:00.000Z"
}
}
}
}
}
}
},
"402": {
"description": "Developer credits exhausted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"developer_credits": {
"value": {
"message": "Developer credits exhausted",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-10T12:00:00.000Z"
}
}
}
}
}
}
},
"404": {
"description": "Related resource not found in current merchant context.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"agreement_context_not_found": {
"summary": "Referenced entity not found",
"value": {
"message": "MONOOVA-monoova.PAM_SB_PAG_NOT_FOUND_ERROR",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-28T12:00:00.000Z"
}
}
}
}
}
}
},
"408": {
"description": "Upstream provider timeout while processing agreement creation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"timeout": {
"summary": "Upstream timeout",
"value": {
"message": "Request Timeout",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-28T12:00:00.000Z"
}
}
}
}
}
}
},
"422": {
"description": "Validation or business-rule failure for agreement creation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"invalid_frequency": {
"summary": "Frequency not accepted after normalization",
"value": {
"message": "Invalid frequency value",
"error_code": "VALIDATION_ERROR",
"data": {
"field": "frequency",
"stored_codes": [
"ADHO",
"DAIL",
"FRTN",
"INDA",
"MIAN",
"MNTH",
"QURT",
"WEEK",
"YEAR"
],
"aliases": {
"DAILY": "DAIL",
"ADHOC": "ADHO"
}
}
}
},
"monoova_payee": {
"summary": "Payee cannot receive NPP (example)",
"value": {
"message": "Payee account cannot receive NPP Payments",
"error_code": "MOV_NPP_PAYMENT_NOT_SUPPORTED",
"data": {
"response_time": "2026-04-08T12:28:26.759Z"
}
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"CreatePaymentAgreementRequest": {
"type": "object",
"description": "Request payload used to create a recurring payment agreement for a payer.",
"required": [
"name",
"type",
"maximum_amount",
"frequency",
"number_of_transactions_permitted",
"pay_id"
],
"properties": {
"phone_number": {
"type": "string",
"description": "Optional payer phone number. When provided, the payer profile is looked up/created against this number.",
"example": "+61422020901"
},
"name": {
"type": "string",
"minLength": 2,
"maxLength": 140,
"description": "Payer display name used in agreement records and authorization flow.",
"example": "John Smith"
},
"type": {
"type": "string",
"description": "Identifier type for payer/payee details.\nSandbox `pay_id` suggestions for each type are listed on this endpoint and on the `pay_id` field.\n",
"example": "email",
"enum": [
"email",
"phone",
"abn",
"org",
"bsb"
]
},
"maximum_amount": {
"type": "string",
"description": "Maximum debit amount allowed per transaction under this agreement.",
"example": "500.00"
},
"maximum_overall_allowed_amount": {
"type": "string",
"description": "Optional. Overall collection cap for the agreement (cumulative amount that may be collected across all payment initiations).\nWhen provided, it must be greater than or equal to `maximum_amount`. Once this total is reached, further payment initiations are rejected.\nLeave empty for no overall cap.\n",
"example": "2000.00"
},
"frequency": {
"type": "string",
"description": "Stored codes (after normalization): ADHO, DAIL, FRTN, INDA, MIAN, MNTH, QURT, WEEK, YEAR.\nAliases before save: DAILY→DAIL, ADHOC→ADHO.\n",
"example": "ADHO",
"enum": [
"ADHO",
"DAIL",
"FRTN",
"INDA",
"MIAN",
"MNTH",
"QURT",
"WEEK",
"YEAR",
"DAILY",
"ADHOC"
]
},
"number_of_transactions_permitted": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum number of debits permitted under this agreement.",
"example": 10
},
"pay_id": {
"type": "string",
"description": "PayID used for payer authorization.\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"
},
"bsb": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"description": "BSB value when bank-account based setup is used.",
"example": "123456"
},
"account_number": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"description": "Account number when bank-account based setup is used.",
"example": "987654321"
},
"agreement_type": {
"type": "string",
"description": "Agreement variation/type code used by downstream provider where applicable.",
"example": "VARI"
},
"start_date": {
"type": "string",
"format": "date",
"description": "Optional agreement start date in `YYYY-MM-DD`.",
"example": "2026-05-01"
},
"end_date": {
"type": "string",
"format": "date",
"description": "Optional agreement end date in `YYYY-MM-DD`. Leave empty for open-ended agreement.",
"example": "2026-12-31"
}
}
},
"SuccessPaymentAgreementResponse": {
"type": "object",
"description": "Standard success envelope for payment agreement APIs.",
"properties": {
"message": {
"type": "string",
"description": "Message for the request response.",
"example": "Payment Agreement created successfully, Please authorized payment agreement from your banking app."
},
"data": {
"$ref": "#/components/schemas/PaymentAgreement"
}
}
},
"PaymentAgreement": {
"type": "object",
"description": "Payment agreement object returned by create/get agreement APIs.",
"properties": {
"payment_agreement_id": {
"type": "string",
"description": "Unique agreement identifier. Use this value to retrieve, amend, resend, or cancel the agreement.",
"example": "3652PA20260428120000123"
},
"status": {
"type": "string",
"description": "Current agreement state in the processing lifecycle.",
"example": "initiated"
},
"end_date": {
"type": "string",
"format": "date",
"description": "Agreement end date when set; null/omitted when open-ended.",
"example": "2026-12-31"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Agreement creation timestamp in ISO8601 format.",
"example": "2026-04-28T12:00:00.000Z"
},
"maximum_amount": {
"type": "string",
"description": "Maximum debit amount allowed per agreement.",
"example": "500.00"
},
"maximum_overall_allowed_amount": {
"type": "string",
"description": "Overall collection cap for the agreement when set (cumulative amount across all payment initiations).\n",
"example": "2000.00"
},
"extented_status": {
"type": "string",
"description": "Compact composite status string used by existing clients.",
"example": "500-WEEK-10-initiated"
},
"message": {
"type": "string",
"description": "Present when agreement has a failure message from scheme",
"example": "Payee account cannot receive NPP Payments"
},
"failure_code": {
"type": "string",
"description": "Provider/business failure code when the agreement fails.",
"example": "M100"
}
}
},
"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`."
}
}
}
}