Skip to content
ShaBaas Pay / Docs
Payment Agreement

Create one-time payment agreement

Create a one-time payment agreement flow linked to checkout.

Error Codes

CodeStatusReasonWhat to do
GN-0000400Request payload is emptyProvide payment_agreement object with required fields.
PAM_NPP_GATEWAY_ERROR422Upstream processing errorRetry request; if repeated, contact support with request details.
PAM_NPP_GATEWAY_TIMEOUT408Upstream timeoutRetry with backoff and poll status.
post/api/public/payment_agreement/one_time

Create one-time payment agreement

Create a one-time payment agreement flow linked to checkout.

Error Codes

CodeStatusReasonWhat to do
GN-0000400Request payload is emptyProvide payment_agreement object with required fields.
PAM_NPP_GATEWAY_ERROR422Upstream processing errorRetry request; if repeated, contact support with request details.
PAM_NPP_GATEWAY_TIMEOUT408Upstream timeoutRetry with backoff and poll status.

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 one-time payment agreement flow.

object

Properties

phone_numberOptionalstring

Optional payer mobile number used to look up or create a payer profile.

string
Example
"+61422020901"
nameRequiredstring

Payer display name shown in agreement flow.

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

One-time debit amount for this agreement flow.

oneOf

string
number
Example
"100.00"
notesOptionalstring

Optional short note/description attached to the one-time flow.

stringmaxLength: 140
Example
"Invoice 1042"
bsbOptional

Optional BSB when account-based payer details are used.

oneOf

string
integer
Example
"123456"
account_numberOptional

Optional account number when account-based payer details are used.

oneOf

string
integer
Example
"987654321"
typeRequiredstring

Identifier type hint for payer details. Sandbox pay_id suggestions for each type are listed on Create PayTo Agreement and on the pay_id field.

stringallowed: "email", "phone", "abn", "org", "bsb"default: "email"
Example
"email"
pay_idRequiredstring

Required PayID value for payer authorization context.

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
agreement_typeOptionalstring

Optional agreement type code used by downstream provider.

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.

stringformat: date
Example
"2026-05-31"
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

200One-time payment 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"
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/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.

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