Getting Started with Mandates

This guide walks you through everything you need to set up recurring payments with Banked using PayTo mandates in Australia. PayTo refers to mandates as "PayTo agreements" - these are authorizations that allow you to automatically collect payments from customers' bank accounts. From initial setup to processing your first mandate-based payment, this comprehensive guide covers the complete mandate lifecycle.

Mandate UsageCopy URL

Typical examples of how mandates are used are Account on File and Subscriptions.

Account on FileCopy URL

Used for: eCommerce, recurring purchases, one-click checkout experiences

• Store customer payment credentials for future ad-hoc purchases
• Predefined transaction limits for security
• Perfect for variable-amount, on-demand payments
• Reduces checkout friction for repeat customers

Subscription ServicesCopy URL

Used for: Monthly software subscriptions, streaming services, membership plans

• Automate recurring payments with a scheduler for subscription-based products and services
• Fixed or variable amounts with predictable billing cycles
• Ideal for ongoing service relationships
• Simplified customer retention and billing

Steps to get started:Copy URL

1. Prerequisites and Setup: Get your account ready for PayTo mandates.
2. Create Your First Mandate: Make your first mandate API call.
3. Presenting the mandate checkout to the payer: Display the mandate to the payer so that they can enter their bank account details.
4. Handle Customer Authorization: Guide customers through PayTo authorization.
5. Monitor Mandate Status: Track mandate lifecycle and status changes.
6. Process Payments with Mandates: Execute payments using established mandates.
7. Canceling or Amending Mandates: You may need to cancel or change (amend) the mandates.
8. Go Live: Deploy to production with PayTo compliance.

Step 1: Prerequisites and SetupCopy URL

What You'll NeedCopy URL

Before creating PayTo mandates, ensure you have:

• Banked merchant account with PayTo mandate capabilities enabled - Create account here
• API credentials - Your API key and secret (authentication guide)
• Development environment - Set up for testing (environment guide)

API Request HeadersCopy URL

All mandate API requests require these headers:

{
  "Authorization": "Bearer <OAuth_short_lived_scoped_token>",
  "Content-Type": "application/json",
  "Idempotency-Key": "unique-request-uuid"
}

Base URLCopy URL

The base URL for all API requests in sandbox or production is:

https://api.banked.com

Step 2: Create Your First MandateCopy URL

Follow these steps to create your first PayTo mandate:

curl --location --request POST 'https://api.banked.com/v2/mandates' \
--header 'Authorization: Bearer <OAuth_short_lived_scoped_token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: unique-request-id-123' \
--data-raw '{
    "currency": "AUD",
    "payment_terms": {
        "max_amount": 100000,
        "terms_type": "variable",
        "frequency": "adhoc" 
    },
    "description": "This description is displayed on the PayTo agreement",
    "redirect_url": "https://banked.com",
    "authorisation_timeout": 600
}'

Step 3: Presenting the mandate checkout to the payerCopy URL

The mandate checkout needs to be presented to the payer so that they can enter their bank account details. There are two options to do this, one is to simply redirect to Banked's hosted mandate checkout and the other option is to embed the Banked's checkout inside your website.

Step 4: Payer AuthorizationCopy URL

Once you create a mandate and the payer has entered their bank account details on the mandate checkout then the payer must authorize the mandate in their internet banking before you can create a payment with a mandate.

Step 5: Monitoring the Mandate StatesCopy URL

A mandate must be in a an active state before you can do a payment against it. The mandate will change to an active state once the mandate is successfully authorised. You can monitor a mandates status throughout its lifecycle.

Mandate Lifecycle StatesCopy URL

PayTo mandates progress through several states from creation to termination

Checking Mandate StatesCopy URL

Use the GET /mandates/{mandate_id} endpoint to retrieve current mandate status:

curl -X GET "https://api.banked.com/v2/mandates/{mandate_id}" \
  -H "Authorization: Bearer <OAuth_short_lived_scoped_token>"

Set Up Webhook Notifications (Recommended)Copy URL

To receive real-time updates on mandate status changes, set up webhooks to listen for events like:

Key webhook events:

• mandate_active - Mandate is authorized and ready for payments
• mandate_cancelled - Mandate terminated by customer, bank, or merchant
• mandate_declined - Mandate creation or amendment declined
• mandate_expired - Mandate reached its expiry date
• mandate_failed - Mandate creation was unsuccessful
• mandate_pending - Mandate awaiting authorization or amendment
• mandate_suspended - Mandate temporarily paused

Step 6: Process Payments with MandatesCopy URL

Once a mandate is authorized and in active state, you can process payments using the established mandate. This allows you to charge customers automatically without requiring their interaction for each transaction.

Step 7: Canceling or amending mandatesCopy URL

Mandates can be canceled before or after they are initiated. If the user hasn't proceeded to enter their bank account details then the mandate hasn't been initiated yet. If the mandate is in a pending or active state then it has been initiated.

Canceling Uninitiated MandatesCopy URL

curl --location --request POST 'https://api.banked.com/v2/mandates/{{mandate_id}}/actions' \
--header 'Authorization: Bearer <OAuth_short_lived_scoped_token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: unique-request-id-123' \
--data-raw '{
  "action_type": "cancel_mandate"
}'

Canceling Initiated MandatesCopy URL

curl --location --request POST 'https://api.banked.com/v2/mandates/{{mandate_id}}/actions' \
--header 'Authorization: Bearer <OAuth_short_lived_scoped_token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: unique-request-id-123' \
--data-raw '{
  "action_type": "cancel_current_mandate_attempt"
}'

Step 8: Go Live with PayTo MandatesCopy URL

Follow this checklist to ensure PayTo compliance and successful launch.

Pre-Launch ChecklistCopy URL

Before switching to production, ensure you've completed:

• [ ] All mandate creation, authorization, and payment flows tested
• [ ] Proper handling of failed mandates, declined payments, and API errors
• [ ] Real-time processing of mandate and payment status updates
• [ ] Proper use of unique request keys to prevent duplicate operations
• [ ] Request signing and field-level encryption implemented where required
• [ ] Clear explanation of PayTo mandate terms and conditions

Support and ResourcesCopy URL

Getting HelpCopy URL

• Banked Support - Technical assistance and compliance guidance
• PayTo Guidelines - Official PayTo scheme documentation
• API Status Page - Real-time system status and maintenance updates

Next StepsCopy URL

Now that you have set up your first PayTo mandate, you can explore more advanced features and scenarios:

• Webhooks: Implement real-time notifications for mandate and payment events
• Security Best Practices: Learn about request signing, encryption, and secure API access