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

# Build Recurring Billing with PayTo Agreements

> Set up bank-authorised PayTo mandates and draw recurring payments for subscriptions, instalments, and usage-based billing.

## What you’ll build

PayTo lets you set up a digital, bank-authorised mandate (a “payment agreement”) that your customer approves once from their banking app. After that, Hello Clever collects funds automatically on the schedule you configured (for subscriptions, instalments, mortgages, usage-based billing, and more) without re-prompting the customer each time.

<Card title="Payment agreement" icon="file-signature">
  The standing authority the customer approves. Defines who pays, how (PayID or BSB/account), the per-payment limit, and the frequency pattern that drives collection.
</Card>

<Info>
  This is an **AUD-only (v1)** capability. Endpoints below use the AUD Payment APIs.
</Info>

## Prerequisites

* A merchant account and an `app-id` / `secret-key` (from the Merchant Portal).
* Sandbox endpoint `https://api.cleverhub.co`; production `https://api-merchant.helloclever.co`.
* A webhook endpoint (TLS 1.2, publicly reachable, commercially-issued certificate) to receive status changes.

## Agreement types and frequency

When you create an agreement you set a `payment_agreement_type` (e.g. `MORTGAGE`) and an `agreement_details` block that is one of four shapes:

| Type            | Behaviour                                                                                                                     | Best for                                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| **Variable**    | Recurring pulls where the amount can vary each cycle. Set a `start_date` and a `frequency` (e.g. `ADHOC` or a fixed cadence). | Subscriptions with changing amounts, usage billing |
| **Fixed**       | The same amount every cycle. `limit_amount` must equal the exact amount you intend to charge.                                 | Flat-rate subscriptions                            |
| **Usage-based** | Pulls tied to metered consumption.                                                                                            | Metered / pay-as-you-go services                   |
| **Balloon**     | Instalment-style with a larger final payment.                                                                                 | Financing plans                                    |

<Tip>
  The `limit_amount` caps each individual collection. Pick it to cover your largest expected charge for variable/usage agreements.
</Tip>

## Set up the agreement and start billing

<Steps>
  <Step title="Create the payment agreement">
    Call **create-payment-agreement** with a unique `client_transaction_id`, the `limit_amount`, a `description` (5–140 chars), the `agreement_details`, the `payer_details`, and a `payment_agreement_notification` (your webhook auth header). Payer details carry either `bank_account_details` (BSB + account number) or `pay_id_details` (`pay_id` + `pay_id_type`, e.g. `EMAIL`).

    ```json Create agreement request theme={null}
    {
      "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
      "limit_amount": 1000,
      "description": "Monthly subscription",
      "external_id": "sub_343",
      "payment_agreement_type": "MORTGAGE",
      "agreement_details": {
        "variable_agreement_details_obj": {
          "start_date": "01/01/22",
          "frequency": "MONTHLY"
        }
      },
      "payer_details": {
        "name": "Jane Doe",
        "pay_id_details": { "pay_id": "customer@example.com", "pay_id_type": "EMAIL" }
      },
      "payment_agreement_notification": {
        "endpoint_url": "https://yoursite.com/webhooks/payto",
        "authorization_header": "SECRET"
      }
    }
    ```

    The response returns a Hello Clever `id` and a `payment_agreement_id`, with an initial `status` of `created`.
  </Step>

  <Step title="Wait for the customer to authorise">
    The customer approves the mandate in their banking app. Hello Clever calls your webhook when the agreement status changes. Only charge against an `active` agreement.

    | Status      | Meaning                               |
    | ----------- | ------------------------------------- |
    | `created`   | Creation triggered, awaiting approval |
    | `active`    | Approved and ready to charge          |
    | `suspended` | Temporarily paused                    |
    | `cancelled` | Permanently ended                     |
    | `failed`    | Creation failed                       |
  </Step>

  <Step title="Let the agreement bill on schedule">
    There’s no separate “draw” or “charge” call to make. The `frequency` you set in `agreement_details` (e.g. `MONTHLY`, `WEEKLY`, `FORTNIGHTLY`) drives collection automatically once the agreement reaches `active` status: Hello Clever pulls the payment each cycle, up to `limit_amount`, and notifies your `payment_agreement_notification` webhook as each collection’s status changes.

    For **fixed** agreements, set `limit_amount` to the exact amount you intend to charge every cycle. For **variable** and **usage-based** agreements where the amount changes cycle to cycle, or for one-off/`ADHOC` charges outside a fixed cadence, confirm with your Hello Clever integration contact how the per-cycle amount is submitted; this isn’t yet covered by the published API reference.

    Reconcile collections with **Get payment agreement detail** (`/v1/pay_to/payment_agreement/detail`) or **Get payment agreements** (`/v1/pay_to/payment_agreement/search`) rather than a dedicated payment/initiation record.
  </Step>

  <Step title="Manage the agreement over its life">
    * **Amend** (`amend-payment-agreement`): change the `limit_amount` or `agreement_details` (e.g. frequency) when a plan changes. Requires the Hello Clever `id`, the new `limit_amount`, the full `agreement_details` block, and a `payment_agreement_notification`: all four are required on every call, even if you’re only changing one field.
    * **Change status** (`change-status`): set `status` to `active`, `suspended`, or `cancelled` to pause during a dispute or cancel on churn.
    * **Get detail** / **Get list**: reconcile agreement state, filter by date range with pagination.
  </Step>
</Steps>

## Sandbox test PayIDs

Use these payer PayIDs in sandbox to force a resulting agreement state:

| PayID                           | Resulting status |
| ------------------------------- | ---------------- |
| `no-action@example.com`         | stays `created`  |
| `error@example.com`             | `failed`         |
| `cancel-agreement@example.com`  | `cancelled`      |
| `suspend-agreement@example.com` | `suspended`      |

## Webhook hygiene

<Warning>
  Implement your webhook idempotently: Hello Clever may deliver the same payload more than once and expects a `200 OK` every time. Non-200 responses are retried 3 times at 15-minute intervals. Use a distinct `authorization_header` per agreement to strengthen verification.
</Warning>


## Related topics

- [Hello Clever Developer Documentation](/index.md)
- [PayTo for Recurring Payments](/platform-overview/payment-concepts/payto-recurring.md)
- [Get Started with Hello Clever](/getting-started/overview.md)