Skip to content
ShaBaas Pay / Docs
Payment Agreement

Show Agreement Status

Retrieve a payment agreement by query parameter id (payment_agreement_id).

Error Codes

CodeStatusReasonWhat to do
GN-0000401Unauthorized Access to an operationSend a valid bearer token.
PAM_SB_PAG_NOT_FOUND_ERROR404Agreement not found for this merchant (includes missing id)Confirm id and merchant ownership.
PAM_NPP_GATEWAY_TIMEOUT408Upstream timeoutRetry with backoff; contact support if persistent.
get/api/public/payment_agreement

Show Agreement Status

Retrieve a payment agreement by query parameter id (payment_agreement_id).

Error Codes

CodeStatusReasonWhat to do
GN-0000401Unauthorized Access to an operationSend a valid bearer token.
PAM_SB_PAG_NOT_FOUND_ERROR404Agreement not found for this merchant (includes missing id)Confirm id and merchant ownership.
PAM_NPP_GATEWAY_TIMEOUT408Upstream timeoutRetry with backoff; contact support if persistent.

Servers

Staging: https://dev-api.shabaas.com

Production: https://api.shabaas.com

Authentication

BearerAuthAuthorization: Bearer <token>

Bearer token returned by /api/public/authorization.

Parameters

idqueryRequired

payment_agreement_id

string

Responses

200Payment agreement details retrieved successfully.
application/json

Standard success envelope for payment agreement APIs.

object

Properties

messageOptionalstring

Message for the request response.

string
Example
"Payment Agreement created successfully, Please authorized payment agreement from your banking app."
dataOptionalobject

Payment agreement object returned by create/get agreement APIs.

object

Properties

payment_agreement_idOptionalstring

Unique agreement identifier. Use this value to retrieve, amend, resend, or cancel the agreement.

string
Example
"3652PA20260428120000123"
statusOptionalstring

Current agreement state in the processing lifecycle.

string
Example
"initiated"
end_dateOptionalstring

Agreement end date when set; null/omitted when open-ended.

stringformat: date
Example
"2026-12-31"
created_atOptionalstring

Agreement creation timestamp in ISO8601 format.

stringformat: date-time
Example
"2026-04-28T12:00:00.000Z"
maximum_amountOptionalstring

Maximum debit amount allowed per agreement.

string
Example
"500.00"
maximum_overall_allowed_amountOptionalstring

Overall collection cap for the agreement when set (cumulative amount across all payment initiations).

string
Example
"2000.00"
extented_statusOptionalstring

Compact composite status string used by existing clients.

string
Example
"500-WEEK-10-initiated"
messageOptionalstring

Present when agreement has a failure message from scheme

string
Example
"Payee account cannot receive NPP Payments"
failure_codeOptionalstring

Provider/business failure code when the agreement fails.

string
Example
"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/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.

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

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

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

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