Show Agreement Status
Retrieve a payment agreement by query parameter id (payment_agreement_id).
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| GN-0000 | 401 | Unauthorized Access to an operation | Send a valid bearer token. |
| PAM_SB_PAG_NOT_FOUND_ERROR | 404 | Agreement not found for this merchant (includes missing id) | Confirm id and merchant ownership. |
| PAM_NPP_GATEWAY_TIMEOUT | 408 | Upstream timeout | Retry with backoff; contact support if persistent. |
/api/public/payment_agreementShow Agreement Status
Retrieve a payment agreement by query parameter id (payment_agreement_id).
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| GN-0000 | 401 | Unauthorized Access to an operation | Send a valid bearer token. |
| PAM_SB_PAG_NOT_FOUND_ERROR | 404 | Agreement not found for this merchant (includes missing id) | Confirm id and merchant ownership. |
| PAM_NPP_GATEWAY_TIMEOUT | 408 | Upstream timeout | Retry with backoff; contact support if persistent. |
Servers
Staging: https://dev-api.shabaas.com
Production: https://api.shabaas.com
Authentication
Authorization: Bearer <token>Bearer token returned by /api/public/authorization.
Parameters
idqueryRequiredpayment_agreement_id
Responses
200Payment agreement details retrieved successfully.
application/jsonStandard success envelope for payment agreement APIs.
Properties
messageOptionalstringMessage for the request response.
"Payment Agreement created successfully, Please authorized payment agreement from your banking app."dataOptionalobjectPayment agreement object returned by create/get agreement APIs.
Properties
payment_agreement_idOptionalstringUnique agreement identifier. Use this value to retrieve, amend, resend, or cancel the agreement.
"3652PA20260428120000123"statusOptionalstringCurrent agreement state in the processing lifecycle.
"initiated"end_dateOptionalstringAgreement end date when set; null/omitted when open-ended.
"2026-12-31"created_atOptionalstringAgreement creation timestamp in ISO8601 format.
"2026-04-28T12:00:00.000Z"maximum_amountOptionalstringMaximum debit amount allowed per agreement.
"500.00"maximum_overall_allowed_amountOptionalstringOverall collection cap for the agreement when set (cumulative amount across all payment initiations).
"2000.00"extented_statusOptionalstringCompact composite status string used by existing clients.
"500-WEEK-10-initiated"messageOptionalstringPresent when agreement has a failure message from scheme
"Payee account cannot receive NPP Payments"failure_codeOptionalstringProvider/business failure code when the agreement fails.
"M100"Agreement found
{
"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"
}
}401Missing or invalid bearer session after decode (no header, unknown `jti`, or inactive merchant).
application/jsonProperties
messageRequiredstring"Payee account cannot receive NPP Payments"error_codeRequiredstring"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobject{
"response_time": "2026-04-08T12:28:26.759Z"
}Additional properties are supported; see the endpoint definition for their schema.
No Authorization header
{
"message": "Unauthorized Access to an operation",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-28T12:00:00.000Z"
}
}Token decoded but merchant not found for jti
{
"message": "Unauthorized Access to an operation",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-28T12:00:00.000Z"
}
}Merchant account not activated
{
"message": "Account not activated yet",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-28T12:00:00.000Z"
}
}403Bearer token could not be decoded (`JWT::DecodeError`).
application/jsonProperties
messageRequiredstring"Payee account cannot receive NPP Payments"error_codeRequiredstring"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobject{
"response_time": "2026-04-08T12:28:26.759Z"
}Additional properties are supported; see the endpoint definition for their schema.
Malformed or invalid JWT
{
"message": "Unauthorized Access to an operation",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-28T12:00:00.000Z"
}
}404No agreement found (`PAM_SB_PAG_NOT_FOUND_ERROR`).
application/jsonProperties
messageRequiredstring"Payee account cannot receive NPP Payments"error_codeRequiredstring"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobject{
"response_time": "2026-04-08T12:28:26.759Z"
}Additional properties are supported; see the endpoint definition for their schema.
Unknown payment_agreement_id or wrong merchant
{
"message": "PaymentAgreement not found for PaymentAgreementUID",
"error_code": "PAM_SB_PAG_NOT_FOUND_ERROR",
"data": {
"response_time": "2026-04-28T12:00:00.000Z"
}
}id query parameter omitted
{
"message": "PaymentAgreement not found for PaymentAgreementUID",
"error_code": "PAM_SB_PAG_NOT_FOUND_ERROR",
"data": {
"response_time": "2026-04-28T12:00:00.000Z"
}
}408Upstream timeout while fetching agreement status.
application/jsonProperties
messageRequiredstring"Payee account cannot receive NPP Payments"error_codeRequiredstring"MOV_NPP_PAYMENT_NOT_SUPPORTED"dataRequiredobject{
"response_time": "2026-04-08T12:28:26.759Z"
}Additional properties are supported; see the endpoint definition for their schema.
Upstream timeout
{
"message": "Request Timeout",
"error_code": "GN-0000",
"data": {
"response_time": "2026-04-28T12: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": {
"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`."
}
}
}
}