Skip to content
ShaBaas Pay / Docs
Payment Agreement

Bilateral Agreement

Submit bilateral amendment details for an existing payment agreement.

Error Codes

CodeStatusReasonWhat to do
PAM_AMEND_FORBIDDEN400Agreement status does not allow amendAmend only active/paused eligible agreements.
PAM_AMEND_PENDING400Pending bilateral amend already existsWait for current amend to complete before retrying.
PAM_ACTION_INVALID400Invalid amend action/state transitionCorrect status/action inputs and retry.
PAM_SB_PAG_NOT_FOUND_ERROR404Payment agreement not foundVerify the target agreement id or phone mapping.
M101422Requested amount exceeds hard thresholdLower maximum_amount to an allowed value.
M100422Requested amount exceeds merchant limitIncrease merchant limit or lower the requested amount.
MOV_AMEND_STATUS_VALIDATION_FAILED400Amendment status validation failedEnsure amend request fields are valid for current status.
MOV_MULTIPLE_FIELD_CHANGE_ERROR400Unsupported multiple-field amend with response timeAmend fewer fields per request and retry.
patch/api/public/payment_agreement/bilateral

Bilateral Agreement

Submit bilateral amendment details for an existing payment agreement.

Error Codes

CodeStatusReasonWhat to do
PAM_AMEND_FORBIDDEN400Agreement status does not allow amendAmend only active/paused eligible agreements.
PAM_AMEND_PENDING400Pending bilateral amend already existsWait for current amend to complete before retrying.
PAM_ACTION_INVALID400Invalid amend action/state transitionCorrect status/action inputs and retry.
PAM_SB_PAG_NOT_FOUND_ERROR404Payment agreement not foundVerify the target agreement id or phone mapping.
M101422Requested amount exceeds hard thresholdLower maximum_amount to an allowed value.
M100422Requested amount exceeds merchant limitIncrease merchant limit or lower the requested amount.
MOV_AMEND_STATUS_VALIDATION_FAILED400Amendment status validation failedEnsure amend request fields are valid for current status.
MOV_MULTIPLE_FIELD_CHANGE_ERROR400Unsupported multiple-field amend with response timeAmend fewer fields per request 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
object

Properties

idRequiredstring
string
maximum_amountRequiredstring
string
frequencyRequiredstring
string
number_of_transactions_permittedRequired

oneOf

string
integer
agreement_typeRequiredstring
string
default
{
  "payment_agreement": {
    "id": "3652PA20260408123221550",
    "maximum_amount": "500",
    "frequency": "WEEK",
    "number_of_transactions_permitted": "10",
    "agreement_type": "VARI"
  }
}

Responses

200Bilateral amendment submitted successfully.
application/json
object

Properties

messageOptionalstring
string
Example
"Success"
dataOptionalobject
object

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

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

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