{"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":{"get":{"tags":["Payment Agreement"],"summary":"Show Agreement Status","description":"Retrieve a payment agreement by query parameter `id` (`payment_agreement_id`).\n\n### Error Codes\n| Code | Status | Reason | What to do |\n| ---- | ------ | ------ | ---------- |\n| GN-0000 | 401 | Unauthorized Access to an operation | Send a valid bearer token. |\n| PAM_SB_PAG_NOT_FOUND_ERROR | 404 | Agreement not found for this merchant (includes missing `id`) | Confirm `id` and merchant ownership. |\n| PAM_NPP_GATEWAY_TIMEOUT | 408 | Upstream timeout | Retry with backoff; contact support if persistent. |\n","parameters":[{"in":"query","name":"id","required":true,"schema":{"type":"string"},"description":"payment_agreement_id"}],"responses":{"200":{"description":"Payment agreement details retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessPaymentAgreementResponse"},"examples":{"found":{"summary":"Agreement found","value":{"message":"Success","data":{"payment_agreement_id":"3652PA20260428120000123","status":"active","end_date":"2026-12-31","created_at":"2026-04-28T12:00:00.000Z","maximum_amount":"500.00","extented_status":"500-WEEK-10-active"}}}}}}},"401":{"description":"Missing or invalid bearer session after decode (no header, unknown `jti`, or inactive merchant).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missing_authorization":{"summary":"No Authorization header","value":{"message":"Unauthorized Access to an operation","error_code":"GN-0000","data":{"response_time":"2026-04-28T12:00:00.000Z"}}},"unknown_merchant":{"summary":"Token decoded but merchant not found for jti","value":{"message":"Unauthorized Access to an operation","error_code":"GN-0000","data":{"response_time":"2026-04-28T12:00:00.000Z"}}},"account_inactive":{"summary":"Merchant account not activated","value":{"message":"Account not activated yet","error_code":"GN-0000","data":{"response_time":"2026-04-28T12:00:00.000Z"}}}}}}},"403":{"description":"Bearer token could not be decoded (`JWT::DecodeError`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_jwt":{"summary":"Malformed or invalid JWT","value":{"message":"Unauthorized Access to an operation","error_code":"GN-0000","data":{"response_time":"2026-04-28T12:00:00.000Z"}}}}}}},"404":{"description":"No agreement found (`PAM_SB_PAG_NOT_FOUND_ERROR`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unknown_or_wrong_id":{"summary":"Unknown payment_agreement_id or wrong merchant","value":{"message":"PaymentAgreement not found for PaymentAgreementUID","error_code":"PAM_SB_PAG_NOT_FOUND_ERROR","data":{"response_time":"2026-04-28T12:00:00.000Z"}}},"missing_id":{"summary":"id query parameter omitted","value":{"message":"PaymentAgreement not found for PaymentAgreementUID","error_code":"PAM_SB_PAG_NOT_FOUND_ERROR","data":{"response_time":"2026-04-28T12:00:00.000Z"}}}}}}},"408":{"description":"Upstream timeout while fetching agreement status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"timeout":{"summary":"Upstream timeout","value":{"message":"Request Timeout","error_code":"GN-0000","data":{"response_time":"2026-04-28T12:00:00.000Z"}}}}}}}}}}},"components":{"schemas":{"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`."}}}}