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.

Payment agreement

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.

This is an AUD-only (v1) capability. Endpoints below use the AUD Payment APIs.

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

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

Set up the agreement and start billing

1. 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).

   Create agreement request

   {
     "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": "[e-mail]", "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.

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

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

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

Sandbox test PayIDs

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

PayID	Resulting status
[e-mail]	stays created
[e-mail]	failed
[e-mail]	cancelled
[e-mail]	suspended

Webhook hygiene

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.