Skip to content
ShaBaas Pay / Docs
Payment Agreement

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.

typeSuggested pay_id
emailsample@shabaas.com, sample@sbpay.au
phone61491570006, 61491570156
abn12345678901, 13579246810
org123456789, 135792468

Error Codes

CodeStatusReasonWhat to do
PAM_PAYER_ID_TYPE_FORBIDDEN400LinkedPayIdType prohibited without linkedPayIDInclude pay_id
PAM_PAYER_BSB_REQUIRED400Payer BSB required when not using a PayIDUse bsb + account_number for bank payers, or switch to type: email / phone with pay_id for PayID.
PAM_REQUEST_EMPTY400Request payload is emptySend payment_agreement object with required fields.
PAM_VALIDATION_ERROR400Request validation failedCorrect invalid/missing fields and retry.
PAM_PAYEE_MISSING400Payee details are missingProvide PayID or valid account details.
PAM_PAYEE_ACCT_MISSING400Payee account details are missingInclude both BSB and account number when required.
PAM_PAYEE_BSB_INVALID400Payee BSB is invalidUse a valid 6-digit BSB.
PAM_PAYEE_ACCT_INVALID400Payee account number is invalidProvide a valid account number.
PAM_PMT_FREQ_INVALID400Frequency value is invalidUse one of supported frequency values.
PAM_PAG_LIMIT_EXCEEDED400Merchant agreement limit exceededReduce request volume or increase limit.
M101422Amount exceeds platform single-agreement thresholdReduce maximum_amount to supported threshold.
M100422Amount exceeds merchant agreement limitUpdate merchant limits or lower maximum_amount.
MOV_NPP_PAYMENT_NOT_SUPPORTED422Payee account cannot receive NPP paymentsUse a valid PayID/account that can receive NPP payments.
MOV_PAYEE_DETAIL_ERROR404Payee details are incorrectCorrect PayID/BSB/account details.
MOV_INVALID_BSB400BSB is invalidProvide a valid BSB and retry.
MOV_REQUEST_TIMEOUT408Provider request timed outRetry with backoff and poll status if needed.
VALIDATION_ERROR422Invalid request fields (for example frequency)Correct payload format and accepted enum values.
CREDITS_EXHAUSTED402Developer credits exhaustedTop up developer credits and retry.
post/api/public/payment_agreement

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.

typeSuggested pay_id
emailsample@shabaas.com, sample@sbpay.au
phone61491570006, 61491570156
abn12345678901, 13579246810
org123456789, 135792468

Error Codes

CodeStatusReasonWhat to do
PAM_PAYER_ID_TYPE_FORBIDDEN400LinkedPayIdType prohibited without linkedPayIDInclude pay_id
PAM_PAYER_BSB_REQUIRED400Payer BSB required when not using a PayIDUse bsb + account_number for bank payers, or switch to type: email / phone with pay_id for PayID.
PAM_REQUEST_EMPTY400Request payload is emptySend payment_agreement object with required fields.
PAM_VALIDATION_ERROR400Request validation failedCorrect invalid/missing fields and retry.
PAM_PAYEE_MISSING400Payee details are missingProvide PayID or valid account details.
PAM_PAYEE_ACCT_MISSING400Payee account details are missingInclude both BSB and account number when required.
PAM_PAYEE_BSB_INVALID400Payee BSB is invalidUse a valid 6-digit BSB.
PAM_PAYEE_ACCT_INVALID400Payee account number is invalidProvide a valid account number.
PAM_PMT_FREQ_INVALID400Frequency value is invalidUse one of supported frequency values.
PAM_PAG_LIMIT_EXCEEDED400Merchant agreement limit exceededReduce request volume or increase limit.
M101422Amount exceeds platform single-agreement thresholdReduce maximum_amount to supported threshold.
M100422Amount exceeds merchant agreement limitUpdate merchant limits or lower maximum_amount.
MOV_NPP_PAYMENT_NOT_SUPPORTED422Payee account cannot receive NPP paymentsUse a valid PayID/account that can receive NPP payments.
MOV_PAYEE_DETAIL_ERROR404Payee details are incorrectCorrect PayID/BSB/account details.
MOV_INVALID_BSB400BSB is invalidProvide a valid BSB and retry.
MOV_REQUEST_TIMEOUT408Provider request timed outRetry with backoff and poll status if needed.
VALIDATION_ERROR422Invalid request fields (for example frequency)Correct payload format and accepted enum values.
CREDITS_EXHAUSTED402Developer credits exhaustedTop up developer credits and retry.

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

payment_agreementRequiredobject

Request payload used to create a recurring payment agreement for a payer.

object

Properties

phone_numberOptionalstring

Optional payer phone number. When provided, the payer profile is looked up/created against this number.

string
Example
"+61422020901"
nameRequiredstring

Payer display name used in agreement records and authorization flow.

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

Identifier type for payer/payee details. Sandbox pay_id suggestions for each type are listed on this endpoint and on the pay_id field.

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

Maximum debit amount allowed per transaction under this agreement.

string
Example
"500.00"
maximum_overall_allowed_amountOptionalstring

Optional. 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.

string
Example
"2000.00"
frequencyRequiredstring

Stored codes (after normalization): ADHO, DAIL, FRTN, INDA, MIAN, MNTH, QURT, WEEK, YEAR. Aliases before save: DAILY→DAIL, ADHOC→ADHO.

stringallowed: "ADHO", "DAIL", "FRTN", "INDA", "MIAN", "MNTH", "QURT", "WEEK", "YEAR", "DAILY", "ADHOC"
Example
"ADHO"
number_of_transactions_permittedRequiredinteger

Maximum number of debits permitted under this agreement.

integerminimum: 1maximum: 1000
Example
10
pay_idRequiredstring

PayID used for payer authorization.

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
bsbOptional

BSB value when bank-account based setup is used.

oneOf

string
integer
Example
"123456"
account_numberOptional

Account number when bank-account based setup is used.

oneOf

string
integer
Example
"987654321"
agreement_typeOptionalstring

Agreement variation/type code used by downstream provider where applicable.

string
Example
"VARI"
start_dateOptionalstring

Optional agreement start date in YYYY-MM-DD.

stringformat: date
Example
"2026-05-01"
end_dateOptionalstring

Optional agreement end date in YYYY-MM-DD. Leave empty for open-ended agreement.

stringformat: date
Example
"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/json

Standard success envelope for payment agreement APIs.

object

Properties

messageOptionalstring

Message for the request response.

string
Example
"Payment Agreement created successfully, Please authorized payment agreement from your banking app."
dataOptionalobject

Payment agreement object returned by create/get agreement APIs.

object

Properties

payment_agreement_idOptionalstring

Unique agreement identifier. Use this value to retrieve, amend, resend, or cancel the agreement.

string
Example
"3652PA20260428120000123"
statusOptionalstring

Current agreement state in the processing lifecycle.

string
Example
"initiated"
end_dateOptionalstring

Agreement end date when set; null/omitted when open-ended.

stringformat: date
Example
"2026-12-31"
created_atOptionalstring

Agreement creation timestamp in ISO8601 format.

stringformat: date-time
Example
"2026-04-28T12:00:00.000Z"
maximum_amountOptionalstring

Maximum debit amount allowed per agreement.

string
Example
"500.00"
maximum_overall_allowed_amountOptionalstring

Overall collection cap for the agreement when set (cumulative amount across all payment initiations).

string
Example
"2000.00"
extented_statusOptionalstring

Compact composite status string used by existing clients.

string
Example
"500-WEEK-10-initiated"
messageOptionalstring

Present when agreement has a failure message from scheme

string
Example
"Payee account cannot receive NPP Payments"
failure_codeOptionalstring

Provider/business failure code when the agreement fails.

string
Example
"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/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.

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/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.

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/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.

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/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.

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/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.

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/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.

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`."
      }
    }
  }
}
Download endpoint OpenAPI JSON →
← Back to API Reference