{"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`."}}}}