> ## 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. # Create Payment Agreement > Create a payment agreement that enables recurring or one-time payments between merchants and payers. This agreement specifies the transaction structure, including payment limits, agreement type, and callback details for status notifications. Available payment methods: - `pay_id`: Use PayID as the payment method, which can be an email, phone number, or Australian Business Number (ABN). This provides a secure and streamlined payment option using a unique identifier. - `bsb`: Use BSB (Bank-State-Branch) and account number as the payment method, which is suitable for direct bank transfers within Australia. The endpoint also supports merchant callback configurations to notify merchants of status changes in the payment agreement. ## OpenAPI ````yaml /api/openapi/v1-reference.yaml post /v1/pay_to/payment_agreement 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: post: tags: - AUD PayTo summary: Create Payment Agreement description: > Create a payment agreement that enables recurring or one-time payments between merchants and payers. This agreement specifies the transaction structure, including payment limits, agreement type, and callback details for status notifications. Available payment methods: - `pay_id`: Use PayID as the payment method, which can be an email, phone number, or Australian Business Number (ABN). This provides a secure and streamlined payment option using a unique identifier. - `bsb`: Use BSB (Bank-State-Branch) and account number as the payment method, which is suitable for direct bank transfers within Australia. The endpoint also supports merchant callback configurations to notify merchants of status changes in the payment agreement. requestBody: required: true content: application/json: schema: type: object required: - client_transaction_id - limit_amount - description - payment_agreement_type - agreement_details - payer_details - payment_agreement_notification properties: client_transaction_id: type: string minLength: 1 maxLength: 90 description: >- Unique identifier for the transaction created by the merchant’s system. example: txn-12345 limit_amount: type: number description: > Maximum payment amount allowed for each transaction under this agreement. If using a fixed agreement, this amount should match the intended charge. example: 500 description: type: string minLength: 5 maxLength: 140 description: Brief description of the payment agreement. example: Monthly utility payment external_id: type: string maxLength: 255 description: >- Custom identifier provided by the merchant for tracking purposes. example: ext-123456 payment_agreement_type: type: string enum: - MORTGAGE - UTILITY - LOAN - DEPENDANT_SUPPORT - GAMBLING - RETAIL - SALARY - PERSONAL - GOVERNMENT - PENSION - TAX - OTHER_SERVICE description: Type of the payment agreement. 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 required: - name - bank_account_details - pay_id_details description: >- Payer details, with either `bank_account_details` or `pay_id_details` required. properties: name: type: string description: The payer's full name. pattern: ^(?![! ](?![!]*$))[a-zA-Z0-9 ]*(?![ ])$ example: John Doe bank_account_details: type: object required: - bsb - account_number description: Details of the payer’s bank account. properties: bsb: type: string description: Bank State Branch (BSB) number for the account. example: '123456' account_number: type: string description: Account number associated with the BSB. example: '987654321' pay_id_details: type: object required: - pay_id - pay_id_type description: Details of the payer’s PayID. properties: pay_id: type: string description: The payer's PayID. example: payer@example.com pay_id_type: type: string enum: - EMAIL - PHONE - ABN description: > Type of PayID: - EMAIL: Email address. - PHONE: Phone number, including area code (e.g., +61-32832832). - ABN: Australian Business Number. example: EMAIL payment_agreement_notification: type: object required: - endpoint_url - authorization_header description: >- Callback configuration for receiving payment agreement status updates. properties: endpoint_url: type: string format: uri description: > URL for receiving payment agreement status notifications. Must be internet-accessible. example: https://merchant.example.com/payment_status_callback authorization_header: type: string description: > Token for the Authorization header in the callback request for security. example: Bearer your_secret_token responses: '200': description: Payment agreement created successfully. content: application/json: schema: $ref: '#/components/schemas/PayToObject' '400': description: Bad Request '401': description: Unauthorized '404': description: Not Found '422': description: Unprocessable Entity callbacks: PaymentAgreementStatus: '{$request.body#/payment_agreement_notification/endpoint_url}': post: summary: Callback When Payment Agreement Status Changes operationId: PaymentAgreementStatusEvent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PayToObject' responses: '200': description: Callback received successfully. '400': description: Bad request. '401': description: Unauthorized access. method: post type: path path: '{$request.body#/payment_agreement_notification/endpoint_url}' security: - app-id: [] secret-key: [] components: schemas: 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 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 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 - [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) - [Get Payment Agreements](/api/aud-payto/get-payment-agreements.md)