Payment Agreement
Bilateral Agreement
Submit bilateral amendment details for an existing payment agreement.
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| PAM_AMEND_FORBIDDEN | 400 | Agreement status does not allow amend | Amend only active/paused eligible agreements. |
| PAM_AMEND_PENDING | 400 | Pending bilateral amend already exists | Wait for current amend to complete before retrying. |
| PAM_ACTION_INVALID | 400 | Invalid amend action/state transition | Correct status/action inputs and retry. |
| PAM_SB_PAG_NOT_FOUND_ERROR | 404 | Payment agreement not found | Verify the target agreement id or phone mapping. |
| M101 | 422 | Requested amount exceeds hard threshold | Lower maximum_amount to an allowed value. |
| M100 | 422 | Requested amount exceeds merchant limit | Increase merchant limit or lower the requested amount. |
| MOV_AMEND_STATUS_VALIDATION_FAILED | 400 | Amendment status validation failed | Ensure amend request fields are valid for current status. |
| MOV_MULTIPLE_FIELD_CHANGE_ERROR | 400 | Unsupported multiple-field amend with response time | Amend fewer fields per request and retry. |
patch
/api/public/payment_agreement/bilateralBilateral Agreement
Submit bilateral amendment details for an existing payment agreement.
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| PAM_AMEND_FORBIDDEN | 400 | Agreement status does not allow amend | Amend only active/paused eligible agreements. |
| PAM_AMEND_PENDING | 400 | Pending bilateral amend already exists | Wait for current amend to complete before retrying. |
| PAM_ACTION_INVALID | 400 | Invalid amend action/state transition | Correct status/action inputs and retry. |
| PAM_SB_PAG_NOT_FOUND_ERROR | 404 | Payment agreement not found | Verify the target agreement id or phone mapping. |
| M101 | 422 | Requested amount exceeds hard threshold | Lower maximum_amount to an allowed value. |
| M100 | 422 | Requested amount exceeds merchant limit | Increase merchant limit or lower the requested amount. |
| MOV_AMEND_STATUS_VALIDATION_FAILED | 400 | Amendment status validation failed | Ensure amend request fields are valid for current status. |
| MOV_MULTIPLE_FIELD_CHANGE_ERROR | 400 | Unsupported multiple-field amend with response time | Amend fewer fields per request and retry. |
Servers
Staging: https://dev-api.shabaas.com
Production: https://api.shabaas.com
Authentication
BearerAuth
Authorization: Bearer <token>Bearer token returned by /api/public/authorization.
Request Body
Requiredapplication/jsonobject
Properties
payment_agreementRequiredobjectobject
Properties
idRequiredstringstring
maximum_amountRequiredstringstring
frequencyRequiredstringstring
number_of_transactions_permittedRequiredoneOf
string
integer
agreement_typeRequiredstringstring
default
{
"payment_agreement": {
"id": "3652PA20260408123221550",
"maximum_amount": "500",
"frequency": "WEEK",
"number_of_transactions_permitted": "10",
"agreement_type": "VARI"
}
}Responses
200Bilateral amendment submitted successfully.
application/jsonobject
Properties
messageOptionalstringstring
Example
"Success"dataOptionalobjectobject
Additional properties are supported; see the endpoint definition for their schema.
Amendment request accepted
{
"message": "Payment agreement updated. Please authorise the changes using your banking app.",
"data": {}
}404Target payment agreement not found for merchant context.
application/jsonobject
Properties
messageRequiredstringstring
Example
"Payee account cannot receive NPP Payments"error_codeRequiredstringstring
Example
"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobjectobject
Example
{
"response_time": "2026-04-08T12:28:26.759Z"
}Additional properties are supported; see the endpoint definition for their schema.
Agreement id not found
{
"message": "MONOOVA-monoova.PAM_SB_PAG_NOT_FOUND_ERROR",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-28T12:00:00.000Z"
}
}422Validation or business-rule error while applying amendment.
application/jsonobject
Properties
messageRequiredstringstring
Example
"Payee account cannot receive NPP Payments"error_codeRequiredstringstring
Example
"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobjectobject
Example
{
"response_time": "2026-04-08T12:28:26.759Z"
}Additional properties are supported; see the endpoint definition for their schema.
amount_rule
{
"message": "Amount exceeds merchant limit",
"error_code": "M100",
"data": {
"response_time": "2026-04-10T12:00:00.000Z"
}
}Full endpoint OpenAPI definition
{
"openapi": "3.0.3",
"info": {
"title": "ShaBaasPay Public API",
"version": "1.0.0",
"description": "Describes public REST endpoints for authorization, payment agreements, payment initiations,\nrefunds, webhooks, and PayID collection APIs.\n"
},
"servers": [
{
"url": "https://dev-api.shabaas.com",
"description": "Staging"
},
{
"url": "https://api.shabaas.com",
"description": "Production"
}
],
"tags": [
{
"name": "Payment 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/bilateral": {
"patch": {
"tags": [
"Payment Agreement"
],
"summary": "Bilateral Agreement",
"description": "Submit bilateral amendment details for an existing payment agreement.\n\n### Error Codes\n| Code | Status | Reason | What to do |\n| ---- | ------ | ------ | ---------- |\n| PAM_AMEND_FORBIDDEN | 400 | Agreement status does not allow amend | Amend only active/paused eligible agreements. |\n| PAM_AMEND_PENDING | 400 | Pending bilateral amend already exists | Wait for current amend to complete before retrying. |\n| PAM_ACTION_INVALID | 400 | Invalid amend action/state transition | Correct status/action inputs and retry. |\n| PAM_SB_PAG_NOT_FOUND_ERROR | 404 | Payment agreement not found | Verify the target agreement id or phone mapping. |\n| M101 | 422 | Requested amount exceeds hard threshold | Lower `maximum_amount` to an allowed value. |\n| M100 | 422 | Requested amount exceeds merchant limit | Increase merchant limit or lower the requested amount. |\n| MOV_AMEND_STATUS_VALIDATION_FAILED | 400 | Amendment status validation failed | Ensure amend request fields are valid for current status. |\n| MOV_MULTIPLE_FIELD_CHANGE_ERROR | 400 | Unsupported multiple-field amend with response time | Amend fewer fields per request and retry. |\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"payment_agreement"
],
"properties": {
"payment_agreement": {
"$ref": "#/components/schemas/BilateralAmendPaymentAgreementRequest"
}
}
},
"examples": {
"default": {
"value": {
"payment_agreement": {
"id": "3652PA20260408123221550",
"maximum_amount": "500",
"frequency": "WEEK",
"number_of_transactions_permitted": "10",
"agreement_type": "VARI"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Bilateral amendment submitted successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageResponse"
},
"examples": {
"amended": {
"summary": "Amendment request accepted",
"value": {
"message": "Payment agreement updated. Please authorise the changes using your banking app.",
"data": {}
}
}
}
}
}
},
"404": {
"description": "Target payment agreement not found for merchant context.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"not_found": {
"summary": "Agreement id 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"
}
}
}
}
}
}
},
"422": {
"description": "Validation or business-rule error while applying amendment.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"amount_rule": {
"value": {
"message": "Amount exceeds merchant limit",
"error_code": "M100",
"data": {
"response_time": "2026-04-10T12:00:00.000Z"
}
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"BilateralAmendPaymentAgreementRequest": {
"type": "object",
"required": [
"id",
"maximum_amount",
"frequency",
"number_of_transactions_permitted",
"agreement_type"
],
"properties": {
"id": {
"type": "string"
},
"maximum_amount": {
"type": "string"
},
"frequency": {
"type": "string"
},
"number_of_transactions_permitted": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"agreement_type": {
"type": "string"
}
}
},
"MessageResponse": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Success"
},
"data": {
"type": "object",
"additionalProperties": true
}
}
},
"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`."
}
}
}
}