> ## Documentation Index > Fetch the complete documentation index at: https://docs.rc.cleverhub.co/llms.txt > Use this file to discover all available pages before exploring further. # Get Payment Agreements > Retrieve a paginated list of payment agreements within a specified time range. This endpoint enables merchants to query and filter payment agreements based on date parameters, allowing for efficient management and monitoring of agreement records over a specified period. The query supports pagination, making it possible to navigate through large datasets by specifying the page number and the number of records per page. ## OpenAPI ````yaml /api/openapi/v1-reference.yaml get /v1/pay_to/payment_agreement/search openapi: 3.0.3 info: title: Payment APIs (AUD only) description: >- ## Introduction The Payment API Solution (AUD) offers developers a comprehensive suite of API services to build innovative AUD payment solutions efficiently. These APIs enable seamless transactions using various payment methods and functionalities, ensuring a robust, reliable, and scalable payment infrastructure tailored for the Australian market. ### Key Features - **Payment Methods**: - **Payment Link**: Supports payments via card and PayID. - **PayID**: Provides instant payments using a unique identifier. - **PayTo**: Enables scheduled or recurring payments. - **BSB/Account Number**: Allows direct bank transfers. - **Payout**: Manage payouts to designated accounts. - **Additional Functionalities**: - **Balance Management**: Real-time balance inquiries and updates. - **Reporting Services**: Generate detailed transaction and payment reports. This documentation provides detailed guidance for integrating these capabilities into your application. termsOfService: https://helloclever.co/terms contact: email: support@helloclever.co version: 1.0.11 servers: - url: https://api.cleverhub.co/api description: Sandbox Environment - url: https://api-merchant.helloclever.co/api description: Production Environment security: [] paths: /v1/pay_to/payment_agreement/search: get: tags: - AUD PayTo summary: Get Payment Agreements description: > Retrieve a paginated list of payment agreements within a specified time range. This endpoint enables merchants to query and filter payment agreements based on date parameters, allowing for efficient management and monitoring of agreement records over a specified period. The query supports pagination, making it possible to navigate through large datasets by specifying the page number and the number of records per page. parameters: - in: query name: from_date required: true schema: type: string format: date-time description: > The start date for querying payment agreements. Accepted formats are 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This date-time is in UTC. example: '2022-01-01T00:00:00' - in: query name: to_date required: true schema: type: string format: date-time description: > The end date for querying payment agreements. Accepted formats are 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This date-time is in UTC. example: '2022-12-01T00:00:00' - in: query name: page required: false schema: type: integer description: > The page number to retrieve. Each page contains a subset of results based on the specified `size` parameter. example: 1 - in: query name: size required: false schema: type: integer description: > The number of records to return per page. This allows you to control the volume of data returned in each response, aiding in efficient data management. example: 20 responses: '200': description: Request processed successfully. content: application/json: schema: type: object properties: from_date: type: string format: date-time description: >- The start date of the queried payment agreements, as specified in the request. example: '2022-01-01T00:00:00' to_date: type: string format: date-time description: >- The end date of the queried payment agreements, as specified in the request. example: '2022-12-01T00:00:00' page: type: integer description: The current page number of the returned results. example: 1 size: type: integer description: The number of records per page as specified in the query. example: 20 next_page: type: integer description: The page number for the next set of results, if available. example: 2 total_page: type: integer description: >- The total number of pages available based on the query parameters. example: 5 total_count: type: integer description: >- The total number of payment agreement records available within the specified date range. example: 100 records: type: array items: $ref: '#/components/schemas/PayToObject' '400': description: Bad Request '401': description: Unauthorized '422': description: Unprocessable Entity security: - app-id: [] secret-key: [] components: schemas: PayToObject: type: object properties: id: type: integer description: > A unique identifier for the payment agreement, used for tracking and management. example: 12345 payment_agreement_id: type: string description: > The unique identifier for the payment agreement, providing a reference to the specific agreement being handled. example: agreement-12345 client_transaction_id: type: string description: > A unique ID for the transaction as provided by the merchant, used to ensure transactions can be uniquely tracked. minLength: 1 maxLength: 90 example: client-trans-001 limit_amount: type: number description: > The maximum allowable amount for each payment under this agreement, helping to manage the scope of transactions. example: 5000 description: type: string description: > A description of the payment agreement, providing context and information for the payer and merchant. minLength: 5 maxLength: 140 example: Monthly utility bill payment agreement. external_id: type: string description: > A custom identifier assigned to the payment agreement, typically used for tracking and reference purposes. maxLength: 255 example: custom-agreement-id-7890 status: type: string enum: - created - active - suspended - cancelled - failed description: > The current status of the payment agreement. Possible values include: - `created`: Agreement has been created but not yet activated. - `active`: Agreement is currently active. - `suspended`: Agreement has been temporarily suspended. - `cancelled`: Agreement has been cancelled. - `failed`: Agreement creation or payment has failed. example: active created_at: type: string format: date-time description: > The timestamp indicating when the payment agreement was created, in UTC. example: '2024-01-01T00:00:00Z' payment_agreement_type: type: string enum: - MORTGAGE - UTILITY - LOAN - DEPENDANT SUPPORT - GAMBLING - RETAIL - SALARY - PERSONAL - GOVERNMENT - PENSION - TAX - OTHER SERVICE description: > The type of payment agreement, indicating the nature of the payments involved. example: UTILITY agreement_details: oneOf: - $ref: '#/components/schemas/variable_agreement_details_obj' - $ref: '#/components/schemas/fixed_agreement_details_obj' - $ref: '#/components/schemas/usage_bases_agreement_details_obj' - $ref: '#/components/schemas/balloon_agreement_details_obj' payer_details: type: object description: > Details about the payer, including either bank account information or PayID details. properties: name: type: string description: | The name of the payer, used for identification and verification. pattern: ^(?![! ](?![!]*$))[a-zA-Z0-9 ]*(?![ ])$ example: Jane Doe bank_account_details: type: object description: > Information about the payer's bank account, used for transactions involving bank details. properties: bsb: type: string description: > The BSB (Bank-State-Branch) number of the payer's account, used to identify the bank and branch. example: '123456' account_number: type: string description: | The account number associated with the payer's bank account. example: '987654321' pay_id_details: type: object description: > Information about the payer's PayID, used for transactions involving a PayID. properties: pay_id: type: string description: > The PayID associated with the payer, allowing payments to be routed via this ID. example: payer@payid.com pay_id_type: type: string enum: - EMAIL - PHONE - ABN description: | The type of PayID being used. Valid values include: - `EMAIL`: An email address. - `PHONE`: A mobile or landline number. - `ABN`: An Australian Business Number. example: EMAIL payment_agreement_notification: type: object description: > Details for the merchant callback, including endpoint URL and authorization header for receiving status updates on the payment agreement. properties: endpoint_url: type: string format: uri description: > The URL to which Hello Clever will send notifications when the status of a transaction changes. The endpoint must be internet accessible and secured by TLS 1.2 or higher. example: https://merchant.com/payment_callback authorization_header: type: string description: > The authorization value that Hello Clever will include in the callback request header to authenticate the request. example: Bearer your_token variable_agreement_details_obj: type: object properties: variable_agreement_details_obj: type: object properties: start_date: type: string description: > The start date for the variable payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone. example: 15/07/24 frequency: type: string enum: - ADHOC - DAILY - FORTNIGHTLY - INTRADAY - SEMIANNUAL - MONTHLY - QUARTERLY - WEEKLY - ANNUAL description: > The frequency of payments for the agreement, indicating how often payments will occur. example: MONTHLY fixed_agreement_details_obj: type: object properties: fixed_agreement_details_obj: type: object properties: start_date: type: string description: > The start date for the fixed payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone. example: 01/01/24 frequency: type: string enum: - ADHOC - DAILY - FORTNIGHTLY - INTRADAY - SEMIANNUAL - MONTHLY - QUARTERLY - WEEKLY - ANNUAL description: > The frequency of payments for the agreement, indicating how often payments will occur. example: ANNUAL usage_bases_agreement_details_obj: type: object properties: usage_bases_agreement_details_obj: type: object properties: start_date: type: string description: > The start date for the usage-based payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone. example: 10/03/24 frequency: type: string enum: - ADHOC - DAILY - FORTNIGHTLY - INTRADAY - SEMIANNUAL - MONTHLY - QUARTERLY - WEEKLY - ANNUAL description: > The frequency of payments for the agreement, indicating how often payments will occur. example: WEEKLY balloon_agreement_details_obj: type: object properties: balloon_agreement_details_obj: type: object properties: start_date: type: string description: > The start date for the balloon payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone. example: 20/11/24 frequency: type: string enum: - ADHOC - DAILY - FORTNIGHTLY - INTRADAY - SEMIANNUAL - MONTHLY - QUARTERLY - WEEKLY - ANNUAL description: > The frequency of payments for the agreement, indicating how often payments will occur. example: FORTNIGHTLY securitySchemes: app-id: type: apiKey in: header name: app-id description: | A unique identifier assigned to each application. secret-key: type: apiKey in: header name: secret-key description: | A secure token associated with the `app-id`. ```` ## Related topics - [Get Payment Agreement Detail](/api/aud-payto/get-payment-agreement-detail.md) - [Build Recurring Billing with PayTo Agreements](/developer-reference/api-use-cases/build-recurring-billing-with-payto-agreements.md) - [Amend Payment Agreement](/api/aud-payto/amend-payment-agreement.md)