The Mandate Creation service in ANZ Fileactive’s PayTo API allows businesses to establish digital mandates for recurring, adhoc or one-time payments. This service streamlines the process of setting up payment agreements between customers and merchants, ensuring that payments are authorised and managed efficiently and securely. This is the necessary first step to begin taking payments through PayTo for a particular customer, regardless of the nature of the transaction. All created mandates are stored in the MMS.

Where create mandate fits in the PayTo process flow:

The diagram below illustrates the steps involved in the PayTo process and highlights where Creat Mandate plays a critical role:

PayTo Bilateral End to End Flow

Capabilities

  • Digital mandate setup: Create digital payment mandates that specify the conditions and frequency of payments from a customer’s account.
  • Flexible mandate options: Supports various mandate types, including fixed, variable, and one-time payments, catering to different business needs.
  • Real-Time customer authorisation: Enables customers to review and authorise mandates instantly through their banking app, ensuring prompt approval and reducing delays.
  • Comprehensive mandate management: Provides full lifecycle management, including creating, viewing, updating, and canceling mandates as needed.

Technical requirements

  • API endpoint: /payto/v1/mandates
  • Authentication: OAuth 2.0 with Client Credential Grant flow is required to securely access the API.
  • Request format: JSON format for mandate details, including customer information, payment terms, and authorisation settings.
  • Security: All mandate creation requests are protected with OAuth 2.0 bearer tokens, and payloads are encrypted to ensure data integrity and confidentiality.

Key features for developers

  • Easy integration: RESTful API design simplifies the integration process into existing systems, allowing quick deployment of mandate creation functionality.
  • Validation and error handling: Robust validation of mandate requests with clear error messages and status codes to help developers troubleshoot and resolve issues effectively.
  • Webhook support: Receive real-time notifications on mandate status changes, such as pending authorisation, active, or canceled, enabling dynamic updates in your application.
  • Scalability: Designed to handle large volumes of mandate requests, making it suitable for both small businesses and large enterprises.

Example workflow

sequenceDiagram participant Client participant ANZ API participant Customer Client->>ANZ API: POST /v1.0/auth (OAuth 2.0 Client Credentials) ANZ API-->>Client: 200 OK (Bearer Token) Client->>ANZ API: POST /v1.0/payto/mandate/create (Create Mandate Request) ANZ API-->>Customer: Notify Customer for authorisation Customer->>ANZ API: Authorise Mandate ANZ API-->>Client: 200 OK (Mandate Created) Note right of ANZ API: Mandate can be
viewed, updated, or canceled Client->>ANZ API: GET /v1.0/payto/mandate/{mandateId} (Check Mandate Status) alt Mandate Active ANZ API-->>Client: 200 OK (Mandate Active) else Mandate Pending ANZ API-->>Client: 202 Accepted (Mandate Pending Authorisation) end Note over ANZ API, Client: Return Webhooks for Mandate Outcome and Notification ANZ API-->>Client: MandateOutcomeWebhook (Mandate Outcome) ANZ API-->>Client: MandateNotificationWebhook (Mandate Notification)

General Rules

  • EstablishmentSchemeRule1: If establishment_scheme is set to 'MGCR', then creditor_information must be present.
  • EstablishmentSchemeRule2: If establishment_scheme is set to 'MGCR', then additional_information must include the BECS User ID of the Initiating Party.
  • EstablishmentSchemeRule3: If establishment_scheme is set to 'MGCR', then resolution_requested_by must not be included.

Validity End Date Rules

  • ValidityEndDateRule1: If validity_end_date is present, then automatic_extension_indicator must be set to false.
  • ValidityEndDateRule2: If validity_end_date is absent, then automatic_extension_indicator must be set to true.

Specific Fields - Business Rules

resolution_requested_by

  • ATTENDED Request:
    • resolution_requested_by should be within 5 minutes.
    • ANZ will default to 5 minutes where not provided or override to 5 minutes where the value exceeds 5 minutes.
  • UNATTENDED Request:
    • resolution_requested_by should be within 5 calendar days.
    • ANZ will default to 5 calendar days where not provided or override to 5 calendar days where the value exceeds 5 calendar days.

debtor_information

  • AccountIdentificationRule1:
    • If account_identification_type_code is equal to 'ALIA', then both account_alias_type_code and account_alias_identification must be present, and account_identification must be absent.
  • AccountIdentificationRule2:
    • If account_identification_type_code is equal to 'BBAN', then account_identification must be present and start with BSB (Bank-State-Branch).
    • In this case, account_alias_type_code and account_alias_identification must be absent.
  • AccountIdentificationRule3:
    • If establishment_scheme is equal to 'MGCR', then account_identification_type_code must be equal to 'BBAN'.

creditor_information

  • CreditorPartyTypeRule1:
    • If establishment_scheme is equal to 'MGCR', then party_type must be present.

payment_information

  • PaymentAmountTypeRule1:
    • If payment_amount_type is equal to 'FIXE', then amount must be present.
  • PaymentAmountTypeRule2:
    • If payment_amount_type is equal to 'BALN', then amount must be present AND either first_payment_amount or last_payment_amount must also be present.
  • PaymentAmountTypeRule3:
    • If payment_amount_type is equal to 'USGB', then maximum_amount must be present.
  • PaymentAmountTypeRule4:
    • If payment_amount_type is equal to 'VARI', then maximum_amount must be present.
  • FirstPaymentDateRule1:
    • first_payment_date cannot be before validity_start_date.
  • FirstPaymentDateRule2:
    • first_payment_date cannot be after validity_end_date.
  • FirstPaymentDateRule3:
    • If establishment_scheme is equal to 'MGCR', then first_payment_date must not be present.
  • LastPaymentDateRule1:
    • last_payment_date cannot be before validity_start_date.
  • LastPaymentDateRule2:
    • last_payment_date cannot be after validity_end_date.
  • FrequencyInTermsRule1:
    • Both count_per_period and point_in_time cannot be present at the same time.
  • PaymentAmountRule1:
    • amount cannot exceed maximum_amount.
  • PaymentAmountRule2:
    • first_payment_amount cannot exceed maximum_amount.
  • PaymentAmountRule3:
    • last_payment_amount cannot exceed maximum_amount.
  • PaymentAmountRule4:
    • If establishment_scheme is equal to 'MGCR', then first_payment_amount must not be present.