Weekly Variable Fee Collection
A lesson costs between A$50 and A$120, depending on the week. With PayTo, the payer can approve one agreement for up to A$150 per payment, once a week. If this week's lessons cost A$95, your business requests A$95. The payer only needs to approve the agreement once for payments within those limits.
Your business schedules each payment. The agreement sets the limits. Each week, your billing system calculates the fee and sends a payment request to ShaBaas Pay. If you skip a week, no payment starts automatically.
1. Set up the agreement
Explain to the payer how you calculate the fee, when you collect it and the most you can charge. In the sandbox, get a bearer token, then create a PayTo agreement using the sample PayID below. Use the payer's authorised PayID in production.
{
"payment_agreement": {
"name": "Example Student",
"type": "email",
"pay_id": "sample@shabaas.com",
"agreement_type": "VARI",
"maximum_amount": "150.00",
"frequency": "WEEK",
"number_of_transactions_permitted": 1
}
}
Here, VARI allows the amount to change, and maximum_amount caps each payment at A$150. Together, WEEK and number_of_transactions_permitted: 1 allow one payment per weekly period. Only set maximum_overall_allowed_amount if you also intend to cap the total collected over the life of the agreement.
Save the returned payment_agreement_id against the payer's billing record. Wait for the payer to approve the agreement in their banking app. Use the payment_agreement webhook and check the agreement status to confirm it is active before collecting.
2. Request this week's fee
When the fee is due, check that the agreement is still active, the fee is within the limit and your records show no request for this payer and billing period. Then request the payment. For a week that costs A$95, send:
{
"payment_initiation": {
"payment_agreement_id": "REPLACE_WITH_ACTIVE_AGREEMENT_ID",
"amount": "95.00",
"merchant_reference": "student-123-week-2026-W47",
"notes": "Weekly lesson fee"
}
}
Save a unique Idempotency-Key and the request body with the weekly charge before you send it. Follow the key format in the payment API reference. If the request times out, check its status. If you resend it, use the same key and identical body so the retry refers to the original charge.
If the agreement becomes inactive, stop scheduling payments for it. If a payment fails, check its status and the weekly limit before following your retry policy. Keep each fee within the agreed limits, including when retrying.
3. Receive updates and match them to your records
Webhooks tell your application when an agreement or payment changes. Prepare HTTPS receivers in both sandbox and production. Register Webhook currently requires URLs for all four events:
| Event | What the URL receives |
|---|---|
payment_agreement | Changes to the agreement, such as approval or cancellation |
payment_initiation | Updates to a payment request |
direct_debit_accepted, direct_debit_rejected | Direct debit notifications. Supply valid URLs even for a PayTo-only integration. |
You can use one URL for several events if your receiver can tell the payloads apart. Check the merchant's existing registrations before updating them.
What to send your ShaBaas Pay integration contact: Send your business name, technical contact name and email, the four callback URLs for each environment, and the date you are ready to test. Label each URL with its event and environment. Confirm your receiver accepts JSON by POST and validates the Authorization header. Share the auth_key separately through an agreed secure channel. Keep secrets, bearer tokens and payer bank details out of email and support tickets.
Validate the header against the shared secret for that environment. Store authenticated events before acknowledging them, and handle repeated or out-of-order notifications. Use agreement IDs, payment IDs and merchant references to match events to your billing records. For missing updates, look up the payment.
An accepted request can still be awaiting settlement. Under Payment Initiation Status Values, ACSC with settled: true means the payer's funds have cleared into the ledger. Payout to the merchant's bank is a separate step.
Before your first live collection
- In the sandbox, approve an agreement and collect different fees across three weekly periods, each within the A$150 cap.
- Test a rejected agreement, a failed payment, a timeout and a repeated webhook. Check that your records show the right outcome and that a retry does not create another charge.
- Confirm the payer understands the pricing and schedule, and record their consent. Use production credentials and real payer details only after merchant onboarding and approval.
For a complete sandbox walkthrough, see Your first sandbox payment. For more detail, see PayTo payment frequency, sandbox payment agreements and webhook notification management.