The PayTo Mandate authorisation service provided by ANZ Fileactive enables businesses to establish and manage payment mandates securely and efficiently. PayTo is a digital payment service designed to streamline the creation, authorisation, and management of payment agreements between customers and businesses, enhancing the overall payment experience by providing greater control and transparency.

Where authorisation fits in the PayTo process flow:

The diagram below illustrates the steps involved in the PayTo process and highlights where auth play a critical role:

PayTo Bilateral End to End Flow

Authentication for ANZ Fileactive APIs

To interact with ANZ Fileactive APIs, authentication is handled using OAuth 2.0 with the Client Credential Grant flow. This ensures secure access to the API resources by obtaining a bearer token, which is then used for authorizing API requests.

Key Points:

  • Flow Type: client_credentials
  • Endpoint: All authentication requests should be sent to the /v1.0/auth endpoint.
  • Token URL: The token URL is https://api.fileactive.anzgcis.com/v1.0/auth.
  • Scopes: Specific scopes define the permissions, such as:
    • AU.INSTO.PAYTO.MANDATE.WRITE - Create & Maintain Mandate.
    • AU.INSTO.PAYTO.MANDATE.READ - Retrieve Mandate Details & Reply to a Query.
    • AU.INSTO.PAYTO.MPIR.WRITE - Create Mandated Payment Initiation Request.
  • Headers: Include an API key in the header using apikey as the parameter name.

Required Fields for Authentication:

  • grant_type: (required, string)
    Specify the type credential requested, for example, client_credentials.

  • client_assertion_type: (required, string)
    Describes the type of client assertion provided in the message request, for example, urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

  • scope: (required, any)
    Define the specific permissions or scope of access, such as:
    • AU.INSTO.PAYTO.MANDATE.WRITE
    • AU.INSTO.PAYTO.MANDATE.READ
    • AU.INSTO.PAYTO.MPIR.WRITE

  • Headers: Include an API key in the header using apikey as the parameter name.

  • client_assertion: (required, object (ClientAssertion))
    The signed JWT assertion.

Example Request:

To request a token, send a POST request with the required parameters in application/x-www-form-urlencoded format. The request must also include your API key in the header for authentication.

POST /v1.0/auth HTTP/1.1
Host: api.fileactive.anzgcis.com
Content-Type: application/x-www-form-urlencoded
x-api-key: <your_api_key_here>  # Include your API key in the header

grant_type=client_credentials&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
scope=AU.INSTO.PAYTO.MANDATE.WRITE&
client_assertion=<your_client_assertion_here>

Example Response:

On success, you’ll receive a bearer token in the response, which is used for authorisation in subsequent API calls.

{
  "expires_in": 3600,
  "token_type": "Bearer",
  "access_token": "eaaa13ee-b596-a8cc-b9d4-f778f8bb9377"
}

Usage Notes:

  • authorisation Header: Include the access_token in the authorisation header as Bearer <access_token>.
  • Token Refresh: Tokens expire according to the expires_in value. Ensure you handle token renewal to maintain API access.

Important Note:

The client_assertion field in your request must be a JWT (JSON Web Token) that is signed with your private key. This ensures the integrity and authenticity of the request. The private key should correspond to the public key that ANZ has on file.

If the client assertion is not properly signed, the authentication request will fail.