Create one-time payment agreement
Create a one-time payment agreement flow linked to checkout.
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| GN-0000 | 400 | Request payload is empty | Provide payment_agreement object with required fields. |
| PAM_NPP_GATEWAY_ERROR | 422 | Upstream processing error | Retry request; if repeated, contact support with request details. |
| PAM_NPP_GATEWAY_TIMEOUT | 408 | Upstream timeout | Retry with backoff and poll status. |
/api/public/payment_agreement/one_timeCreate one-time payment agreement
Create a one-time payment agreement flow linked to checkout.
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| GN-0000 | 400 | Request payload is empty | Provide payment_agreement object with required fields. |
| PAM_NPP_GATEWAY_ERROR | 422 | Upstream processing error | Retry request; if repeated, contact support with request details. |
| PAM_NPP_GATEWAY_TIMEOUT | 408 | Upstream timeout | Retry with backoff and poll status. |
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 one-time payment agreement flow.
Properties
phone_numberOptionalstringOptional payer mobile number used to look up or create a payer profile.
"+61422020901"nameRequiredstringPayer display name shown in agreement flow.
"John Smith"amountRequiredOne-time debit amount for this agreement flow.
oneOf
"100.00"notesOptionalstringOptional short note/description attached to the one-time flow.
"Invoice 1042"bsbOptionalOptional BSB when account-based payer details are used.
oneOf
"123456"account_numberOptionalOptional account number when account-based payer details are used.
oneOf
"987654321"typeRequiredstringIdentifier type hint for payer details.
Sandbox pay_id suggestions for each type are listed on Create PayTo Agreement and on the pay_id field.
"email"pay_idRequiredstringRequired PayID value for payer authorization context.
Sandbox suggestions (Staging). Production requires a real PayID.
email:sample@shabaas.com,sample@sbpay.auphone:61491570006,61491570156abn:12345678901,13579246810org:123456789,135792468
agreement_typeOptionalstringOptional agreement type code used by downstream provider.
"VARI"start_dateOptionalstringOptional agreement start date in YYYY-MM-DD.
"2026-05-01"end_dateOptionalstringOptional agreement end date in YYYY-MM-DD.
"2026-05-31"destinationOptionalobjectDestination payout account details used when instant payout is enabled.
Properties
bsbOptionalstringDestination BSB (6 digits).
"123456"account_numberOptionalstringDestination account number.
"12345678"Responses
200One-time payment 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"One-time agreement created
{
"message": "Payment Agreement created successfully, Please authorized payment agreement from your banking app.",
"data": {
"payment_agreement_id": "4469PA20260707111156522",
"status": "created",
"end_date": "2027-07-07",
"created_at": "2026-07-07T11:11:56.522Z",
"maximum_amount": "100.0"
}
}422Validation or business-rule error while creating one-time agreement.
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.
Invalid payload
{
"message": "Invalid request payload",
"error_code": "VALIDATION_ERROR",
"data": {
"response_time": "2026-04-28T13:15:00.000Z"
}
}Upstream provider error
{
"message": "MONOOVA-monoova.PAM_NPP_GATEWAY_ERROR",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-28T13:15: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 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/one_time": {
"post": {
"tags": [
"Payment Agreement"
],
"summary": "Create one-time payment agreement",
"description": "Create a one-time payment agreement flow linked to checkout.\n\n### Error Codes\n| Code | Status | Reason | What to do |\n| ---- | ------ | ------ | ---------- |\n| GN-0000 | 400 | Request payload is empty | Provide `payment_agreement` object with required fields. |\n| PAM_NPP_GATEWAY_ERROR | 422 | Upstream processing error | Retry request; if repeated, contact support with request details. |\n| PAM_NPP_GATEWAY_TIMEOUT | 408 | Upstream timeout | Retry with backoff and poll status. |\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"payment_agreement"
],
"properties": {
"payment_agreement": {
"$ref": "#/components/schemas/CreateOneTimePaymentAgreementRequest"
},
"destination": {
"$ref": "#/components/schemas/DestinationAccount"
}
}
}
}
}
},
"responses": {
"200": {
"description": "One-time payment agreement created and submitted for payer authorization.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessPaymentAgreementResponse"
},
"examples": {
"created": {
"summary": "One-time agreement created",
"value": {
"message": "Payment Agreement created successfully, Please authorized payment agreement from your banking app.",
"data": {
"payment_agreement_id": "4469PA20260707111156522",
"status": "created",
"end_date": "2027-07-07",
"created_at": "2026-07-07T11:11:56.522Z",
"maximum_amount": "100.0"
}
}
}
}
}
}
},
"422": {
"description": "Validation or business-rule error while creating one-time agreement.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"validation_error": {
"summary": "Invalid payload",
"value": {
"message": "Invalid request payload",
"error_code": "VALIDATION_ERROR",
"data": {
"response_time": "2026-04-28T13:15:00.000Z"
}
}
},
"provider_error": {
"summary": "Upstream provider error",
"value": {
"message": "MONOOVA-monoova.PAM_NPP_GATEWAY_ERROR",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-28T13:15:00.000Z"
}
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"CreateOneTimePaymentAgreementRequest": {
"type": "object",
"description": "Request payload used to create a one-time payment agreement flow.",
"required": [
"name",
"amount",
"type",
"pay_id"
],
"properties": {
"phone_number": {
"type": "string",
"description": "Optional payer mobile number used to look up or create a payer profile.",
"example": "+61422020901"
},
"name": {
"type": "string",
"minLength": 2,
"maxLength": 140,
"description": "Payer display name shown in agreement flow.",
"example": "John Smith"
},
"amount": {
"oneOf": [
{
"type": "string"
},
{
"type": "number"
}
],
"description": "One-time debit amount for this agreement flow.",
"example": "100.00"
},
"notes": {
"type": "string",
"maxLength": 140,
"description": "Optional short note/description attached to the one-time flow.",
"example": "Invoice 1042"
},
"bsb": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"description": "Optional BSB when account-based payer details are used.",
"example": "123456"
},
"account_number": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"description": "Optional account number when account-based payer details are used.",
"example": "987654321"
},
"type": {
"type": "string",
"description": "Identifier type hint for payer details.\nSandbox `pay_id` suggestions for each type are listed on Create PayTo Agreement and on the `pay_id` field.\n",
"enum": [
"email",
"phone",
"abn",
"org",
"bsb"
],
"default": "email",
"example": "email"
},
"pay_id": {
"type": "string",
"description": "Required PayID value for payer authorization context.\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"
},
"agreement_type": {
"type": "string",
"description": "Optional agreement type code used by downstream provider.",
"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`.",
"example": "2026-05-31"
}
}
},
"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"
}
}
},
"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`."
}
}
}
}