---
layout: detail
title: Australia payments
menu_key: auPayments
group: fileactive
hero_key: payments
---

---

Access the Fileactive API for fast, secure, and real-time payments within Australia. The API supports both the New Payments Platform (NPP) for instant domestic settlements and Cross Border Funds Transfer (CBFT) for international transactions. This enables businesses to efficiently manage both domestic and cross-border payment workflows with robust security measures, including OAuth 2.0 and JWT encryption.

---
[Key features](#keyfeatures) 

<h4 name="keyfeatures" id="keyfeatures"></h4>

#### Key features:

- **NPP:** Instant, real-time domestic payment processing within Australia.

- **CBFT:** Secure cross-border funds transfers, supporting international payment needs.

- **Secure authentication:** Leverage OAuth 2.0 and JWT for strong security in all payment transactions.

- **Status tracking:** Easily track payment statuses with dedicated API endpoints.

---

[Rate limits and throttling](#ratelimits) 

<h4 name="ratelimits" id="ratelimits"></h4>

#### Rate limits and throttling:

By default the following rate limits are applied.

<table style="border-collapse: collapse; width: 100%;">
  <thead>
    <tr style="background-color: #f2f2f2; border: 1px solid #ddd;">
      <th style="border: 1px solid #ddd; padding: 8px;">Type</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPH (Transactions Per Hour)</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPM (Transactions Per Minute)</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPS (Transactions Per Second)</th>
    </tr>
  </thead>
  <tbody>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Authorisation</td>
      <td style="border: 1px solid #ddd; padding: 8px;">10</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">NPP Single Payment</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">30</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
     <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Payment</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">30</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
     <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Payment Enquiry</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">90</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
  </tbody>
</table>

---

[Rate limiting algorithms](#ratelimitalgorithm) 

<h4 name="ratelimitalgorithm" id="ratelimitalgorithm"></h4>

#### Rate limiting algorithms:

For most use cases one of two algorithms is implemented for rate limiting.

**Fixed Window**
The system uses a window size of `n` seconds (typically using human-friendly values, such as 60 or 3600 seconds) to track the fixed window algorithm rate. Each incoming request increments the counter for the window. It discards the request if the counter exceeds a threshold. The current timestamp floor typically defines the windows, so 12:00:03, with a 60-second window length, would be in the 12:00:00 window.

**Sliding Window**
Sliding Window is a hybrid approach. Like the fixed window algorithm, we track a counter for each fixed window. Next, we account for a weighted value of the previous window’s request rate based on the current timestamp to smooth out bursts of traffic.

[Sliding window example](#slidingexample) 

<h4 name="slidingexample" id="slidingexample"></h4>

#### Sliding window example:

**Given a limit of 100 transactions per hour.**

- **Window 1 (13:00 - 14:00)**  
  Between 13:00 - 14:00, 80 requests are received. This is within the 100 tph limit, so all are allowed.

- **Window 2 (14:00 - 15:00)**  
  By 14:15, 20 requests are received. This is 25% (15 minutes) into window 2, so the weighted average would include 75% from the previous window.

  **Request rate**: 20 (all requests within window 2) + 60 (75% of requests from window 1) = 80 requests.  
  The request rate is still within the 100 tph maximum.

  By 14:30, 75 requests have been received. This is 50% (30 minutes) into window 2, so the weighted average would include 50% from the previous window.

  **Request rate**: 75 (all requests within window 2) + 40 (50% weighted average from previous window) = 115 requests.  
  This exceeds the 100 tph limit, so further requests would return an HTTP 429 (Too Many Requests) status code until the weighted request rate is below the agreed limit.

  By 14:45, no further requests have been made. This is 75% (45 minutes) through window 2.

  **Request rate**: 75 (current window) + 20 (25% weighted average from previous window) = 95 requests.  
  As this is below the 100 tph limit, further requests will be accepted.

openapi: 3.0.1
info:
    title: Fileactive Authentication API
    version: 2.1.0
servers:
  - url: https://api.fileactive.uat.anzgcis.com
    description: UAT Test environment
  - url: https://api.fileactive.anzgcis.com
    description: Production Environment
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /v1.0/auth:
    post:
      security:
        - apiKeyAuth: []
          oAuth2: []
      summary: Auth Token Request
      description: >
        ANZ uses OAuth 2.0 to authenticate inbound token requests, a bearer token
        is returned as a response which is then used to authorise against ANZ
        resources.
      operationId: auth
      requestBody:
        description: 'Information and examples of Auth request body '
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/authTokenRequest'
      responses:
        '200':
          $ref: '#/components/responses/200OKAuth'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorised'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalError'
        '502':
          $ref: '#/components/responses/502BadGateway'
        '503':
          $ref: '#/components/responses/503Unavailable'
        '504':
          $ref: '#/components/responses/504Timeout'
        default:
          $ref: '#/components/responses/default'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: uuid
      description: Bearer token obtained during token exchange
    apiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: API key to authorise requests.
    oAuth2:
      type: oauth2
      description: OAuth2 flows for both Production and UAT environments
      flows:
        clientCredentials:
          tokenUrl: https://api.fileactive.anzgcis.com/v1.0/auth
          scopes:
            AU.INSTO.PAYMENT.NPP.CREATE: Create Australia NPP Payment Resource   
            AU.INSTO.PAYMENT.NPP.READ: Retrieve information for specific payment resource   
            AU.INSTO.PAYMENT.CBFT.CREATE: Create Australia CBFT Payment Resource   
            AU.INSTO.PAYMENT.READ: Retrieve information for specific payment resource (except AU NPP)
    apiKey:
          type: apiKey
          in: header
          name: apikey
          description: API key to authorise requests.
  responses:
    200OKAuth:
      description: Bearer token (Opaque Token) returned after a token request
      headers:
        x-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/authTokenResponse'
    400BadRequest:
      description: Bad Request, message format does not match expected schema
      content: {}
    401Unauthorised:
      description: Application is not unauthorised to perform a specific action
      content: {}
    403Forbidden:
      description: Action is not authorised using current authentication credentils
      content: {}
    404NotFound:
      description: No record found
      content: {}
    429TooManyRequests:
      description: Action exceeds allocated limits
      content: {}
    500InternalError:
      description: Internal Server Error, contact support
      content: {}
    502BadGateway:
      description: Bad Gateway, contact support
      content: {}
    503Unavailable:
      description: Service Unavailable or down for maintainance
      content: {}
    504Timeout:
      description: Gateway Timeout, retry or contact support
      content: {}
    default:
      description: Unexpected error
      content: {}
  schemas:
    authTokenRequest:
      required:
        - grant_type
        - client_assertion_type
        - scope
        - client_assertion
      type: object
      properties:
        grant_type:
          description: Specify the type credential requested
          type: string
          example: client_credentials
        client_assertion_type:
          description: >-
            Describes the type of client assertion provided in the message
            request
          type: string
          example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
        scope:
          $ref: '#/components/securitySchemes/oAuth2/flows/clientCredentials/scopes'
        client_assertion:
          $ref: '#/components/schemas/ClientAssertion'
    authTokenResponse:
      type: object
      description: Response to report the status of a customer credit transfer.
      additionalProperties: false
      properties:
        expires_in:
          description: Indication on how long a token is valid for
          type: integer
        token_type:
          description: Type of token returned
          type: string
        access_token:
          description: >-
            Opaque token returned as part of request, Fileactive does not provide the
            full access token
          type: string
      example:
        expires_in: 3600
        token_type: Bearer
        access_token: eaaa13ee-b596-a8cc-b9d4-f778f8bb9377
    ClientAssertion:
      required:
        - sub
        - exp
        - aud
      type: object
      properties:
        sub:
          type: string
          description: Customer Code as provided by ANZ onboarding
          example: CUSTOMERA
        exp:
          type: integer
          description: EPOCH date and time
          example: '1619658591'
          maxLength: 10
          minLength: 10
        aud:
          type: string
          description: Specify the intended audience of the token request
          example: https://api.fileactive.anzgcis.com/auth
    UUID:
      type: string
      example: 71d6fb19-7515-40dc-b045-e17550b67600
      pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
  parameters:
    requestKey:
      name: X-REQUESTKEY
      in: header
      description: Internal End to End key used for support and reporting purposes
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275

spec.yaml

---
layout: code
title: Authentication
menu_key: auth
group: fileactive
hero_key: fileactive
payload_spec: "/gcis/api-portal/fileactive/api/payments/au/data/auth-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
---

---
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](#access) 

<h4 name="access" id="access"></h4>

#### Key points:

- **Endpoint:** All authentication requests should be sent to the `/v1.0/auth` endpoint.
- **Grant Type:** Use `client_credentials` as the grant type for obtaining tokens.
- **Token URL:** The token URL is `https://api.fileactive.anzgcis.com/v1.0/auth`.
- **Scopes:** Specific scopes define the permissions, such as:
  - `AU.INSTO.PAYMENT.NPP.CREATE` - For creating NPP Payment resources.
  - `AU.INSTO.PAYMENT.NPP.READ` - For retrieving NPP Payment resources.
  - `AU.INSTO.PAYMENT.CBFT.CREATE` - For creating CBFT Payment resources.
  - `AU.INSTO.PAYMENT.READ` - For retrieving payment resources (except AU NPP).
- **Headers:** Include an API key in the header using `apikey` as the parameter name.

---

[Example request](#send) 

<h4 name="send" id="send"></h4>

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

```http
curl --request POST \
--url "https://api.fileactive.uat.anzgcis.com/auth" \
--header "Content-Type: application/x-www-form-urlencoded" \
--header "apikey: 111abc23233223" \
--data "grant_type=client_credentials&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&scope=AU.INSTO.PAYMENT.NPP.CREATE&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJHUkFQRSIsImV4cCI6IjE3Mjg3NzQ5NzMiLCJhdWQiOiJodHRwczovL2FwaS5maWxlYWN0aXZlLnVhdC5hbnpnY2lzLmNvbS9hdXRoIn0.bKkKtGbdbJTKhi6ViSqfXJXqZf_NISgNGc0rSs32YK-FJF6ZeOy63BUoZXcsdaPKA0K3CE5Smi-jmHf7tW109lsDaoYO8hU3pDqNjyx8oZO157nLUBt68OMzbZOKDGBg6T9p8qLPllfGvVX3m5XqkGN5I2kaLPnofWONYRiR6Y_qWHB6IbzXSLhpxvWcRJ0Fb5HoEJi3xAO7eG78xnevVSEv5aIe57q2ba6btyciaU-dnfceMJOzsjjAyr4k10B-S3M9ckhYfeIRqwR4ZzHukiwVH9s5sl9MC3kKBGzjtIvTTw3HZH0MT5wS1fFwb4UAbpppphDMQzWJ-7fww3A5Iw"
```

---

[Example response](#receive) 

<h4 name="receive" id="receive"></h4>

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

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

---

[Usage notes](#expire) 

<h4 name="expire" id="expire"></h4>

#### 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](#field) 

<h4 name="field" id="field"></h4>

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

API Level Documentation

Authentication

NPP-OSKO

---
layout: code
title: CBFT
menu_key: auPayments
group: fileactive
hero_key: payments
payload_spec: "/gcis/api-portal/fileactive/api/payments/au/data/cbft-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
---

---
Cross-Border Funds Transfer (CBFT) APIs enable seamless international payments, allowing businesses to transfer funds across borders efficiently and securely. CBFT supports multiple currencies and adheres to international standards, making it an essential service for companies involved in global trade.

---

[Capabilities](#capable) 

<h4 name="capable" id="capable"></h4>

#### Capabilities
- **Multi-Currency support:** Handle payments in a wide range of currencies, supporting global business operations.
- **Compliance and standards:** Adheres to international payment standards, including SWIFT messaging, to ensure compliance with global financial regulations.
- **End-to-End tracking:** Monitor the status of your international transfers with tracking capabilities that provide transparency throughout the transaction lifecycle.
- **Cost efficiency:** Optimise transfer costs with competitive foreign exchange rates and lower processing fees compared to traditional bank transfers.

---
[Technical requirements](#require) 

<h4 name="require" id="require"></h4>

#### Technical requirements
- **Authentication:** Utilize OAuth 2.0 with the Client Credential Grant to obtain a bearer token, which is required for API access.
- **Endpoints:** Access CBFT APIs through the `/payment/au/v1.0/cbft` endpoint for initiating cross-border payments.
- **Security:** All transactions are secured with HTTPS and OAuth 2.0, ensuring the protection of sensitive financial data during transfer.
- **Data format:** JSON is used for request and response payloads, facilitating easy integration with web applications and services.

---
[Key features for developers](#develop) 

<h4 name="develop" id="develop"></h4>

#### Key features for developers
- **Asynchronous payment processing:** Submit cross-border payment requests and handle responses asynchronously, allowing your application to operate without waiting for immediate confirmation.
- **Detailed error messages:** Comprehensive error handling with detailed messages to assist in troubleshooting and resolving issues swiftly.
- **Testing environment:** A dedicated UAT environment is available for testing and validating integrations before moving to the production environment.
- **Extensive documentation:** Access to thorough API documentation, including example code, request structures, and common use cases to support developers during integration.

---
[Example workflow](#flow) 

<h4 name="flow" id="flow"></h4>

#### Example workflow

<div class="mermaid">
sequenceDiagram
    participant Developer
    participant CBFT API

    Developer->>CBFT API: POST /v1.0/auth (Client Credentials)
    CBFT API-->>Developer: 200 OK (Bearer Token)

    Developer->>CBFT API: POST /payment/au/v1.0/cbft (CBFT Payment Request)
    CBFT API-->>Developer: 202 Accepted (Payment Processing)

    Developer->>CBFT API: GET /payment/au/v1.0/cbft/status/{requestId}
    alt Payment Successful
        CBFT API-->>Developer: 200 OK (Payment Details)
    else Payment Pending
        CBFT API-->>Developer: 204 No Content (Payment Pending)
    else Payment Failed
        CBFT API-->>Developer: 400 Bad Request (Error Details)
    end
</div>

CBFT

---
layout: detail
title: Hong Kong payments
menu_key: hkPayments
group: fileactive
hero_key: payments
---

---
Access the Fileactive API for efficient and secure payment processing in Hong Kong. The API supports various payment types, including ACH for automated clearing, FPS for faster payments, RTGS for real-time gross settlements, and CBFT for cross-border transactions. These capabilities allow businesses to handle both domestic and international payments with robust security measures, including OAuth 2.0 and JWT encryption.

---
[Key features](#test) 

<h4 name="test" id="test"></h4>

#### Key features:
- **ACH:** Automate clearing house payments for streamlined domestic transactions.

- **FPS:** Fast and efficient payment processing for real-time settlements in Hong Kong.

- **RTGS:** Real-time gross settlement for high-value transactions with immediate finality.

- **CBFT:** Secure cross-border funds transfers to support international payment needs.

- **Secure authentication:** Utilize OAuth 2.0 and JWT for secure access to all payment services.

- **Status tracking:** Monitor payment statuses with dedicated endpoints for each payment type.

---
[Rate limits and throttling:](#limits) 

<h4 name="limits" id="limits"></h4>

#### Rate limits and throttling:

By default the following rate limits are applied.

<table style="border-collapse: collapse; width: 100%;">
  <thead>
    <tr style="background-color: #f2f2f2; border: 1px solid #ddd;">
      <th style="border: 1px solid #ddd; padding: 8px;">Type</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPH (Transactions Per Hour)</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPM (Transactions Per Minute)</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPS (Transactions Per Second)</th>
    </tr>
  </thead>
  <tbody>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Authorisation</td>
      <td style="border: 1px solid #ddd; padding: 8px;">10</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Payments</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">30</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
     <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Payment Enquiry</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">90</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
  </tbody>
</table>

---
[Rate limiting algorithms](#algor) 

<h4 name="algor" id="algor"></h4>

#### Rate limiting algorithms:

For most use cases one of two algorithms is implemented for rate limiting.

**Fixed Window**
The system uses a window size of `n` seconds (typically using human-friendly values, such as 60 or 3600 seconds) to track the fixed window algorithm rate. Each incoming request increments the counter for the window. It discards the request if the counter exceeds a threshold. The current timestamp floor typically defines the windows, so 12:00:03, with a 60-second window length, would be in the 12:00:00 window.

**Sliding Window**
Sliding Window is a hybrid approach. Like the fixed window algorithm, we track a counter for each fixed window. Next, we account for a weighted value of the previous window’s request rate based on the current timestamp to smooth out bursts of traffic.

[Sliding window example](#example) 

<h4 name="example" id="example"></h4>

#### Sliding window example:

**Given a limit of 100 transactions per hour.**

- **Window 1 (13:00 - 14:00)**  
  Between 13:00 - 14:00, 80 requests are received. This is within the 100 tph limit, so all are allowed.

- **Window 2 (14:00 - 15:00)**  
  By 14:15, 20 requests are received. This is 25% (15 minutes) into window 2, so the weighted average would include 75% from the previous window.

  **Request rate**: 20 (all requests within window 2) + 60 (75% of requests from window 1) = 80 requests.  
  The request rate is still within the 100 tph maximum.

  By 14:30, 75 requests have been received. This is 50% (30 minutes) into window 2, so the weighted average would include 50% from the previous window.

  **Request rate**: 75 (all requests within window 2) + 40 (50% weighted average from previous window) = 115 requests.  
  This exceeds the 100 tph limit, so further requests would return an HTTP 429 (Too Many Requests) status code until the weighted request rate is below the agreed limit.

  By 14:45, no further requests have been made. This is 75% (45 minutes) through window 2.

  **Request rate**: 75 (current window) + 20 (25% weighted average from previous window) = 95 requests.  
  As this is below the 100 tph limit, further requests will be accepted.

openapi: 3.0.1
info:
    title: Fileactive Authentication API
    version: 2.1.0
servers:
  - url: https://api.fileactive.uat.anzgcis.com
    description: UAT Test environment
  - url: https://api.fileactive.anzgcis.com
    description: Production Environment
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /v1.0/auth:
    post:
      security:
        - apiKeyAuth: []
          oAuth2: []
      summary: Auth Token Request
      description: >
        ANZ uses OAuth 2.0 to authenticate inbound token requests, a bearer token
        is returned as a response which is then used to authorise against ANZ
        resources.
      operationId: auth
      requestBody:
        description: 'Information and examples of Auth request body '
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/authTokenRequest'
      responses:
        '200':
          $ref: '#/components/responses/200OKAuth'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorised'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalError'
        '502':
          $ref: '#/components/responses/502BadGateway'
        '503':
          $ref: '#/components/responses/503Unavailable'
        '504':
          $ref: '#/components/responses/504Timeout'
        default:
          $ref: '#/components/responses/default'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: uuid
      description: Bearer token obtained during token exchange
    apiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: API key to authorise requests.
    oAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.fileactive.anzgcis.com/v1.0/auth
          scopes:
            HK.INSTO.PAYMENT.ACH.CREATE: Create Hong Kong ACH Payment Resource   
            HK.INSTO.PAYMENT.FAST.CREATE: Create Hong Kong FPS Payment Resource   
            HK.INSTO.PAYMENT.RTGS.CREATE: Create Hong Kong RTGS Payment Resource
            HK.INSTO.PAYMENT.CBFT.CREATE: Create Hong Kong CBFT Payment Resource  
            HK.INSTO.PAYMENT.READ: Retrieve information for specific payment resource   
    apiKey:
      type: apiKey
      in: header
      name: apikey
      description: API key to authorise requests.
  responses:
    200OKAuth:
      description: Bearer token (Opaque Token) returned after a token request
      headers:
        x-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/authTokenResponse'
    400BadRequest:
      description: Bad Request, message format does not match expected schema
      content: {}
    401Unauthorised:
      description: Application is not unauthorised to perform a specific action
      content: {}
    403Forbidden:
      description: Action is not authorised using current authentication credentils
      content: {}
    404NotFound:
      description: No record found
      content: {}
    429TooManyRequests:
      description: Action exceeds allocated limits
      content: {}
    500InternalError:
      description: Internal Server Error, contact support
      content: {}
    502BadGateway:
      description: Bad Gateway, contact support
      content: {}
    503Unavailable:
      description: Service Unavailable or down for maintainance
      content: {}
    504Timeout:
      description: Gateway Timeout, retry or contact support
      content: {}
    default:
      description: Unexpected error
      content: {}
  schemas:
    authTokenRequest:
      required:
        - grant_type
        - client_assertion_type
        - scope
        - client_assertion
      type: object
      properties:
        grant_type:
          description: Specify the type credential requested
          type: string
          example: client_credentials
        client_assertion_type:
          description: >-
            Describes the type of client assertion provided in the message
            request
          type: string
          example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
        scope:
          $ref: '#/components/securitySchemes/oAuth2/flows/clientCredentials/scopes'
        client_assertion:
          $ref: '#/components/schemas/ClientAssertion'
    authTokenResponse:
      type: object
      description: Response to report the status of a customer credit transfer.
      additionalProperties: false
      properties:
        expires_in:
          description: Indication on how long a token is valid for
          type: integer
        token_type:
          description: Type of token returned
          type: string
        access_token:
          description: >-
            Opaque token returned as part of request, Fileactive does not provide the
            full access token
          type: string
      example:
        expires_in: 3600
        token_type: Bearer
        access_token: eaaa13ee-b596-a8cc-b9d4-f778f8bb9377
    ClientAssertion:
      required:
        - sub
        - exp
        - aud
      type: object
      properties:
        sub:
          type: string
          description: Customer Code as provided by ANZ onboarding
          example: CUSTOMERA
        exp:
          type: integer
          description: EPOCH date and time
          example: '1619658591'
          maxLength: 10
          minLength: 10
        aud:
          type: string
          description: Specify the intended audience of the token request
          example: https://api.fileactive.anzgcis.com/auth
    UUID:
      type: string
      example: 71d6fb19-7515-40dc-b045-e17550b67600
      pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
  parameters:
    requestKey:
      name: X-REQUESTKEY
      in: header
      description: Internal End to End key used for support and reporting purposes
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275

---
layout: code
title: Authentication
menu_key: auth
group: fileactive
hero_key: fileactive
payload_spec: "/gcis/api-portal/fileactive/api/payments/hk/data/auth-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
---

---

To interact with ANZ Fileactive APIs for Hong Kong, 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](#capable) 

<h4 name="capable" id="capable"></h4>

#### Key points:

- **Endpoint:** All authentication requests should be sent to the `/v1.0/auth` endpoint.
- **Grant Type:** Use `client_credentials` as the grant type for obtaining tokens.
- **Token URL:** The token URL is `https://api.fileactive.anzgcis.com/v1.0/auth`.
- **Scopes:** Specific scopes define the permissions, such as:
  - `HK.INSTO.PAYMENT.ACH.CREATE` - For creating ACH Payment resources in Hong Kong.
  - `HK.INSTO.PAYMENT.ACH.READ` - For retrieving ACH Payment resources in Hong Kong.
  - `HK.INSTO.PAYMENT.FAST.CREATE` - For creating FAST Payment resources in Hong Kong.
  - `HK.INSTO.PAYMENT.FAST.READ` - For retrieving FAST Payment resources in Hong Kong.
  - `HK.INSTO.PAYMENT.RTGS.CREATE` - For creating RTGS Payment resources in Hong Kong.
  - `HK.INSTO.PAYMENT.RTGS.READ` - For retrieving RTGS Payment resources in Hong Kong.
  - `HK.INSTO.PAYMENT.CBFT.CREATE` - For creating CBFT Payment resources in Hong Kong.
  - `HK.INSTO.PAYMENT.CBFT.READ` - For retrieving CBFT Payment resources in Hong Kong.
- **Headers:** Include an API key in the header using `apikey` as the parameter name.

---
[Example request](#send) 

<h4 name="send" id="send"></h4>

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

```http
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=HK.INSTO.PAYMENT.ACH.CREATE&
client_assertion=<your_client_assertion_here>
```
 ---
[Example response](#receive) 

<h4 name="receive" id="receive"></h4>

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

```json
{
  "expires_in": 3600,
  "token_type": "Bearer",
  "access_token": "eaaa13ee-b596-a8cc-b9d4-f778f8bb9377"
}
```
---
[Usage notes](#usage) 

<h4 name="usage" id="usage"></h4>

#### 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](#note) 

<h4 name="note" id="note"></h4>

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

---
layout: code
title: Hong Kong ACH
menu_key: hkPayments
group: fileactive
hero_key: payments
payload_spec: "/fileactive/api/payments/hk/data/ach-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
---

The Hong Kong ACH (Automated Clearing House) Payments API provides a streamlined and secure way for businesses to initiate and manage domestic low-value payments in Hong Kong. This API is designed to facilitate automated, efficient, and scalable payment processing, making it an ideal solution for recurring payments, payroll, and bulk transactions.

---
[Capabilities](#capable) 

<h4 name="capable" id="capable"></h4>

#### Capabilities

- **Payment initiation:** Submit ACH payment requests to transfer funds between accounts within Hong Kong.
- **Batch processing:** Support for bulk payment processing, allowing multiple transactions in a single request.
- **Payment tracking:** Monitor the status of payments in real-time to ensure transparency and accountability.
- **Secure transactions:** All transactions are encrypted and securely transmitted, meeting regulatory and compliance standards.

---
[Technical requirements](#require) 

<h4 name="require" id="require"></h4>

#### Technical requirements

- **Authentication:** OAuth 2.0 with the Client Credential Grant flow is used for secure access. Obtain a bearer token from the `/v1.0/auth` endpoint and include it in the authorisation header as `Bearer <access_token>`.
- **API Endpoint:** All ACH payment requests should be sent to the `/payment/hk/v1.0/ach` endpoint.
- **Headers:** Include the required headers such as `Content-Type: application/json` and `authorisation: Bearer <access_token>`.
- **Payload Format:** Payment requests should be formatted in JSON, adhering to the defined schema for ACH payments.

---
[Key features for developers](#develop) 

<h4 name="develop" id="develop"></h4>

#### Key features for developers

- **Automated payments:** Simplifies the process of making regular payments, such as payroll or vendor payments, through automation.
- **Batch support:** Efficiently handle large volumes of transactions with batch processing capabilities, reducing the need for individual requests.
- **Real-TimesStatus updates:** Access up-to-date information on payment statuses, helping to manage and reconcile transactions effectively.
- **Error handling:** Detailed error codes and messages assist in troubleshooting and ensuring smooth integration with your systems.

---
[Example workflow](#flow) 

<h4 name="flow" id="flow"></h4>

#### Example workflow

<div class="mermaid">
sequenceDiagram
    participant Client
    participant Fileactive

    Client->>Fileactive: POST /v1.0/auth (Obtain Bearer Token)
    Fileactive-->>Client: 200 OK (Bearer Token)

    Client->>Fileactive: POST /payment/hk/v1.0/ach (Submit ACH Payment)
    Fileactive-->>Client: 202 Accepted (Payment Processing)

    Client->>Fileactive: GET /payment/hk/v1.0/ach/{paymentId} (Check Payment Status)
    alt Payment Completed
        Fileactive-->>Client: 200 OK (Payment Success)
    else Payment Pending
        Fileactive-->>Client: 202 Accepted (Payment Pending)
    else Payment Failed
        Fileactive-->>Client: 400 Bad Request (Payment Failed)
    end
</div>

ACH Payment

---
layout: code
title: Hong Kong FPS
menu_key: hkPayments
group: fileactive
hero_key: payments
payload_spec: "/gcis/api-portal/fileactive/api/payments/hk/data/fps-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
---

---
The Hong Kong FPS (Faster Payment System) Payments API enables real-time, instant payments and transfers within Hong Kong. Designed to streamline financial transactions, the FPS API allows businesses to conduct payments between banks and stored value facility (SVF) operators quickly and securely.

---
[Capabilities](#capable) 

<h4 name="capable" id="capable"></h4>

#### Capabilities

- **Instant payments:** Facilitate real-time payments between different banks and SVFs, ensuring funds are transferred within seconds.
- **P2P and B2B transactions:** Supports both peer-to-peer (P2P) and business-to-business (B2B) payments, catering to a wide range of financial operations.
- **24/7 Availability:** FPS operates around the clock, allowing transactions to be initiated and processed anytime, enhancing operational efficiency.
- **Support for multiple identifiers:** Payments can be made using various identifiers, such as mobile numbers, email addresses, FPS IDs, and bank account numbers.

---
[Technical requirements](#require) 

<h4 name="require" id="require"></h4>

#### Technical requirements

- **Authentication:** Use OAuth 2.0 with the Client Credential Grant flow for secure access. Obtain a bearer token from the `/v1.0/auth` endpoint and include it in the authorisation header as `Bearer <access_token>`.
- **API Endpoint:** FPS payment requests are submitted to the `/payment/hk/v1.0/fast` endpoint.
- **Headers:** Include essential headers like `Content-Type: application/json` and `authorisation: Bearer <access_token>` in all API requests.
- **Payload Format:** Payments should be submitted in JSON format, adhering to the FPS payment schema outlined in the API documentation.

---
[Key features for developers](#develop) 

<h4 name="develop" id="develop"></h4>

#### Key features for developers

- **Real-Time processing:** Ensure instantaneous transaction processing, significantly reducing payment settlement times and improving cash flow.
- **Flexible payment initiation:** Utilize various identifiers (e.g., mobile number, email) to initiate payments, offering flexibility in how payments are processed and received.
- **Detailed status tracking:** Access comprehensive status updates for each payment, providing visibility and control over transaction outcomes.
- **Enhanced security:** Leverages strong encryption and secure communication protocols, aligning with Hong Kong’s regulatory standards for payment processing.

---
[Example workflow](#flow) 

<h4 name="flow" id="flow"></h4>

#### Example workflow

<div class="mermaid">
sequenceDiagram
    participant Client
    participant Fileactive

    Client->>Fileactive: POST /v1.0/auth (Obtain Bearer Token)
    Fileactive-->>Client: 200 OK (Bearer Token)

    Client->>Fileactive: POST /payment/hk/v1.0/fast (Submit FPS Payment)
    Fileactive-->>Client: 202 Accepted (Payment Processing)

    Client->>Fileactive: GET /payment/hk/v1.0/fast/{paymentId} (Check Payment Status)
    alt Payment Completed
        Fileactive-->>Client: 200 OK (Payment Success)
    else Payment Pending
        Fileactive-->>Client: 202 Accepted (Payment Pending)
    else Payment Failed
        Fileactive-->>Client: 400 Bad Request (Payment Failed)
    end
</div>

FPS Payment

---
layout: code
title: Hong Kong RTGS
menu_key: hkPayments
group: fileactive
hero_key: payments
payload_spec: "/gcis/api-portal/fileactive/api/payments/hk/data/rtgs-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
---

---
The Hong Kong RTGS (Real-Time Gross Settlement) Payments API provides a secure and efficient method for processing high-value and time-critical transactions in real-time. Designed for interbank transfers, the RTGS system ensures that payments are settled instantly and irrevocably on a transaction-by-transaction basis.

---
[Capabilities](#capable) 

<h4 name="capable" id="capable"></h4>

#### Capabilities

- **High-Value transactions:** Supports large-scale, high-value payments, making it ideal for business-to-business transactions, treasury operations, and financial market settlements.
- **Immediate settlement:** Transactions are settled in real-time, ensuring immediate transfer of funds between participating banks, reducing settlement risk.
- **Final and irrevocable payments:** Once processed, payments are final and cannot be reversed, providing certainty and security in financial transactions.
- **24/7 Operations:** The RTGS system operates continuously, allowing transactions to be processed at any time, supporting global financial operations across different time zones.

---
[Technical requirements](#require) 

<h4 name="require" id="require"></h4>

#### Technical requirements

- **Authentication:** Use OAuth 2.0 with the Client Credential Grant flow for secure access. Obtain a bearer token from the `/v1.0/auth` endpoint and include it in the authorisation header as `Bearer <access_token>`.
- **API Endpoint:** RTGS payment requests should be submitted to the `/payment/hk/v1.0/rtgs` endpoint.
- **Headers:** Ensure all API requests include headers such as `Content-Type: application/json` and `authorisation: Bearer <access_token>`.
- **Payload format:** Submit payment details in JSON format, following the schema specified in the API documentation for RTGS payments.

---
[Key features for developers](#develop) 

<h4 name="develop" id="develop"></h4>

#### Key features for developers

- **Secure High-Value transfers:** Leverage RTGS for secure, real-time processing of large financial transactions, reducing the exposure to settlement risk.
- **Real-Time transaction monitoring:** Track payment status and confirmations in real-time, allowing for immediate visibility and control over financial flows.
- **Guaranteed settlement:** All transactions processed via RTGS are final and irrevocable, ensuring confidence and reliability in payment processing.
- **Scalability for business needs:** Capable of handling high volumes of transactions, supporting both routine and peak business activities without performance degradation.

---
[Example workflow](#flow) 

<h4 name="flow" id="flow"></h4>

#### Example workflow

<div class="mermaid">
sequenceDiagram
    participant Client
    participant Fileactive

    Client->>Fileactive: POST /v1.0/auth (Obtain Bearer Token)
    Fileactive-->>Client: 200 OK (Bearer Token)

    Client->>Fileactive: POST /payment/hk/v1.0/rtgs (Submit RTGS Payment)
    Fileactive-->>Client: 202 Accepted (Payment Processing)

    Client->>Fileactive: GET /payment/hk/v1.0/rtgs/{paymentId} (Check Payment Status)
    alt Payment Completed
        Fileactive-->>Client: 200 OK (Payment Success)
    else Payment Pending
        Fileactive-->>Client: 202 Accepted (Payment Pending)
    else Payment Failed
        Fileactive-->>Client: 400 Bad Request (Payment Failed)
    end
</div>

RTGS Payment

---
layout: code
title: Hong Kong CBFT
menu_key: hkPayments
group: fileactive
hero_key: payments
payload_spec: "/fileactive/api/payments/hk/data/cbft-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
---

---
The Hong Kong CBFT (Cross-Border Funds Transfer) Payments API facilitates secure and efficient processing of cross-border transactions, enabling businesses to send and receive funds globally. This API is designed to handle various currencies and support compliance with international payment standards and regulations.

---
[Capabilities](#capable) 

<h4 name="capable" id="capable"></h4>

#### Capabilities

- **Cross-Border transfers:** Supports international payments, allowing businesses to conduct transactions with partners and customers globally.
- **Multi-Currency support:** Handles payments in multiple currencies, providing flexibility for international trade and financial operations.
- **Compliance and reporting:** Ensures compliance with international financial regulations, including anti-money laundering (AML) and know-your-customer (KYC) requirements, with detailed transaction reporting.
- **Flexible payment types:** Supports various payment types including SWIFT, local clearing, and other international payment networks, providing a versatile solution for different business needs.

---
[Technical requirements](#require) 

<h4 name="require" id="require"></h4>

#### Technical requirements

- **Authentication:** Use OAuth 2.0 with the Client Credential Grant flow for secure access. Obtain a bearer token from the `/v1.0/auth` endpoint and include it in the authorisation header as `Bearer <access_token>`.
- **API Endpoint:** CBFT payment requests should be submitted to the `/payment/hk/v1.0/cbft` endpoint.
- **Headers:** Ensure all API requests include headers such as `Content-Type: application/json` and `authorisation: Bearer <access_token>`.
- **Payload Format:** Submit payment details in JSON format, following the schema specified in the API documentation for CBFT payments.

---
[Key features for developers](#develop) 

<h4 name="develop" id="develop"></h4>

#### Key features for developers

- **Secure Cross-Border transfers:** Leverage CBFT for secure and efficient international payments, reducing the risk associated with cross-border financial transactions.
- **Real-Time status updates:** Monitor payment statuses in real-time, providing immediate visibility into the transaction flow and confirmation of fund transfers.
- **Detailed reporting:** Access comprehensive transaction reports that help meet compliance requirements and provide valuable insights into international payment activities.
- **Scalability:** Capable of handling high volumes of transactions, supporting routine and peak business operations without compromising performance.

---
[Example workflow](#flow) 

<h4 name="flow" id="flow"></h4>

#### Example workflow

<div class="mermaid">
sequenceDiagram
    participant Client
    participant Fileactive

    Client->>Fileactive: POST /v1.0/auth (Obtain Bearer Token)
    Fileactive-->>Client: 200 OK (Bearer Token)

    Client->>Fileactive: POST /payment/hk/v1.0/cbft (Submit CBFT Payment)
    Fileactive-->>Client: 202 Accepted (Payment Processing)

    Client->>Fileactive: GET /payment/hk/v1.0/cbft/{paymentId} (Check Payment Status)
    alt Payment Completed
        Fileactive-->>Client: 200 OK (Payment Success)
    else Payment Pending
        Fileactive-->>Client: 202 Accepted (Payment Pending)
    else Payment Failed
        Fileactive-->>Client: 400 Bad Request (Payment Failed)
    end
</div>

CBFT Payment

---
layout: detail
title: India payments
menu_key: inPayments
group: fileactive
hero_key: payments
---

---
The Fileactive API provides secure and reliable ACH payment processing for India, enabling businesses to automate clearing house transactions with ease. By leveraging robust security features such as OAuth 2.0 and JWT encryption, the API ensures that domestic payments are processed efficiently and securely.

---
[Key features](#feature) 

<h4 name="feature" id="feature"></h4>

#### Key Features:
- **ACH:** Efficiently manage domestic automated clearing house payments in India.

- **Secure Authentication:** Ensure strong security for all transactions with OAuth 2.0 and JWT.

- **Status Tracking:** Easily track the status of ACH payments through dedicated API endpoints.

---

---
[Rate limits and throttling:](#limits) 

<h4 name="limits" id="limits"></h4>

#### Rate limits and throttling:

By default the following rate limits are applied.

<table style="border-collapse: collapse; width: 100%;">
  <thead>
    <tr style="background-color: #f2f2f2; border: 1px solid #ddd;">
      <th style="border: 1px solid #ddd; padding: 8px;">Type</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPH (Transactions Per Hour)</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPM (Transactions Per Minute)</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPS (Transactions Per Second)</th>
    </tr>
  </thead>
  <tbody>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Authorisation</td>
      <td style="border: 1px solid #ddd; padding: 8px;">10</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Payments</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">30</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
     <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Payment Enquiry</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">90</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
  </tbody>
</table>

---
[Rate limiting algorithms](#algor) 

<h4 name="algor" id="algor"></h4>

#### Rate limiting algorithms:

For most use cases one of two algorithms is implemented for rate limiting.

**Fixed Window**
The system uses a window size of `n` seconds (typically using human-friendly values, such as 60 or 3600 seconds) to track the fixed window algorithm rate. Each incoming request increments the counter for the window. It discards the request if the counter exceeds a threshold. The current timestamp floor typically defines the windows, so 12:00:03, with a 60-second window length, would be in the 12:00:00 window.

**Sliding Window**
Sliding Window is a hybrid approach. Like the fixed window algorithm, we track a counter for each fixed window. Next, we account for a weighted value of the previous window’s request rate based on the current timestamp to smooth out bursts of traffic.

[Sliding window example](#example) 

<h4 name="example" id="example"></h4>

#### Sliding window example:

**Given a limit of 100 transactions per hour.**

- **Window 1 (13:00 - 14:00)**  
  Between 13:00 - 14:00, 80 requests are received. This is within the 100 tph limit, so all are allowed.

- **Window 2 (14:00 - 15:00)**  
  By 14:15, 20 requests are received. This is 25% (15 minutes) into window 2, so the weighted average would include 75% from the previous window.

  **Request rate**: 20 (all requests within window 2) + 60 (75% of requests from window 1) = 80 requests.  
  The request rate is still within the 100 tph maximum.

  By 14:30, 75 requests have been received. This is 50% (30 minutes) into window 2, so the weighted average would include 50% from the previous window.

  **Request rate**: 75 (all requests within window 2) + 40 (50% weighted average from previous window) = 115 requests.  
  This exceeds the 100 tph limit, so further requests would return an HTTP 429 (Too Many Requests) status code until the weighted request rate is below the agreed limit.

  By 14:45, no further requests have been made. This is 75% (45 minutes) through window 2.

  **Request rate**: 75 (current window) + 20 (25% weighted average from previous window) = 95 requests.  
  As this is below the 100 tph limit, further requests will be accepted.

openapi: 3.0.1
info:
    title: Fileactive Authentication API
    version: 2.1.0
servers:
  - url: https://api.fileactive.uat.anzgcis.com
    description: UAT Test environment
  - url: https://api.fileactive.anzgcis.com
    description: Production Environment
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /v1.0/auth:
    post:
      security:
        - apiKeyAuth: []
          oAuth2: []
      summary: Auth Token Request
      description: >
        ANZ uses OAuth 2.0 to authenticate inbound token requests, a bearer token
        is returned as a response which is then used to authorise against ANZ
        resources.
      operationId: auth
      requestBody:
        description: 'Information and examples of Auth request body '
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/authTokenRequest'
      responses:
        '200':
          $ref: '#/components/responses/200OKAuth'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorised'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalError'
        '502':
          $ref: '#/components/responses/502BadGateway'
        '503':
          $ref: '#/components/responses/503Unavailable'
        '504':
          $ref: '#/components/responses/504Timeout'
        default:
          $ref: '#/components/responses/default'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: uuid
      description: Bearer token obtained during token exchange
    apiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: API key to authorise requests.
    oAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.fileactive.anzgcis.com/v1.0/auth
          scopes:
            IN.INSTO.PAYMENT.ACH.CREATE: Create India ACH Payment Resource   
            IN.INSTO.PAYMENT.READ: Retrieve information for specific payment resource   
    apiKey:
      type: apiKey
      in: header
      name: apikey
      description: API key to authorise requests.
  responses:
    200OKAuth:
      description: Bearer token (Opaque Token) returned after a token request
      headers:
        x-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/authTokenResponse'
    400BadRequest:
      description: Bad Request, message format does not match expected schema
      content: {}
    401Unauthorised:
      description: Application is not unauthorised to perform a specific action
      content: {}
    403Forbidden:
      description: Action is not authorised using current authentication credentils
      content: {}
    404NotFound:
      description: No record found
      content: {}
    429TooManyRequests:
      description: Action exceeds allocated limits
      content: {}
    500InternalError:
      description: Internal Server Error, contact support
      content: {}
    502BadGateway:
      description: Bad Gateway, contact support
      content: {}
    503Unavailable:
      description: Service Unavailable or down for maintainance
      content: {}
    504Timeout:
      description: Gateway Timeout, retry or contact support
      content: {}
    default:
      description: Unexpected error
      content: {}
  schemas:
    authTokenRequest:
      required:
        - grant_type
        - client_assertion_type
        - scope
        - client_assertion
      type: object
      properties:
        grant_type:
          description: Specify the type credential requested
          type: string
          example: client_credentials
        client_assertion_type:
          description: >-
            Describes the type of client assertion provided in the message
            request
          type: string
          example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
        scope:
          $ref: '#/components/securitySchemes/oAuth2/flows/clientCredentials/scopes'
        client_assertion:
          $ref: '#/components/schemas/ClientAssertion'
    authTokenResponse:
      type: object
      description: Response to report the status of a customer credit transfer.
      additionalProperties: false
      properties:
        expires_in:
          description: Indication on how long a token is valid for
          type: integer
        token_type:
          description: Type of token returned
          type: string
        access_token:
          description: >-
            Opaque token returned as part of request, Fileactive does not provide the
            full access token
          type: string
      example:
        expires_in: 3600
        token_type: Bearer
        access_token: eaaa13ee-b596-a8cc-b9d4-f778f8bb9377
    ClientAssertion:
      required:
        - sub
        - exp
        - aud
      type: object
      properties:
        sub:
          type: string
          description: Customer Code as provided by ANZ onboarding
          example: CUSTOMERA
        exp:
          type: integer
          description: EPOCH date and time
          example: '1619658591'
          maxLength: 10
          minLength: 10
        aud:
          type: string
          description: Specify the intended audience of the token request
          example: https://api.fileactive.anzgcis.com/auth
    UUID:
      type: string
      example: 71d6fb19-7515-40dc-b045-e17550b67600
      pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
  parameters:
    requestKey:
      name: X-REQUESTKEY
      in: header
      description: Internal End to End key used for support and reporting purposes
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275

---
layout: code
title: Authentication
menu_key: auth
group: fileactive
hero_key: fileactive
payload_spec: "/fileactive/api/payments/in/data/auth-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
---

---
To interact with ANZ Fileactive APIs for India, 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](#capable) 

<h4 name="capable" id="capable"></h4>

#### Key Points:

- **Endpoint:** All authentication requests should be sent to the `/v1.0/auth` endpoint.
- **Grant Type:** Use `client_credentials` as the grant type for obtaining tokens.
- **Token URL:** The token URL is `https://api.fileactive.anzgcis.com/v1.0/auth`.
- **Scopes:** Specific scopes define the permissions, such as:
  - `IN.INSTO.PAYMENT.ACH.CREATE` - For creating ACH Payment resources in India.
  - `IN.INSTO.PAYMENT.ACH.READ` - For retrieving ACH Payment resources in India.
- **Headers:** Include an API key in the header using `apikey` as the parameter name.

---
[Example request](#send) 

<h4 name="send" id="send"></h4>

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

```http
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=IN.INSTO.PAYMENT.ACH.CREATE&
client_assertion=<your_client_assertion_here>
```

---
[Example response](#receive) 

<h4 name="receive" id="receive"></h4>

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

```json
{
  "expires_in": 3600,
  "token_type": "Bearer",
  "access_token": "eaaa13ee-b596-a8cc-b9d4-f778f8bb9377"
}
```
---
[Usage notes](#usage) 

<h4 name="usage" id="usage"></h4>

#### 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](#note) 

<h4 name="note" id="note"></h4>

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

---
layout: code
title: India ACH
menu_key: inPayments
group: fileactive
hero_key: payments
overview_tab: "true"
payload_spec: "/fileactive/api/payments/in/data/ach-api-payload.yaml"
payload_tab: "true" 
---

---
The India ACH (Automated Clearing House) Payments API allows businesses to efficiently initiate and manage domestic payments within India. Designed for handling bulk and low-value transactions, this API is suitable for payroll, vendor payments, recurring transactions, and other financial operations requiring automated processing.

---
[Capabilities](#capable) 

<h4 name="capable" id="capable"></h4>

#### Capabilities

- **Payment Initiation:** Submit ACH payment requests to facilitate the transfer of funds between bank accounts within India.
- **Bulk Processing:** Supports batch payments, enabling the submission of multiple transactions in a single request for efficient processing.
- **Status Tracking:** Monitor the status of submitted payments to ensure successful processing and manage exceptions.
- **Secure and Compliant:** Transactions are securely processed with encryption and comply with Indian regulatory requirements, including NPCI (National Payments Corporation of India) standards.

---
[Technical requirements](#require) 

<h4 name="require" id="require"></h4>

#### Technical Requirements

- **Authentication:** Utilize OAuth 2.0 with the Client Credential Grant flow for secure access. Obtain a bearer token from the `/v1.0/auth` endpoint and include it in the authorisation header as `Bearer <access_token>`.
- **API Endpoint:** ACH payment requests are sent to the `/payment/in/v1.0/ach` endpoint.
- **Headers:** Ensure headers like `Content-Type: application/json` and `authorisation: Bearer <access_token>` are included in your requests.
- **Payload Format:** Payments should be submitted in JSON format, conforming to the ACH payment schema provided in the API documentation.

---
[Key features for developers](#devops) 

<h4 name="devops" id="devops"></h4>

#### Key Features for Developers

- **Automated Bulk Payments:** Streamline bulk payment operations such as payroll, utility payments, or supplier payouts with automation, reducing manual effort and errors.
- **Batch Processing:** Efficiently manage high volumes of transactions through batch processing, improving system performance and reducing transaction times.
- **Real-Time Monitoring:** Access real-time updates on the status of each payment, providing transparency and enabling quick resolution of issues.
- **Detailed Error Responses:** Receive comprehensive error codes and messages to help diagnose and resolve issues quickly during integration.

---
[Example workflow](#exampl) 

<h4 name="exampl" id="exampl"></h4>

#### Example Workflow

<div class="mermaid">
sequenceDiagram
    participant Client
    participant Fileactive

    Client->>Fileactive: POST /v1.0/auth (Obtain Bearer Token)
    Fileactive-->>Client: 200 OK (Bearer Token)

    Client->>Fileactive: POST /payment/in/v1.0/ach (Submit ACH Payment)
    Fileactive-->>Client: 202 Accepted (Payment Processing)

    Client->>Fileactive: GET /payment/in/v1.0/ach/{paymentId} (Check Payment Status)
    alt Payment Completed
        Fileactive-->>Client: 200 OK (Payment Success)
    else Payment Pending
        Fileactive-->>Client: 202 Accepted (Payment Pending)
    else Payment Failed
        Fileactive-->>Client: 400 Bad Request (Payment Failed)
    end
</div>

---
layout: detail
title: Singapore payments
menu_key: sgPayments
group: fileactive
hero_key: payments
---

---
Fileactive API offers comprehensive payment solutions in Singapore, supporting ACH for automated clearing, FAST for instant transfers, RTGS for high-value settlements, and CBFT for cross-border payments. With robust security measures including OAuth 2.0 and JWT encryption, the API facilitates both domestic and international transactions efficiently.

---
[Key features](#test) 

<h4 name="test" id="test"></h4>

#### Key features:
- **ACH:** Manage automated clearing house payments seamlessly within Singapore.

- **FAST:** Instant domestic payment processing for quick and reliable fund transfers.

- **RTGS:** Real-time gross settlement for high-value, time-critical payments.

- **CBFT:** Handle cross-border funds transfers securely to meet international payment needs.

- **Secure authentication:** Utilize OAuth 2.0 and JWT for enhanced security in all payment transactions.

- **Status tracking:** Access real-time payment statuses through dedicated endpoints.

---
[Rate limits and throttling:](#limits) 

<h4 name="limits" id="limits"></h4>

#### Rate limits and throttling:

By default the following rate limits are applied.

<table style="border-collapse: collapse; width: 100%;">
  <thead>
    <tr style="background-color: #f2f2f2; border: 1px solid #ddd;">
      <th style="border: 1px solid #ddd; padding: 8px;">Type</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPH (Transactions Per Hour)</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPM (Transactions Per Minute)</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPS (Transactions Per Second)</th>
    </tr>
  </thead>
  <tbody>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Authorisation</td>
      <td style="border: 1px solid #ddd; padding: 8px;">10</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Payments</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">30</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
     <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Payment Enquiry</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">90</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
  </tbody>
</table>

---
[Rate limiting algorithms](#algor) 

<h4 name="algor" id="algor"></h4>

#### Rate limiting algorithms:

For most use cases one of two algorithms is implemented for rate limiting.

**Fixed Window**
The system uses a window size of `n` seconds (typically using human-friendly values, such as 60 or 3600 seconds) to track the fixed window algorithm rate. Each incoming request increments the counter for the window. It discards the request if the counter exceeds a threshold. The current timestamp floor typically defines the windows, so 12:00:03, with a 60-second window length, would be in the 12:00:00 window.

**Sliding Window**
Sliding Window is a hybrid approach. Like the fixed window algorithm, we track a counter for each fixed window. Next, we account for a weighted value of the previous window’s request rate based on the current timestamp to smooth out bursts of traffic.

[Sliding window example](#example) 

<h4 name="example" id="example"></h4>

#### Sliding window example:

**Given a limit of 100 transactions per hour.**

- **Window 1 (13:00 - 14:00)**  
  Between 13:00 - 14:00, 80 requests are received. This is within the 100 tph limit, so all are allowed.

- **Window 2 (14:00 - 15:00)**  
  By 14:15, 20 requests are received. This is 25% (15 minutes) into window 2, so the weighted average would include 75% from the previous window.

  **Request rate**: 20 (all requests within window 2) + 60 (75% of requests from window 1) = 80 requests.  
  The request rate is still within the 100 tph maximum.

  By 14:30, 75 requests have been received. This is 50% (30 minutes) into window 2, so the weighted average would include 50% from the previous window.

  **Request rate**: 75 (all requests within window 2) + 40 (50% weighted average from previous window) = 115 requests.  
  This exceeds the 100 tph limit, so further requests would return an HTTP 429 (Too Many Requests) status code until the weighted request rate is below the agreed limit.

  By 14:45, no further requests have been made. This is 75% (45 minutes) through window 2.

  **Request rate**: 75 (current window) + 20 (25% weighted average from previous window) = 95 requests.  
  As this is below the 100 tph limit, further requests will be accepted.

openapi: 3.0.1
info:
    title: Fileactive Authentication API
    version: 2.1.0
servers:
  - url: https://api.fileactive.uat.anzgcis.com
    description: UAT Test environment
  - url: https://api.fileactive.anzgcis.com
    description: Production Environment
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /v1.0/auth:
    post:
      security:
        - apiKeyAuth: []
          oAuth2: []
      summary: Auth Token Request
      description: >
        ANZ uses OAuth 2.0 to authenticate inbound token requests, a bearer token
        is returned as a response which is then used to authorise against ANZ
        resources.
      operationId: auth
      requestBody:
        description: 'Information and examples of Auth request body '
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/authTokenRequest'
      responses:
        '200':
          $ref: '#/components/responses/200OKAuth'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorised'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalError'
        '502':
          $ref: '#/components/responses/502BadGateway'
        '503':
          $ref: '#/components/responses/503Unavailable'
        '504':
          $ref: '#/components/responses/504Timeout'
        default:
          $ref: '#/components/responses/default'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: uuid
      description: Bearer token obtained during token exchange
    apiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: API key to authorise requests.
    oAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.fileactive.anzgcis.com/v1.0/auth
          scopes:
            SG.INSTO.PAYMENT.ACH.CREATE: Create Singapore ACH Payment Resource   
            SG.INSTO.PAYMENT.FAST.CREATE: Create Singapore FAST Payment Resource   
            SG.INSTO.PAYMENT.RTGS.CREATE: Create Singapore RTGS Payment Resource
            SG.INSTO.PAYMENT.CBFT.CREATE: Create Singapore CBFT Payment Resource  
            SG.INSTO.PAYMENT.READ: Retrieve information for specific payment resource   
    apiKey:
      type: apiKey
      in: header
      name: apikey
      description: API key to authorise requests.
  responses:
    200OKAuth:
      description: Bearer token (Opaque Token) returned after a token request
      headers:
        x-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/authTokenResponse'
    400BadRequest:
      description: Bad Request, message format does not match expected schema
      content: {}
    401Unauthorised:
      description: Application is not unauthorised to perform a specific action
      content: {}
    403Forbidden:
      description: Action is not authorised using current authentication credentils
      content: {}
    404NotFound:
      description: No record found
      content: {}
    429TooManyRequests:
      description: Action exceeds allocated limits
      content: {}
    500InternalError:
      description: Internal Server Error, contact support
      content: {}
    502BadGateway:
      description: Bad Gateway, contact support
      content: {}
    503Unavailable:
      description: Service Unavailable or down for maintainance
      content: {}
    504Timeout:
      description: Gateway Timeout, retry or contact support
      content: {}
    default:
      description: Unexpected error
      content: {}
  schemas:
    authTokenRequest:
      required:
        - grant_type
        - client_assertion_type
        - scope
        - client_assertion
      type: object
      properties:
        grant_type:
          description: Specify the type credential requested
          type: string
          example: client_credentials
        client_assertion_type:
          description: >-
            Describes the type of client assertion provided in the message
            request
          type: string
          example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
        scope:
          $ref: '#/components/securitySchemes/oAuth2/flows/clientCredentials/scopes'
        client_assertion:
          $ref: '#/components/schemas/ClientAssertion'
    authTokenResponse:
      type: object
      description: Response to report the status of a customer credit transfer.
      additionalProperties: false
      properties:
        expires_in:
          description: Indication on how long a token is valid for
          type: integer
        token_type:
          description: Type of token returned
          type: string
        access_token:
          description: >-
            Opaque token returned as part of request, Fileactive does not provide the
            full access token
          type: string
      example:
        expires_in: 3600
        token_type: Bearer
        access_token: eaaa13ee-b596-a8cc-b9d4-f778f8bb9377
    ClientAssertion:
      required:
        - sub
        - exp
        - aud
      type: object
      properties:
        sub:
          type: string
          description: Customer Code as provided by ANZ onboarding
          example: CUSTOMERA
        exp:
          type: integer
          description: EPOCH date and time
          example: '1619658591'
          maxLength: 10
          minLength: 10
        aud:
          type: string
          description: Specify the intended audience of the token request
          example: https://api.fileactive.anzgcis.com/auth
    UUID:
      type: string
      example: 71d6fb19-7515-40dc-b045-e17550b67600
      pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
  parameters:
    requestKey:
      name: X-REQUESTKEY
      in: header
      description: Internal End to End key used for support and reporting purposes
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275

---
layout: code
title: Authentication
menu_key: auth
group: fileactive
hero_key: fileactive
payload_spec: "/gcis/api-portal/fileactive/api/payments/sg/data/auth-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
---

---
To interact with ANZ Fileactive APIs for Singapore, 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](#capable) 

<h4 name="capable" id="capable"></h4>

#### Key points:

- **Endpoint:** All authentication requests should be sent to the `/v1.0/auth` endpoint.
- **Grant Type:** Use `client_credentials` as the grant type for obtaining tokens.
- **Token URL:** The token URL is `https://api.fileactive.anzgcis.com/v1.0/auth`.
- **Scopes:** Specific scopes define the permissions, such as:
  - `SG.INSTO.PAYMENT.ACH.CREATE` - For creating ACH Payment resources in Singapore.
  - `SG.INSTO.PAYMENT.ACH.READ` - For retrieving ACH Payment resources in Singapore.
  - `SG.INSTO.PAYMENT.FAST.CREATE` - For creating FAST Payment resources in Singapore.
  - `SG.INSTO.PAYMENT.FAST.READ` - For retrieving FAST Payment resources in Singapore.
  - `SG.INSTO.PAYMENT.RTGS.CREATE` - For creating RTGS Payment resources in Singapore.
  - `SG.INSTO.PAYMENT.RTGS.READ` - For retrieving RTGS Payment resources in Singapore.
  - `SG.INSTO.PAYMENT.CBFT.CREATE` - For creating CBFT Payment resources in Singapore.
  - `SG.INSTO.PAYMENT.CBFT.READ` - For retrieving CBFT Payment resources in Singapore.
- **Headers:** Include an API key in the header using `apikey` as the parameter name.

---
[Example request](#send) 

<h4 name="send" id="send"></h4>

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

```http
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=SG.INSTO.PAYMENT.ACH.CREATE&
client_assertion=<your_client_assertion_here>
```
---
[Example response](#receive) 

<h4 name="receive" id="receive"></h4>

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

```json
{
  "expires_in": 3600,
  "token_type": "Bearer",
  "access_token": "eaaa13ee-b596-a8cc-b9d4-f778f8bb9377"
}
```
---
[Usage notes](#usage) 

<h4 name="usage" id="usage"></h4>

#### 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](#note) 

<h4 name="note" id="note"></h4>

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

---
layout: code
title: Singapore ACH
menu_key: sgPayments
group: fileactive
hero_key: payments
payload_spec: "/gcis/api-portal/fileactive/api/payments/sg/data/ach-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"  
---

---
Singapore ACH (Automated Clearing House) payments enable businesses to process batch transactions, including payroll, vendor payments, and other recurring transactions, efficiently and securely. Leveraging the ANZ Fileactive API, ACH payments in Singapore offer a streamlined solution for managing bulk payments within a standardized framework, ensuring compliance with local financial regulations.

---
[Capabilities](#capable) 

<h4 name="capable" id="capable"></h4>

#### Capabilities

- **Batch processing:** Facilitate the submission of multiple transactions in a single request, Optimising processing efficiency for high-volume payments.
- **Scheduled payments:** Set up future-dated payments, allowing businesses to plan and automate their cash flow management.
- **Reconciliation support:** Provides detailed transaction reports to help with account reconciliation and financial tracking.
- **Secure transactions:** Transactions are secured through OAuth 2.0 authentication and encrypted communications, ensuring the safety of financial data.

---
[Technical requirements](#require) 

<h4 name="require" id="require"></h4>

#### Technical requirements

- **Authentication:** All API requests require OAuth 2.0 authentication using the Client Credential Grant flow. Obtain a bearer token from the `/v1.0/auth` endpoint.
- **Endpoint:** Use the `/payment/sg/v1.0/ach` endpoint for submitting ACH payment requests.
- **Data Format:** Requests must be sent in JSON format, and responses will be provided in JSON format as well.
- **Rate Limits:** Ensure compliance with the API rate limits to avoid throttling or access restrictions.

---
[Key features for developers](#develop) 

<h4 name="develop" id="develop"></h4>

#### Key features for developers

- **API integration:** Simple RESTful API that allows developers to easily integrate ACH payment capabilities into their systems.
- **Error handling:** Detailed error responses assist in quickly identifying and resolving issues during payment processing.
- **Real-Time status updates:** Monitor the status of submitted payments with real-time notifications, improving visibility and control over transactions.

<div class="mermaid">
sequenceDiagram
    participant Business
    participant ANZ Fileactive

    %% Authentication Flow
    Business->>ANZ Fileactive: POST /v1.0/auth (OAuth Client Credential Grant)
    ANZ Fileactive-->>Business: 200 OK (Bearer Token)

    %% ACH Payment Request Flow
    Business->>ANZ Fileactive: POST /payment/sg/v1.0/ach (Submit ACH Payment)
    ANZ Fileactive-->>Business: 202 Accepted (Payment Request Received)

    %% Payment Status Check
    Note right of ANZ Fileactive: Processes the payment<br>and updates the status
    Business->>ANZ Fileactive: GET /payment/sg/v1.0/ach/{paymentId} (Check Payment Status)
    ANZ Fileactive-->>Business: 200 OK (Payment Status)
</div>

---
layout: code
title: Singapore Fast
menu_key: sgPayments
group: fileactive
hero_key: payments
payload_spec: "/gcis/api-portal/fileactive/api/payments/sg/data/fast-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"  
---

---
Singapore FAST (Fast And Secure Transfers) payments allow businesses to conduct real-time, instant payments between banks in Singapore. Utilizing the ANZ Fileactive API, FAST payments offer a quick and reliable way to handle transactions, supporting both business-to-business and business-to-consumer payment needs.

---
[Capabilities](#capable) 

<h4 name="capable" id="capable"></h4>

#### Capabilities

- **Instant Payments:** Enables real-time processing of payments, ensuring funds are transferred and available immediately.
- **24/7 Availability:** FAST payments can be made at any time, providing flexibility and convenience for businesses operating outside of regular banking hours.
- **Enhanced Cash Flow Management:** Improve liquidity management with immediate transaction processing, aiding in better cash flow control.
- **Secure Transactions:** All payments are securely processed using OAuth 2.0 authentication and encrypted communications to protect sensitive financial information.

---
[Technical requirements](#require) 

<h4 name="require" id="require"></h4>

#### Technical requirements

- **Authentication:** Use OAuth 2.0 with the Client Credential Grant flow to authenticate API requests. Obtain a bearer token from the `/v1.0/auth` endpoint.
- **Endpoint:** Use the `/payment/sg/v1.0/fast` endpoint to submit FAST payment requests.
- **Data Format:** Requests and responses are in JSON format, ensuring easy integration and data handling.
- **Rate Limits:** Adhere to the APIs rate limits to avoid throttling and ensure smooth operation.

---
[Key features for developers](#develop) 

<h4 name="develop" id="develop"></h4>

#### Key features for developers

- **Simple Integration:** RESTful API design allows for seamless integration of FAST payment capabilities into existing systems.
- **Real-Time Feedback:** Receive immediate status updates and confirmations for payments, allowing for responsive transaction management.
- **Error Handling:** Comprehensive error responses help developers quickly identify and resolve issues during the payment process.
- **Support for multiple use cases:** Ideal for various business needs, including payroll, vendor payments, and consumer disbursements.

<div class="mermaid">
sequenceDiagram
    participant Business
    participant ANZ Fileactive

    %% Authentication Flow
    Business->>ANZ Fileactive: POST /v1.0/auth (OAuth Client Credential Grant)
    ANZ Fileactive-->>Business: 200 OK (Bearer Token)

    %% FAST Payment Request Flow
    Business->>ANZ Fileactive: POST /payment/sg/v1.0/fast (Submit FAST Payment)
    ANZ Fileactive-->>Business: 202 Accepted (Payment Request Received)

    %% Payment Status Check
    Note right of ANZ Fileactive: Processes the payment<br>and updates the status
    Business->>ANZ Fileactive: GET /payment/sg/v1.0/fast/{paymentId} (Check Payment Status)
    ANZ Fileactive-->>Business: 200 OK (Payment Status)
</div>

FAST Payment

---
layout: code
title: Singapore RTGS
menu_key: sgPayments
group: fileactive
hero_key: payments
payload_spec: "/gcis/api-portal/fileactive/api/payments/sg/data/rtgs-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"  
---

---
Singapore RTGS (Real-Time Gross Settlement) is designed for high-value and time-critical payments. Through ANZ Fileactive APIs, businesses can leverage RTGS to settle transactions individually and in real-time, providing a secure and efficient method for large payments within Singapore.

---
[Capabilities](#capable) 

<h4 name="capable" id="capable"></h4>

#### Capabilities

- **High-Value payments:** Suitable for large-scale transactions that require immediate settlement.
- **Real-Time processing:** Payments are processed individually in real time, ensuring no delays and immediate fund availability.
- **Priority handling:** Designed for time-sensitive payments where prompt settlement is essential.
- **Secure transactions:** All payments are securely handled through OAuth 2.0 authentication and encrypted data transfer, ensuring the integrity and confidentiality of transactions.

---
[Technical requirements](#require) 

<h4 name="require" id="require"></h4>

#### Technical requirements

- **Authentication:** Use OAuth 2.0 with the Client Credential Grant flow to obtain a bearer token from the `/v1.0/auth` endpoint for secure access.
- **Endpoint:** Submit RTGS payment requests using the `/payment/sg/v1.0/rtgs` endpoint.
- **Data Format:** All interactions use JSON format, facilitating straightforward integration and data manipulation.
- **Compliance:** Ensure adherence to regulatory requirements and standards for high-value payments.

---
[Key features for developers](#develop) 

<h4 name="develop" id="develop"></h4>

#### Key features for developers

- **Robust integration:** RESTful API design allows developers to easily integrate RTGS capabilities into existing systems for seamless high-value transaction processing.
- **Real-Time monitoring:** Provides immediate feedback on transaction status, allowing businesses to track payments in real-time.
- **Error management:** Detailed error responses assist developers in quickly identifying and addressing issues during payment processing.
- **High reliability:** Designed for high-value, time-sensitive payments, ensuring transactions are processed with utmost reliability and priority.

<div class="mermaid">
sequenceDiagram
    participant Business
    participant ANZ Fileactive

    %% Authentication Flow
    Business->>ANZ Fileactive: POST /v1.0/auth (OAuth Client Credential Grant)
    ANZ Fileactive-->>Business: 200 OK (Bearer Token)

    %% RTGS Payment Request Flow
    Business->>ANZ Fileactive: POST /payment/sg/v1.0/rtgs (Submit RTGS Payment)
    ANZ Fileactive-->>Business: 202 Accepted (Payment Request Received)

    %% Payment Status Check
    Note right of ANZ Fileactive: Processes the payment<br>and updates the status
    Business->>ANZ Fileactive: GET /payment/sg/v1.0/rtgs/{paymentId} (Check Payment Status)
    ANZ Fileactive-->>Business: 200 OK (Payment Status)
</div>

---
layout: code
title: Singapore CBFT
menu_key: sgPayments
group: fileactive
hero_key: payments
payload_spec: "/gcis/api-portal/fileactive/api/payments/sg/data/cbft-api-payload.yaml"
overview_tab: "true" 
payload_tab: "true"   
---

---
Singapore CBFT (Cross-Border Funds Transfer) allows businesses to execute international payments securely and efficiently through ANZ Fileactive APIs. It is designed for sending funds across borders, supporting various currencies and ensuring compliance with international payment standards.

---
[Capabilities](#capable) 

<h4 name="capable" id="capable"></h4>

#### Capabilities

- **International transfers:** Enables seamless cross-border payments from Singapore to global destinations, supporting multiple currencies and complying with international regulations.
- **Secure transactions:** Utilizes OAuth 2.0 authentication and encrypted communication to ensure the security and integrity of transactions.
- **Flexible payment options:** Supports different types of cross-border payment instructions, catering to various business needs.
- **Compliance and reporting:** Provides comprehensive compliance checks and reporting features to meet regulatory requirements for cross-border transactions.

---
[Technical requirements](#require) 

<h4 name="require" id="require"></h4>

#### Technical requirements

- **Authentication:** Use OAuth 2.0 with the Client Credential Grant flow to obtain a bearer token from the `/v1.0/auth` endpoint for secure access.
- **Endpoint:** Submit CBFT payment requests using the `/payment/sg/v1.0/cbft` endpoint.
- **Data Format:** All interactions use JSON format, simplifying integration and data handling.
- **Compliance:** Transactions comply with international standards and regulations, ensuring smooth cross-border payments.

---
[Key features for developers](#develop) 

<h4 name="develop" id="develop"></h4>

#### Key features for developers

- **Easy integration:** RESTful API design allows developers to integrate CBFT capabilities into existing systems with minimal effort, enhancing international payment workflows.
- **Real-Time processing:** Provides near real-time feedback on payment status, enabling businesses to track cross-border transactions effectively.
- **Error handling:** Detailed error codes and responses help developers quickly resolve issues and ensure reliable payment processing.
- **Comprehensive documentation:** Access to detailed API documentation supports efficient integration and utilization of CBFT capabilities.

<div class="mermaid">
sequenceDiagram
    participant Business
    participant ANZ Fileactive

    %% Authentication Flow
    Business->>ANZ Fileactive: POST /v1.0/auth (OAuth Client Credential Grant)
    ANZ Fileactive-->>Business: 200 OK (Bearer Token)

    %% CBFT Payment Request Flow
    Business->>ANZ Fileactive: POST /payment/sg/v1.0/cbft (Submit CBFT Payment)
    ANZ Fileactive-->>Business: 202 Accepted (Payment Request Received)

    %% Payment Status Check
    Note right of ANZ Fileactive: Processes the payment<br>and updates the status
    Business->>ANZ Fileactive: GET /payment/sg/v1.0/cbft/{paymentId} (Check Payment Status)
    ANZ Fileactive-->>Business: 200 OK (Payment Status)
</div>

---
layout: detail
title: Vietnam payments
menu_key: vnPayments
group: fileactive
hero_key: payments
---

---
The Fileactive API provides secure ACH payment processing for Vietnam, allowing businesses to efficiently manage domestic transactions. With strong security features such as OAuth 2.0 and JWT encryption, the API ensures that payments are handled with the highest level of security and reliability.

---
[Key features](#feature) 

<h4 name="feature" id="feature"></h4>

#### Key features:
- **ACH:** Automate clearing house payments for domestic transactions in Vietnam.

- **Secure authentication:** Leverage OAuth 2.0 and JWT for secure payment processing.

- **Status tracking:** Track payment statuses through dedicated API endpoints for complete visibility.

----
[Rate limits and throttling:](#limits) 

<h4 name="limits" id="limits"></h4>

#### Rate limits and throttling:

By default the following rate limits are applied.

<table style="border-collapse: collapse; width: 100%;">
  <thead>
    <tr style="background-color: #f2f2f2; border: 1px solid #ddd;">
      <th style="border: 1px solid #ddd; padding: 8px;">Type</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPH (Transactions Per Hour)</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPM (Transactions Per Minute)</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPS (Transactions Per Second)</th>
    </tr>
  </thead>
  <tbody>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Authorisation</td>
      <td style="border: 1px solid #ddd; padding: 8px;">10</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Payments</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">30</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
     <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Payment Enquiry</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">90</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
  </tbody>
</table>

---
[Rate limiting algorithms](#algor) 

<h4 name="algor" id="algor"></h4>

#### Rate limiting algorithms:

For most use cases one of two algorithms is implemented for rate limiting.

**Fixed Window**
The system uses a window size of `n` seconds (typically using human-friendly values, such as 60 or 3600 seconds) to track the fixed window algorithm rate. Each incoming request increments the counter for the window. It discards the request if the counter exceeds a threshold. The current timestamp floor typically defines the windows, so 12:00:03, with a 60-second window length, would be in the 12:00:00 window.

**Sliding Window**
Sliding Window is a hybrid approach. Like the fixed window algorithm, we track a counter for each fixed window. Next, we account for a weighted value of the previous window’s request rate based on the current timestamp to smooth out bursts of traffic.

[Sliding window example](#example) 

<h4 name="example" id="example"></h4>

#### Sliding window example:

**Given a limit of 100 transactions per hour.**

- **Window 1 (13:00 - 14:00)**  
  Between 13:00 - 14:00, 80 requests are received. This is within the 100 tph limit, so all are allowed.

- **Window 2 (14:00 - 15:00)**  
  By 14:15, 20 requests are received. This is 25% (15 minutes) into window 2, so the weighted average would include 75% from the previous window.

  **Request rate**: 20 (all requests within window 2) + 60 (75% of requests from window 1) = 80 requests.  
  The request rate is still within the 100 tph maximum.

  By 14:30, 75 requests have been received. This is 50% (30 minutes) into window 2, so the weighted average would include 50% from the previous window.

  **Request rate**: 75 (all requests within window 2) + 40 (50% weighted average from previous window) = 115 requests.  
  This exceeds the 100 tph limit, so further requests would return an HTTP 429 (Too Many Requests) status code until the weighted request rate is below the agreed limit.

  By 14:45, no further requests have been made. This is 75% (45 minutes) through window 2.

  **Request rate**: 75 (current window) + 20 (25% weighted average from previous window) = 95 requests.  
  As this is below the 100 tph limit, further requests will be accepted.

---
layout: code
title: Vietnam ACH
menu_key: vnPayments
group: fileactive
hero_key: payments
payload_spec: "/gcis/api-portal/fileactive/api/payments/vn/data/ach-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"  
---

---
The Vietnam ACH (Automated Clearing House) payments service provided by ANZ Fileactive enables businesses to process electronic transactions efficiently within Vietnam. This service is designed to facilitate batch processing of credit transfers, direct debits, and other payment types, providing a secure and reliable method for managing domestic payments.

---
[Capabilities](#capable) 

<h4 name="capable" id="capable"></h4>

#### Capabilities

- **Batch processing:** Supports the processing of large volumes of transactions in a single batch, improving operational efficiency and reducing manual effort.
- **Automated clearing:** Utilizes the ACH network to automate the clearing and settlement of payments, ensuring timely and accurate transfers.
- **Direct credits and debits:** Enables both direct credits (payments) and direct debits (collections), catering to diverse business needs.
- **Transaction reporting:** Provides detailed reports on processed transactions, including status updates and any exceptions, for easier reconciliation.

---
[Technical requirements](#require) 

<h4 name="require" id="require"></h4>

#### Technical requirements

- **API endpoint:** `/payment/vn/v1.0/ach`
- **Authentication:** Requires OAuth 2.0 authentication using the Client Credential Grant flow.
- **Formats supported:** JSON format for both requests and responses, ensuring compatibility with modern application architectures.
- **Security:** All transactions are secured using OAuth 2.0 bearer tokens, with encrypted payloads to protect sensitive information.

---
[Key features for developers](#develop) 

<h4 name="develop" id="develop"></h4>

#### Key features for developers

- **RESTful API Design:** Easy-to-use RESTful API endpoints that integrate seamlessly with your existing systems.
- **Scalability:** Designed to handle high transaction volumes, making it suitable for businesses of all sizes.
- **Error Handling:** Detailed error responses and status codes to help developers quickly identify and resolve issues.
- **Webhook Notifications:** Option to set up real-time notifications for payment status updates, enhancing visibility and control over transactions.

---
[Example workflow](#flow) 

<h4 name="flow" id="flow"></h4>

#### Example workflow

<div class="mermaid">
sequenceDiagram
    participant Client
    participant ANZ API

    Client->>ANZ API: POST /v1.0/auth (OAuth 2.0 Client Credentials)
    ANZ API-->>Client: 200 OK (Bearer Token)

    Client->>ANZ API: POST /payment/vn/v1.0/ach (Submit Payment Batch)
    ANZ API-->>Client: 202 Accepted (Batch Received)

    Note right of ANZ API: Batch is processed<br>and transactions are cleared

    Client->>ANZ API: GET /payment/vn/v1.0/ach/{batchId} (Check Batch Status)
    alt Batch Processed
        ANZ API-->>Client: 200 OK (Batch Processed Successfully)
    else Batch Pending
        ANZ API-->>Client: 204 No Content (Batch Still Processing)
    end
</div>

---
layout: detail
title: Return codes
menu_key: fileactive-payments
group: fileactive
hero_key: payments
---
---

[Default API event codes](#general) 

<h4 name="general" id="general"></h4>
<a name="general"></a>

### Default API Event Codes

| Event Code | Name                   | HTTP <BR> Response | Description                                    |
| :--------- | :--------------------- | :----------------: | :--------------------------------------------- |
| EC000_001  | Internal Server Error  |        500         | Internal Server Error, please contact support. |
| EC000_002  | Unauthorized           |        401         | The request is not authorized                  |
| EC000_003  | Validation Failure     |        400         | The request failed validation                  |
| EC000_004  | Resource Not Found     |        404         | The requested resource is not found            |
| EC000_005  | Method Not Allowed     |        405         | The requested HTTP method is not allowed       |
| EC000_006  | Unsupported Media Type |        405         | Content-Type provided is not supported         |
| EC000_007  | Invalid Content        |        400         | Invalid secured payload                        |

---

[Return to Top](#top)

[Payment event codes](#events) 

<h4 name="events" id="events"></h4>
<a name="events"></a>

### Payment Event Codes

Validation failures relating to payment submissions. The codes and status are returned in a Payment Status response message.

**Event Code Ranges**

| Range Start | Range End | Usage                   |
| :---------- | :-------- | :---------------------- |
| EC004_101   | EC004_199 | Group level error       |
| EC004_201   | EC004_299 | Payment level error     |
| EC004_301   | EC004_399 | Transaction level error |

**Payment Event Code List**

| Event Code | Status Code | Status Reason Code | Status Reason Code Description  | Error Description |
| :--------- | :---------: | :----------------: | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
|            |    RJCT     |        NARR        | Narrative                       | Reason is provided as narrative information in the additional reason information.<br/>Generic error which will be returned where no external reason code is available.<br/>For rejections from downstream applications additional_information will contain proprietary rejection code and reason in format:<br/>(\<rejection code\>) \<rejection reason\><br/>I.e "(1234) Insufficient funds"|
| EC004_101  |    RJCT     |        TD03        | InvalidPayment                  | Schema validation failed against the payment schema, error details \[Missing or invalid X-Message-Id\]|
| EC004_102  |    RJCT     |        TD03        | DuplicatePayment                | Duplicate payment received (supplied X-Message-Id value: \[X-Message-Id\]|
| EC004_103  |    RJCT     |        TD03        | CryptoFailure                   | Failed to decrypt and verify the message|
| EC004_104  |    RJCT     |        TD03        | SchemaValidation                | Schema validation failed against the payment schema, error details \[{errorDetail}\]|
| EC004_105  |    RJCT     |        DT02        | PaymentProcessingFailed         | Payment processing failed, please re-submit and try again|
| EC004_106  |    RJCT     |        DT02        | InvalidCreationDate             | creation_date_time is too far in the past (greater than 24 hours), or in the future|
| EC004_107  |    RJCT     |        BC01        | InvalidPaymentInformationCount  | The number of payment_information elements should not be more than 1 per request|
| EC004_108  |    RJCT     |        AM10        | InvalidControlSum               | Sum of instructed amounts does not equal the control sum.|
| EC004_109  |    RJCT     |        AM18        | InvalidNumberOfTransactions     | Number of transactions is invalid or missing.|
| EC004_110  |    RJCT     |        TD03        | SchemaValidation                | Echo any parser error message.<br/>I.e.<br/>Property with the name '\<json key\>' already exists in the current JSON object. Path '\<json key\>', line \<#\>, position \<#\>.<br/>Property with the name 'payment_information' already exists in the current JSON object. Path 'payment_information', line 32, position 30.|
| EC004_158  |    RJCT     |        BE16        | InvalidDebtorIdentificationCode      | Where:<br/>Payment Type is CBFT<br/>Do a check on debtor_account_identification to determine if it's AU domestic (CACHE) or FX (MIDANZ) <br/>MIDANZ pattern: [0-9]{6}[A-Z]{3}[0-9]{5}  (i.e 123456USD00001) <br/> Cache pattern: [0-9]{15}  (i.e 012123999999999) <br/>Error Message:<br/>Invalid Debtor Identification Code|
| EC004_159  |    RJCT     |        AM10        | InvalidControlSum         | Where:<br/>Payment Type is CBFT<br/>Sum of amounts(instructed and equivalent) does not equal the control sum. <br/>Error Message:<br/>Invalid Control Sum|
| EC004_201  |    RJCT     |        AC02        | InvalidDebtorAccountNumber      | Where:<br/>{max_account_length} = Integer. Maximum length allowed for account number for country/ payment type<br/>Error Message:<br/>Debtor Account Number format is invalid for country and payment type. Value exceeds maximum length of {max_account_length} (supplied value: \[{debtor_account_identification}\])|
| EC004_202  |    RJCT     |        TC01        | InvalidTransactionCount         | The number of credit_transfer_transaction_information elements should not be more than 1000 per payment_information element|
| EC004_203  |    RJCT     |        AM03        | NotAllowedCurrency              | Where:<br/>{currency} = List of values provided against instructed_amount.currency<br/>Error Message:<br/>Payment type only allows for single currency in batch. Provided currencies: \[{currency}\]|
| EC004_204  |    RJCT     |        DU02        | DuplicatePaymentInformationID   | Payment Information ID must be unique per payment (supplied value: \[{payment_information_identification}\])|
| EC004_205  |    RJCT     |        CH16        | ElementContentFormallyIncorrect | Where:<br/>{max_length} = Maximum allowed length for payment type<br/>Error Message:<br/>Payment Information ID exceeds maximum allowed length for country and payment type. Value exceeds maximum length of {max_length} (supplied value: \[{payment_information_identification}\])|
| EC004_301  |    RJCT     |        AC03        | CreditorAccountRule             | creditor_account_proxy is invalid for CountryCode: \[{countryCode}\] and PaymentType: \[{paymentType}\]|
| EC004_302  |    RJCT     |        AM03        | NotAllowedCurrency              | Where:<br/>{allowed currencies} = an array of currency codes valid for the country/ payment type<br/>{currency} = value of instructed_amount.currency<br/>Error Message:<br/>"Invalid currency for payment type. Instructed amount currency must be one of \[{allowed currencies}\] (supplied value: \\[{currency}\\])"|
| EC004_303  |    RJCT     |        DU05        | DuplicateInstructionID          | Instruction ID must be unique within a batch (supplied value: \[{instruction_identification}\])|
| EC004_304  |    RJCT     |        AC03        | InvalidCreditorAccountNumber    | Either creditor_account_identification or creditor_account_proxy may be present, but not both|
| EC004_305  |    RJCT     |        CH16        | ElementContentFormallyIncorrect | Where:<br/>{max_length} = Maximum allowed length for payment type<br/>Error Message:<br/>Instruction Identification exceeds maximum allowed length for country and payment type. Value exceeds maximum length of {max_length} (supplied value: \[{instruction_identification}\])|
| EC004_306  |    RJCT     |        BE22        | MissingCreditorName    | Where:<br/>{creditor_name} = not present<br/>Error Message:<br/>Creditor name is missing|
| EC004_307  |    RJCT     |        MS06        | MissingAmount | Where:<br/>PaymentType is CBFT and {instructed_amount} = Not present<br/>Or <br/>{equivalent_amount} = Not present<br/> Error Message:<br/>Amount is missing|
| EC004_308  |    RJCT     |        BE19        | InvalidChargeBearerCode | Where:<br/>PaymentType is CBFT and {charge_bearer} = Not present <br/> Error Message:<br/>Invalid Charge Bearer Code|

---

[Return to Top](#top)

[NPP event codes](#npp) 

<h4 name="npp" id="npp"></h4>
<a name="npp"></a>

### NPP Event Codes

Below event codes are used to indicate Payment validation failures. The codes and status are returned in a Payment Status response message

| Event Code | transaction_<br>status | transaction_status_<br>reason_code | transaction_status_<br>description     | Description                                                                                          |
| :--------- | :--------------------: | :--------------------------------: | :------------------------------------- | :--------------------------------------------------------------------------------------------------- |
| EC004_001  |          RJCT          |                TD03                | EC004_001-InvalidPayment               | Schema validation failed against the payment schema, error details [Missing or invalid X-Message-Id] |
| EC004_002  |          RJCT          |                TD03                | EC004_002-DuplicatePayment             | Duplicate payment received (supplied X-Message-Id value: [X-Message-Id]                              |
| EC004_003  |          RJCT          |                TD03                | EC004_003-InvalidPayment               | Schema validation failed against the payment schema, error details [{errorDetail}]                   |
| EC004_004  |          RJCT          |                TD03                | EC004_004-CryptoFailure                | Failed to decrypt and verify the message                                                             |
| EC004_005  |          RJCT          |                TD03                | EC004_005-SchemaValidation             | Schema validation failed against the payment schema, `PaymentSubmissionResource`                     |
| EC004_006  |          RJCT          |                AC03                | EC004_006-CreditorAccountRule          | /CreditorAliasValue or /CreditorAccountIdentification must be present                                |
| EC004_007  |          RJCT          |                AC03                | EC004_007-CreditorAccountRule          | If /CreditorAccountType is present then /CreditorAccountIdentification must be present               |
| EC004_008  |          RJCT          |                AC03                | EC004_008-CreditorAccountRule          | If /CreditorAliasType is present then /CreditorAliasValue must be present                            |
| EC004_009  |          RJCT          |                AC13                | EC004_009-DebtorAccountRule            | /DebtorAccountType AND /DebtorAccountIdentification must be present                                  |
| EC004_010  |          RJCT          |                DT02                | EC004_010-CreationDateRule             | Creation date and time (UTC) is too far in the past (greater than 24 hours), or is future dated      |
| EC004_011  |          RJCT          |                DT01                | EC004_011-RequestedDateRule            | Requested Execution Date is in the past or invalid                                                   |
| EC004_012  |          RJCT          |                DT01                | EC004_012-RequestedDateRule            | Requested Execution Date is in the future or invalid                                                 |
| EC004_013  |          RJCT          |                AM12                | EC004_013-InstructedAmountRule         | Amount field does not match a two decimal place format.                                              |
| EC004_014  |          RJCT          |                AM06                | EC004_014-TooLowAmount                 | Instructed amount must be equal or greater than `$0.01`                                              |
| EC004_015  |          RJCT          |                AM03                | EC004_015-CurrencyRule                 | Instructed amount must be in `AUD`                                                                   |
| EC004_016  |          RJCT          |                AC02                | EC004_016-InvalidDebtorAccountNumber   | Account numbers for NPP can only contain numeric values                                              |
| EC004_017  |          RJCT          |                AC08                | EC004_017-InvalidBranchCode            | Debtor BSB must be a minimum of 6 numeric digits, including leading zeroes                           |
| EC004_018  |          RJCT          |                AC03                | EC004_018-InvalidCreditorAccountNumber | Account numbers for NPP can only contain numeric values                                              |
| EC004_019  |          RJCT          |                AC08                | EC004_019-InvalidBranchCode            | Creditor BSB must be a minimum of 6 numeric digits, including leading zeroes                         |
| EC004_020  |          RJCT          |                AC14                | EC004_020-InvalidCreditorAccountType   | Valid values are: `AIIN` and `BBAN`                                                                  |
| EC004_021  |          RJCT          |                AC13                | EC004_021-InvalidDebtorAccountType     | Valid values are: `AIIN` and `BBAN`                                                                  |
| EC004_022  |          RJCT          |                AC13                | EC004_022-InvalidEndToEndId            | EndToEnd Identification is missing or invalid                                                        |
| EC004_023  |          RJCT          |                FF04                | EC004_023-InvalidServiceLevelCode      | Service Level must be `npp.clear.01-x2p1`                                                            |
| EC004_024  |          RJCT          |                DT02                | EC004_024-InvalidCreationDate          | Creation date must be of ISODateTime format (UTC Expressed: YYYY-MM-DDThh:mm:ss.sssZ)                |
| EC004_026  |          RJCT          |                DT02                | EC004_026-PaymentProcessingFailed      | Payment processing failed, please re-submit and try again                                            |
| EC004_027  |          RJCT          |                DT02                | EC004_027-InvalidAlias                 | Alias value is invalid as per Alias Type.                                                            |



---

[Return to Top](#top)

<a name="access"></a>


[How do I access fileactive APIs?](#accessfileactive) 

<h4 name="accessfileactive" id="accessfileactive"></h4>

#### How do I access Fileactive APIs? 
Contact your ANZ Account Manager to discuss requirements and arrange for access. A technical consultant will be assigned to provide advice and assitance throughout the process.

---



<a name="throttle"></a>

[Are fileactive APIs subject to rate limits or throttling?](#ratelimits) 

<h4 name="ratelimits" id="ratelimits"></h4>

#### Are Fileactive APIs subject to rate limits or throttling?

By default the following rate limits are applied:   

|            Type             | TPH (Transactions Per Hour) | TPM (Transactions Per Minute) | TPS (Transactions Per Second) |
|:----------------------------|:---------------------------:|:-----------------------------:|:-----------------------------:|
| ACMC GraphQL calls          |             10,000          |              n/a              |               5               |
| Authorisation               |             10              |              n/a              |               2               |
| FX RFQ                      |             500             |              n/a              |              10               |
| NPP Single Payment          |             n/a             |              30               |               2               |
| PayTo Change Mandate Status |             n/a             |              n/a              |              10               |
| PayTo Create Mandate        |             n/a             |              n/a              |              10               |
| PayTo Create MPIR           |             n/a             |              n/a              |               5               |
| PayTo Get Mandate Details   |             n/a             |              n/a              |               5               |
| PayTo Query Resolution      |             n/a             |              n/a              |               5               |
| Payments                    |             n/a             |              30               |               2               |
| Payment Enquiry             |             n/a             |              90               |               2               |
| Statement / BTR             |             25              |              n/a              |              n/a              |

_Non-default limits will be considered on request. Please discuss with your ANZ account or relationship manager to request a non-default limit. Temporary limits may also be requested for specific ad hoc use cases._ 

---

<a name="rate"></a>

[Which rate limiting algorithms do you use?](#algorithms) 

<h4 name="algorithms" id="algorithms"></h4>

#### Which rate limiting algorithms do you use?

For most use cases one of two algorithms is implemented for rate limiting:   
           
**Fixed Window**   

- The system uses a window size of n seconds (typically using human-friendly values, such as 60 or 3600 seconds) to track the fixed window algorithm rate. 
- Each incoming request increments the counter for the window. It discards the request if the counter exceeds a threshold. 
- The current timestamp floor typically defines the windows, so 12:00:03, with a 60-second window length, would be in the 12:00:00 window.   
    
**Sliding Window**   

Sliding Window is a hybrid approach. Like the fixed window algorithm, we track a counter for each fixed window. 
Next, we account for a weighted value of the previous window's request rate based on the current timestamp to smooth out bursts of traffic.    
    
**Sliding window example:** 
- Given a limit of 100 transaction per hour.
- **Window 1 (13:00 - 14:00)** 
  - Between 13:00 - 14:00, 80 requests are received. This is within the 100 tph limit so all are allowed.
- **Window 2 (14:00 - 15:00)** 
  - By **14:15**, 20 requests are received. This is 25% (15 minutes) in to window 2, so weighted average would include 75% from the previous window.    
    Request rate: *20 (all requests within window 2) + 60 (75% of requests from window 1) = 80 requests*.    
    Request rate is still within the 100 tph maximum.
  - By **14:30**, 75 requests have been received. This is 50% (30 minutes) in to window 2, so weighted average would include 50% from the previous window.    
    Request rate is: *75 (all requests within window 2) + 40 (50% weighted average from previous window) = 115 requests*.    
    This exceeds the 100 tph limit so further requests would return an HTTP `429` (Too Many Requests) status code until the weighted request rate is below the agreed limit.
  - By **14:45**, no further requests have been made. This is 75% (45 minutes) through window 2.   
    Request rate is *75 (current window) + 20 (25% weighted average from previous window) = 95 requests*.    
    As this is below the 100 tph limit further requests will be accepted.

---


[Where are changes to the site and specifications documented?](#spec) 

<h4 name="spec" id="spec"></h4>

<a name="spec"></a>

#### Where are changes to the site and specifications documented?

Significant changes to the site and documentation will be listed in the [Change Log](change-log).

---

[What is OAuth 2.0?](#oauth) 

<h4 name="oauth" id="oauth"></h4>

<a name="oauth"></a>

#### What is OAuth 2.0?

OAuth 2.0 supported APIs are tagged with `OAuth2.0`. Detailed information can be found on the [RFC 6749 OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749) page.   

ANZ's OAuth 2.0 API is used for authentication and authorization and is OpenID Connect compliant, requesting a token involves calling the ANZ token issuer endpoint with a valid `client credential` grant.  ANZ will issue a reference token that can be used for subsequent calls to ANZ for the lifetime of the token.

<aside class="alert alert-primary" role="alert">
A Client Credential Grant is required to obtain an access token.  The customers public key must be pre-exchanged for ANZ to verify the signed Client Credential Grant.
</aside>

---

[What is a client credential grant?](#grant) 

<h4 name="grant" id="grant"></h4>

<a name="grant"></a>

#### What is a Client Credential Grant?

The Client Credential Grant is a messsage based interaction used to obtain a token, called a **Bearer Token**, from ANZ.


The Client Credential Grant is constructed as follows:

| Field  | Value                                                                                                                                                                                           |
|:-------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Header | Content-Type: `application/x-www-form-urlencoded`                                                                                                                                               |
| Header | apikey: `[ANZ issued apikey]`                                                                                                                                                                   |
| Body   | grant_type=`client_credentials`<br />client_assertion_type=`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`<br />scope=`scope1 scope2`<br />client_assertion=`[Customer Signed JWT]`  |

<br />
<aside class="alert alert-primary" role="alert">
The client credential grant includes a customer signed JWT as a `client_assertion`
</aside>



**Example Request**

<h4 style="color: #d73a49; font-size:18px;">POST https://api.fileactive.uat.anzgcis.com/v1.0/auth</h4>

<pre style="background-color: #272822; padding: 10px; border-radius: 5px; width:100%; white-space: pre-wrap; word-wrap: break-word;">
  <code>
<span style="color: #f92672;">curl --request POST \</span><br>
<span style="color: #f92672;">--url</span> <span style="color: #FF746A;">https://api.fileactive.uat.anzgcis.com/v1.0/auth \</span> 
<span style="color: #f92672;">--header</span> <span style="color: #e6db74;">'apikey: [ANZ issued apikey?]' \</span> 
<span style="color: #f92672;">--header</span> <span style="color: #e6db74;">'content-type: application/x-www-form-urlencoded' \</span> 
<span style="color: #f92672;">--data</span> <span style="color: #e6db74;">'grant_type=client_credentials&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&scope=SCOPE1+SCOPE2&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.ewoJInN1YiI6ICJDVVNUS01FUkNPREUiLAogICJleHAiOiAiMTY2MjUzMDkwMiIsCiAgImF1ZCI6ICJodHRwczovL2FwaS5maWxlYWN0aXZlLnVhdC5hbnpnY2lzLmNvbS9hdXRoIgp9.ewWggi_ti3LyCc_X84XbeHDh1GU-J2uVx-vC_jZN2ZnO_CjwrUlAC3LXwEh2DX6IPTeP2jpX1IdWt-IaQlzendnfBYmq7YqxAWKhJiZATNM15YxSqQH67Z3Ic3UscXNMvRPClnfHBuIfalSnBAVOzm-WhQ9gboEpSGJ9-wQB7qN5pBXR4IiWUy6NX2wWLXGdLnQozg_A1nTp0Wwr_xQO4_qcIAUnAxG7SaJ1zlOq_QLMMdvczgHt1_DCTnIYetH5Wy4Y47Jyb0GrzfcTjcIR1z6jS-e4gcMyom6hOO-QH5vWFW3t5hhCaM8la7o8LhEhYzXoXXUYCO7Q7qfMK-vBVg'</span> <br>
  </code>
</pre>



<br />


**Example Response**

**Header:**  


<pre style="background-color: #272822; padding: 10px; border-radius: 5px; width:100%; white-space: pre-wrap; word-wrap: break-word;">
  <code>
  <span style="color: #66d9ef">
HTTP</span> <span style="color: #f92672">/ </span><span style="color: #ae81ff">1.1 200</span> OK
<span style="color: #a6e22e">
X-RequestKey </span>: <span style="color: #e6db74">5c9707f9-0ecf-4543-aa03-7c5b48b441d1</span>
  </code>
</pre>


<br />

**Body:**  
<pre style="background-color: #272822; padding: 10px; border-radius: 5px; width:100%; white-space: pre-wrap; word-wrap: break-word; color: white; ">
  <code>
  {
    <span style="color: white;">"expires_in"</span>: <span style="color: yellow;">3600</span>,
    <span style="color: white;">"token_type"</span>: <span style="color: yellow;">"Bearer"</span>,
    <span style="color: white;">"access_token"</span>: <span style="color: yellow;">"66118dbe-f3a9-8ccd-be7e-06864aaac613"</span>
  }
  </code>
</pre>


<br />
<aside class="alert alert-success" role="alert" >
HTTP: 200
</aside>

| Field  | Name         | Description                                 |
|:-------|:-------------|:--------------------------------------------|
| Header | X-RequestKey | ANZ Request Key                             |
| Body   | expires_in   | The lifetime in seconds of the access token |
| Body   | token_type   | Bearer token type                           |
| Body   | access_token | Token value to be used as Bearer token      |

<br />

<aside class="alert alert-warning" role="alert">
HTTP: 401 Unauthorized
</aside>
If the Client Credential Grant is invalid or is not verified against the Customer Public Key a `401` Unauthorized is returned.

<aside class="alert alert-warning" role="alert">
HTTP: 400 BadRequest
</aside>

If required fields are not provided or if auth request is invalid a `400` Bad Request is returned.

---



<a name="jwt"></a>

[What is a JWT?](#jwttoken) 

<h4 name="jwttoken" id="jwttoken"></h4>

#### What is a JWT?

 A [JSON Web Token?](https://jwt.io) or JWT, pronouced jot is an internet standard RFC 7519 used to transfer claims from a server to a client in a secured and URL-safe means. 
        Clients are then authorised to access claims as specified in the scope specified by the client in the `Client Credential Grant Request`.

---



<a name="valid"></a>

[How to constuct a valid JWT?](#validjwt) 

<h4 name="validjwt" id="validjwt"></h4>

#### How to constuct a valid JWT?

Refer to [jwt.io?](https://jwt.io) for detailed information.   

JWT consists of three parts:
* Header
* Payload
* Signature

The three parts are encoded using `Base64url Encoding` and concatenated. Each part is seperated using a period `.`   
JWT = header.payload.signature   

**Header**   
JWT Header is only two fields, these fields contain fixed values:

| Field | Name       | Description                                       |  Value  |
|:------|:-----------|:--------------------------------------------------|:-------:|
| alg   | alogorithm | Identifies the algorithm is used in the signature | `RS256` |
| typ   | JWT        | Identifies the token type                         |  `jwt`  |

<br />


**Payload**

| Field | Name       | Description                                                                             | Value                                         | Example                                     |
|:------|:-----------|:----------------------------------------------------------------------------------------|:---------------------------------------------:|:--------------------------------------------|
| sub   | subscriber | ANZ provided Customer Code, ALL CAPS                                                    | PROVIDED VALUE                                | CUSTOMERCODE                                |
| exp   | JWT expiry | Set the time, using UNIX EPOCH, after which the token cannot be accepted for processing | GENERATED EPOCH VALUE                         | 1662530902                                  |
| aud   | audience   | provides an identification of the intended recipient. Token cannot be processed         | `https://api.fileactive.uat.anzgcis.com/auth` | https://api.fileactive.uat.anzgcis.com/auth |

<br />

**Signature**
  
JWT signatures are used to generate a Message Authentication Code (MAC) to verify that the message is correct and true. 
ANZ verifies the signature of a JWT using a `public key` as provided by the **customer**. Customers must generate the signature/MAC value using the corresponding `Private Key`


**Example JWT**

Example JWT with signed and encoded content:
<pre style="background-color: #272822; padding: 10px; border-radius: 5px; width:100%; white-space: pre-wrap; word-wrap: break-word; color: #FF746A; "><code>
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.ewoJInN1YiI6ICJDVVNUT01FUkNPREUiLAogICJleHAiOiAiMTY2MjUzMDkwMiIsCiAgImF1ZCI6ICJodHRwczovL2FwaS5maWxlYWN0aXZlLnVhdC5hbnpnY2lzLmNvbS9hdXRoIgp9.ewWggi_ti3LyCc_X84XbeHDh1GU-J2uVx-vC_jZN2ZnO_CjwrUlAC3LXwEh2DX6IPTeP2jpX1IdWt-IaQlzendnfBYmq7YqxAWKhJiZATNM15YxSqQH67Z3Ic3UscXNMvRPClnfHBuIfalSnBAVOzm-WhQ9gboEpSGJ9-wQB7qN5pBXR4IiWUy6NX2wWLXGdLnQozg_A1nTp0Wwr_xQO4_qcIAUnAxG7SaJ1zlOq_QLMMdvczgHt1_DCTnIYetH5Wy4Y47Jyb0GrzfcTjcIR1z6jS-e4gcMyom6hOO-QH5vWFW3t5hhCaM8la7o8LhEhYzXoXXUYCO7Q7qfMK-vBVg
</pre>
</code>

---




<a name="token"></a>

[What is a bearer token?](#token) 

<h4 name="token" id="token"></h4>


#### What is a Bearer Token?

 Bearer Tokens are generated by and returned to a customer during a Client Credential Interaction.
        Customer must provide a valid JWT with an `exp` field that dates **not more than 60 minutes into the future**.
        Bearer Tokens are GUIDs, 32 character hypenated strings.

 ---



<a name="scope"></a>

[How are scopes used?](#used) 

<h4 name="used" id="used"></h4>

#### How are scopes used?

 A scope is a mechanism in OAuth 2.0 to define what an application can access (such as payments) and whether the access is read or write. An application can request one or more scopes during a credential grant request. 
        The `bearer token` issued will be limited to the scopes granted.
    



<a name="sec"></a>

[How are payloads secured?](#secured) 

<h4 name="secured" id="secured"></h4>

#### How are Payloads secured?



 **JOSE (JWT)**

Payload data is secured using a combination of JSON Web Signature (JWS) & JSON Web Encryption (JWE)

Sequence to create a valid `secured_payload` object

1. Create valid JSON payload
2. Sign JSON object using JWS
3. Encrypt payload using JWE
4. Encapsulate signed and encrypted payload in `secured_payload` object



**JSON Web Signature (JWS)**

| Algorithm | Supported Key Size |
|:----------|:-------------------|
|   RS256   |    2048 or 4096    |

<br />

**JSON Web Encryption (JWE)**

| Algorithm  | Encryption      | Key Size |
|------------|-----------------|----------|
|   RSA-OAEP |   A256CBC-HS512 |   2048   |

<br />


---



[What is X-RequestKey used for?](#signature) 

<h4 name="signature" id="signature"></h4>
<a name="xkey"></a>

#### What is X-RequestKey used for?

ANZ Support requires the `X-RequestKey` value when engaged, the `X-RequestKey` is a GUID assigned to each request sent to ANZ for processing. ANZ applications are developed to retain context and information on the `X-RequestKey` value, providing the `X-RequestKey` will allow ANZ Support to uniquely identify the API call in question.

---

---
layout: detail
title: Payments API code catalogue
menu_key: fileactive-payments 
group: fileactive
hero_key: payments
---

---

The Fileactive Payments API suite enables developers to handle a wide range of payment types across multiple regions, including Australia, Hong Kong, India, Singapore, and Vietnam. With robust support for domestic and international transactions, the APIs ensure secure, efficient, and reliable payment processing, utilizing OAuth 2.0 for authentication and JWT for encryption and signing.

---
[Regional payment capabilities](#capable) 

<h4 name="capable" id="capable"></h4>

#### Regional payment capabilities

- **Australia:**  
  NPP/OSKO Payment: Utilize the NPP API for real-time domestic payments, with instant settlements via the New Payments Platform (NPP). Secure transactions with OAuth 2.0 and JWT to protect data integrity.
  
  Cross Border Payment: Provide regional payment capabilities, allowing customers to process transactions across borders seamlessly and efficiently. Leverage ANZ’s global network to ensure secure and compliant cross-border payments.

- **Hong Kong:**  
  Support for ACH, FPS, RTGS, and CBFT payments allows for versatile payment processing needs, from automated clearing to real-time gross settlements. Each payment type comes with its dedicated status endpoints for tracking.

- **India:**  
  Manage ACH payments securely and efficiently, automating clearing house transactions with integrated status checks.

- **Singapore:**  
  The API supports ACH, FAST, RTGS, and CBFT payments, covering a broad spectrum of payment needs from rapid domestic transfers to cross-border fund transfers. Secure authentication and encryption are standard for all transactions.

- **Vietnam:**  
  Handle ACH payments with ease, leveraging secure API endpoints for transaction processing and status retrieval.

---  
[Key features](#feature) 

<h4 name="feature" id="feature"></h4>

#### Key features:

- **Multi-Regional support:** 
A single API suite to manage various payment types across Australia, Hong Kong, India, Singapore, and Vietnam.

- **Secure transactions:** 
All payments are authenticated using OAuth 2.0, and data is protected with JWT signing and encryption.

- **Comprehensive tracking:** 
Each payment type includes endpoints for real-time status tracking, ensuring transparency and control over financial operations.

---
[Technical requirements](#require) 

<h4 name="require" id="require"></h4>

#### Technical requirements:

- **OAuth 2.0 Authentication:** 
Implement secure access control using OAuth 2.0 with signed client assertions.

- **JWT Encryption and signing:** 
Securely transmit payment data with JWT, ensuring both integrity and confidentiality.

- **API rate limits:** 
Be mindful of rate limits and Optimise API usage according to business needs.

Integrate Fileactive APIs into your systems to streamline payment processes, automate transactions, and enhance security across your payment workflows.

This set of diagrams shows the flows for using the Fileactive Payment API. The APIs utilize OAuth for authentication, require payments to be encrypted and signed with JWT keys, and involve sending a signed client assertion.

---
[Common authentication flow](#authflow) 

<h4 name="authflow" id="authflow"></h4>

#### Common authentication flow

<div class="mermaid">
sequenceDiagram
    participant Customer
    participant API Gateway
    participant Fileactive

    Customer->>API Gateway: POST /v1.0/auth (OAuth Client Assertion)
    API Gateway->>Customer: 200 OK (Bearer Token)
    
</div>

---
[Consolidated payment flows](#payment) 

<h4 name="payment" id="payment"></h4>

#### Consolidated payment flows

<div class="mermaid">
sequenceDiagram
    participant Customer
    participant API Gateway
    participant Fileactive

    %% Payment Submission Flow
    Customer->>API Gateway: POST /{region}/v1.0/payment/submit (JWT Signed & Encrypted)
    API Gateway->>Fileactive: Forward Payment Request (JWT)
    Fileactive-->>API Gateway: 201 Created
    API Gateway-->>Customer: 201 Created (Payment Submission Confirmation)

    %% Payment Status Check Flow
    Customer->>API Gateway: GET /{region}/v1.0/payment/{transaction_id}/status
    API Gateway->>Fileactive: Get Payment Status
    Fileactive-->>API Gateway: 200 OK (Payment Status)
    API Gateway-->>Customer: 200 OK (Payment Status)

   
</div>

-----
---
[Regional endpoints overview](#overview) 

<h4 name="overview" id="overview"></h4>

#### Regional endpoints overview:


<table style="border-collapse: collapse; width: 100%;">
  <thead>
    <tr style="background-color: #f2f2f2; border: 1px solid #ddd;">
      <th style="border: 1px solid #ddd; padding: 8px;">Region</th>
      <th style="border: 1px solid #ddd; padding: 8px;">Payment Method</th>
      <th style="border: 1px solid #ddd; padding: 8px;">Endpoint</th>
    </tr>
  </thead>
  <tbody>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Australia</td>
      <td style="border: 1px solid #ddd; padding: 8px;">NPP</td>
      <td style="border: 1px solid #ddd; padding: 8px;">/npp/v1.0/payment/submit</td>
    </tr>
    <tr style="background-color: #f9f9f9; border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Australia</td>
      <td style="border: 1px solid #ddd; padding: 8px;">CBFT</td>
      <td style="border: 1px solid #ddd; padding: 8px;">/payment/au/v1.0/cbft</td>
    </tr>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">India</td>
      <td style="border: 1px solid #ddd; padding: 8px;">ACH</td>
      <td style="border: 1px solid #ddd; padding: 8px;">/payment/in/v1.0/ach</td>
    </tr>
    <tr style="background-color: #f9f9f9; border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Hong Kong</td>
      <td style="border: 1px solid #ddd; padding: 8px;">ACH</td>
      <td style="border: 1px solid #ddd; padding: 8px;">/payment/hk/v1.0/ach</td>
    </tr>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Hong Kong</td>
      <td style="border: 1px solid #ddd; padding: 8px;">FAST</td>
      <td style="border: 1px solid #ddd; padding: 8px;">/payment/hk/v1.0/fast</td>
    </tr>
    <tr style="background-color: #f9f9f9; border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Hong Kong</td>
      <td style="border: 1px solid #ddd; padding: 8px;">RTGS</td>
      <td style="border: 1px solid #ddd; padding: 8px;">/payment/hk/v1.0/rtgs</td>
    </tr>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Hong Kong</td>
      <td style="border: 1px solid #ddd; padding: 8px;">CBFT</td>
      <td style="border: 1px solid #ddd; padding: 8px;">/payment/hk/v1.0/cbft</td>
    </tr>
    <tr style="background-color: #f9f9f9; border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Singapore</td>
      <td style="border: 1px solid #ddd; padding: 8px;">ACH</td>
      <td style="border: 1px solid #ddd; padding: 8px;">/payment/sg/v1.0/ach</td>
    </tr>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Singapore</td>
      <td style="border: 1px solid #ddd; padding: 8px;">FAST</td>
      <td style="border: 1px solid #ddd; padding: 8px;">/payment/sg/v1.0/fast</td>
    </tr>
    <tr style="background-color: #f9f9f9; border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Singapore</td>
      <td style="border: 1px solid #ddd; padding: 8px;">RTGS</td>
      <td style="border: 1px solid #ddd; padding: 8px;">/payment/sg/v1.0/rtgs</td>
    </tr>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Singapore</td>
      <td style="border: 1px solid #ddd; padding: 8px;">CBFT</td>
      <td style="border: 1px solid #ddd; padding: 8px;">/payment/sg/v1.0/cbft</td>
    </tr>
    <tr style="background-color: #f9f9f9; border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Vietnam</td>
      <td style="border: 1px solid #ddd; padding: 8px;">ACH</td>
      <td style="border: 1px solid #ddd; padding: 8px;">/payment/vn/v1.0/ach</td>
    </tr>
  </tbody>
</table>


---
[Key points for developers](#submission) 

<h4 name="submission" id="submission"></h4>

#### Key points for developers:

- **Consistent Flow:** The payment submission and status check flows are consistent across all regions, providing a unified approach to handling various payment types.
  
- **Regional Variations:** Only the endpoint paths change according to the specific country and payment method, ensuring a smooth adaptation to different payment infrastructures.
  
- **Secure Processes:** All requests are secured with JWT encryption and OAuth 2.0 authentication, maintaining high standards of data protection across all transactions.

---

[Need help or have questions](#needhelp) 

<h4 name="needhelp" id="needhelp"></h4>

#### Need help or have questions?

If you have any questions, concerns, or require assistance while using the Fileactive APIs, we’re here to help. For personalized support tailored to your business needs, please reach out to your dedicated relationship management team.

[Your relationship team can assist with](#relationship) 

<h4 name="relationship" id="relationship"></h4>

#### Your relationship team can assist with:

- **Account and API access**: Ensuring your account is set up correctly and that you have the appropriate access to the APIs.
- **API integration**: Guidance on integrating the Fileactive APIs into your systems and workflows.
- **Technical support**: Help troubleshooting issues or understanding API functionality.
- **Business consultation**: Discussing how our APIs can help achieve your business objectives and exploring additional solutions.
- **Further information**: Providing detailed documentation, use case examples, or assisting with any other queries you may have.

By working closely with your relationship team, you can get the most out of our products and services, ensuring a smooth and successful experience.

For immediate help, don’t hesitate to contact your relationship team directly. We’re here to ensure you get the support you need at every step of your journey with Fileactive APIs.

---
layout: code
title: Authentication
menu_key: auth
group: payto
hero_key: payto
payload_spec: "/gcis/api-portal/fileactive/api/payto/data/auth-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
---

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](#flow) 

<h4 name="flow" id="flow"></h4>

#### 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:

<img src="/images/PayTo/PayTo - Step 1.png" alt="PayTo Bilateral End to End Flow" style="width: 100%;">

[Authentication for ANZ fileactive APIs](#auth) 

<h4 name="auth" id="auth"></h4>

#### 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](#keypoints) 

<h4 name="keypoints" id="keypoints"></h4>

#### 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](#authreqfield) 

<h4 name="authreqfield" id="authreqfield"></h4>

#### 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](#examplereq) 

<h4 name="examplereq" id="examplereq"></h4>

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

```http
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](#exampleres) 

<h4 name="exampleres" id="exampleres"></h4>

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

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

---

[Usage notes](#usagenotes) 

<h4 name="usagenotes" id="usagenotes"></h4>

#### 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](#importantnotes) 

<h4 name="importantnotes" id="importantnotes"></h4>

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

---
layout: detail
title: PayTo  mandates
menu_key: fileactive-payto
group: payto
hero_key: payto
permalink: /fileactive/api/payto/mandates/
---

[What is a mandate?](#whatsmandate) 

<h4 name="whatsmandate" id="whatsmandate"></h4>

#### What is a mandate?

In PayTo, a Mandate (or PayTo Agreement) is the core component that defines the terms under which payments are authorised. It is a consent mechanism that allows a business to request payments directly from a customer's bank account according to the agreed terms.

---

[Fileactive PayTo API capabilities for mandates](#capabilities) 

<h4 name="capabilities" id="capabilities"></h4>

#### Fileactive PayTo API capabilities for mandates:

- **Create mandate:** Establish a new PayTo mandate that defines how and when payments can be made.

- **Amend mandate:** Modify the existing mandate details, such as updating payment terms or conditions.

- **Change mandate status:** Manage the status of mandates, including activating, suspending, or cancelling them.

- **Fetch detailed information about mandates on-demand:** Fetch detailed information about mandates for monitoring or compliance purposes.

- **Query resolution:** Handle queries related to mandates, ensuring clarity and support for mandate-related transactions.

---
[Where mandates fit in the PayTo process flow](#wheremandatefits) 

<h4 name="wheremandatefits" id="wheremandatefits"></h4>

#### Where mandates fit in the PayTo process flow:

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

<img src="/images/PayTo/PayTo - Step 2.png" alt="PayTo Bilateral End to End Flow" style="width: 100%;">


---
[Key points for developers](#keyfeatures) 

<h4 name="keyfeatures" id="keyfeatures"></h4>

#### Key points for developers:

- **Mandate creation:** This is a pivotal step where the terms of payment are set up, allowing for clear authorisation and control over transactions.

- **Mandate management:** Once a mandate is created, it can be amended or its status can be changed, providing flexibility to adjust to business needs.

- **Integration tips:** Utilize the API endpoints to automate the creation, management, and retrieval of mandates, ensuring a seamless integration into your payment processes.

- **Webhooks for real-time updates:** Integrate webhook notifications to stay updated on changes to mandates and other related events, keeping your systems aligned with payment activities.

---

---
layout: code_tagged
title: Create mandate
menu_key: create
group: payto
hero_key: payto
payload_spec: "/fileactive/api/payto/data/payto-api.yaml"
filter_tag_groups:
  - Mandate Create
overview_tab: "true"
payload_tab: "true"   
business_rules_tab: "true"
---

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.  

Developers interested in reviewing examples of the different Mandate Create Payload structures possible, to support the various PayTo usecases (such as one-off, adhoc, balloon, usage or fixed payments), can refer to <a href="/product/PayTo API/code?path=Mandates/Mandate%20scenarios">Mandate Scenarios</a>

---
[Where create mandate fits in the PayTo process flow](#wherecreatemandatefits) 

<h4 name="wherecreatemandatefits" id="wherecreatemandatefits"></h4>

#### 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:

<img src="/images/PayTo/PayTo - Step 2.png" alt="PayTo Bilateral End to End Flow" style="width: 100%;">

---
[Capabilities](#capabilities) 

<h4 name="capabilities" id="capabilities"></h4>

#### 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](#techrequirements) 

<h4 name="techrequirements" id="techrequirements"></h4>

#### 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](#keyfeatures) 

<h4 name="keyfeatures" id="keyfeatures"></h4>

#### 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](#exampleworkflow) 

<h4 name="exampleworkflow" id="exampleworkflow"></h4>

#### Example workflow

<div class="mermaid">
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<br>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)
</div>


---



[General rules](#generalrules) 
 
<h4 name="generalrules" id="generalrules"></h4>

#### 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](#validitydate) 
 
<h4 name="validitydate" id="validitydate"></h4>

#### 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](#specificfields) 
 
<h4 name="specificfields" id="specificfields"></h4>

#### 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.
- **UltimatePartyNameRule1**  
  - If in the **Create Mandate** the `creditor_information` block is being populated, then `party_name` and `ultimate_party_name` are required to be populated accurately. Below rules apply:
    - (a) If the initiating party is the ultimate beneficiary of the funds, then the initiating party must be reflected under the `party_name` and `ultimate_party_name`.
    - (b) If the initiating party is initially going to receive the funds, then subsequently onforward those funds to the ultimate beneficiary. Then the initiating party must be reflected under `party_name` and the ultimate beneficiary must be reflected under `ultimate_party_name`.

#### `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.


&nbsp;


<style>
  ol {
    list-style-type: decimal; /* This ensures numbers appear in ordered list */
    padding-left: 20px;
  }

  ul {
    list-style-type: disc; /* This ensures bullet points appear in unordered list */
    padding-left: 20px;
  }

Create

---
layout: code_tagged
title: Amend mandate
menu_key: payto
group: payto
hero_key: payto
payload_spec: "/fileactive/api/payto/data/payto-api.yaml"
filter_tag_groups:
  - Amend Mandate
overview_tab: "true"
payload_tab: "true"
business_rules_tab: "true"
---
The Mandate Amendment service in ANZ Fileactive’s PayTo API allows businesses to modify the parameters of existing PayTo mandates such as changing the frequency or the amount. This operation is essential for maintaining accurate and up-to-date mandate agreements and ensuring that any necessary changes are correctly applied. Some mandate amendments are bilateral and therefore require payer approval (e.g. a change to the amount) whereas others can be applied unilaterally (e.g. a change to the creditor account details).

---

[Where amend fits in the PayTo process flow:](#access) 

<h4 name="access" id="access"></h4>

#### Where amend fits in the PayTo process flow:

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

<img src="/images/PayTo/PayTo - Step 4.png" alt="PayTo Bilateral End to End Flow" style="width: 100%;">


[Capabilities](#capability) 

<h4 name="capability" id="capability"></h4>

#### Capabilities

- **Amend existing mandates:** Modify existing mandates to update payment terms, amounts, or other mandate details as required.
- **Unilateral and bilateral amendments:** The system determines if an amendment should be applied unilaterally (immediate effect) or bilaterally (requires payer approval), based on the specific fields being amended.
- **Pending amendments management:** For bilateral amendments, the amendment remains pending until it is either completed, declined by the payer, recalled by the biller, or expires. Only one bilateral amendment can be pending per mandate at any time. Payment is still able to be initiated under the original PayTo amendment terms whilst a mandate amendment is pending.

---

[Technical requirements](#requirements) 

<h4 name="requirements" id="requirements"></h4>


#### Technical requirements

- **API Endpoint:** `/payto/v1/mandates/{mandateId}`
- **Authentication:** OAuth 2.0 with Client Credential Grant flow is required to securely access the API.
- **Request Format:** JSON format for mandate amendment details, including updated terms and authorisation settings.
- **Security:** All amendment requests are protected with OAuth 2.0 bearer tokens, and payloads are encrypted to ensure data integrity and confidentiality.

---

[Key features for developers](#features) 

<h4 name="features" id="features"></h4>

#### Key features for developers

- **Integrity verification:** For unilateral amendments, changes are applied only if they do not compromise the mandate's integrity. For bilateral amendments, integrity checks are performed both when the request is received and upon confirmation of the action.
- **Error handling:** Attempts to amend a mandate requiring bilateral action will fail if there is already a pending amendment. However, unilateral amendments may still proceed under these conditions.
- **Expiration of pending amendments:** Bilateral amendments automatically expire after a set period if not completed, declined, or recalled.
- **Version control:** The mandate version number is incremented only when a bilateral amendment is successfully completed.

---

[Example workflow](#example) 

<h4 name="example" id="example"></h4>

#### Example workflow

<div class="mermaid">
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/amend (Amend Mandate Request)
    ANZ API-->>Customer: Notify Customer for Approval (Bilateral Amendment)
    Customer->>ANZ API: Approve Amendment
    ANZ API-->>Client: 200 OK (Amendment Applied)

    Note right of ANZ API: Amendment pending for bilateral,<br> immediate for unilateral amendments

    Client->>ANZ API: GET /v1.0/payto/mandate/{mandateId} (Check Mandate Status)
    alt Amendment Approved
        ANZ API-->>Client: 200 OK (Mandate Amended Successfully)
    else Amendment Pending
        ANZ API-->>Client: 202 Accepted (Amendment Pending Approval)
    end
</div>

---



[Bilateral amendment rules](#bilateralamendment) 
 
<h4 name="bilateralamendment" id="bilateralamendment"></h4>

#### Bilateral amendment rules

- **ValidityEndDateRule1**: If `validity_end_date` is present, then `automatic_extension_indicator` must be set to `false`.
- **ValidityEndDateRule2**: If `validity_end_date` is cleared by setting value to `1000-01-01`, then `automatic_extension_indicator` **must** be 'true'.
- **BilatClearingRule1**: The following attribute **cannot** be cleared; `automatic_extension_indicator`.
- **BilatClearingRule2**: The following attribute **can** be cleared; `transfer_arrangement` by setting value to `-`.
- **AddInfoRule1**: Where `establishment_scheme` = 'AUPM' then `additional_information` **can** be modified **or** cleared by setting value to `-`.
- **AddInfoRule2**: Where `establishment_scheme` = 'MGCR' then `additional_information` **cannot** be modified **or** cleared.

---

[Unilateral amendment rules](#unilateralamendment) 
 
<h4 name="unilateralamendment" id="unilateralamendment"></h4>

#### Unilateral amendment rules

- **UnilatClearingRule1**: The following attribute **cannot** be cleared; `description`.

---


&nbsp;

Amend

---
layout: code_tagged
title: Recall mandate
menu_key: recall
group: payto
hero_key: payto
permalink: /fileactive/api/payto/mandates/recall/
payload_spec: "/fileactive/api/payto/data/payto-api.yaml"
filter_tag_groups:
  - Recall Mandate
overview_tab: "true"
payload_tab: "true"   
business_rules_tab: "false"
---


The PayTo Recall service in ANZ Fileactive’s PayTo API suite allows a business to manually recall a PayTo agreement/mandate that was created or amended but hasn't yet been actioned by the payer. 

This can be used if the biller wants to prevent authorisation beyond a certain timeframe (for example when holding goods at an online checkout) or an incorrect agreement or amendment to an agreement was issued.

When the mandate has been successfully recalled, the biller will be notified by the <a href="/product/PayTo API/code?path=Webhook/Mandate notification">Mandate Notification</a>.

Should a biller wish to cancel a mandate that has already been authorised by a payer, this can be done using the <a href="/product/PayTo API/code?path=Mandates/Status change">Mandate Status Change API</a>. 

---

[Capabilities](#capability) 

<h4 name="capability" id="capability"></h4>


#### Capabilities

- **Manual Recall:** Allows billers to manually recall PayTo mandates create and amendment requests that haven’t been actioned by the payer.
- **Enforce time-out requirements:** Enables billers to withdraw the ability for a Payer customer to authorise either a Mandate create post a desired timeframe.
- **Notification:** Provides detailed notifications to billers upon successful recall of a mandate.

---

Recall

---
layout: code_tagged
title: Change the Status of a mandate
menu_key: status
group: payto
hero_key: payto
permalink: /fileactive/api/payto/mandates/status/
payload_spec: "/fileactive/api/payto/data/payto-api.yaml"
filter_tag_groups:
  - Change Mandate Status
overview_tab: "true"
payload_tab: "true"   
business_rules_tab: "true"
---

The PayTo Status Change service in ANZ Fileactive's PayTo API allows businesses to update the status of existing mandates. This feature is critical for managing the lifecycle of payment mandates, including activating, pausing, or canceling mandates as per business requirements or customer requests.

---

[Where status change fits in the PayTo process flow](#mandatestatusflow) 

<h4 name="mandatestatusflow" id="mandatestatusflow"></h4>

#### Where status change fits in the PayTo process flow:

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

<img src="/images/PayTo/PayTo - Step 4.png" alt="PayTo Bilateral End to End Flow" style="width: 100%;">

---

[Capabilities](#capabilities) 

<h4 name="capabilities" id="capabilities"></h4>


#### Capabilities

- **Operation:** The purpose of this operation is for a biller to change the status of a mandate. A status change is always performed as unilateral operation meaning the payer customer does not have to subsequently authorise the change.
- **Lifecycle management:** The status can only be changed when the mandate status is currently ACTIVE or SUSPENDED. Options for changing the status of a mandate are (noting SUSPENDED can also be interchangeably referred to as PAUSED):
   - Moving from ACTIVE to SUSPENDED
   - Moving from ACTIVE to CANCELLED
   - Moving from SUSPENDED to ACTIVE
   - Moving from SUSPENDED to CANCELLED
- **Resuming a suspended mandate** can only be done by the party that suspended the mandate in the first place.
- **Amend/Porting Scenarios**  A status change is able to be applied even if there is a pending amendment to a mandate or mandate porting is in process. 
- **Real-time updates:** Status changes are processed and reflected immediately, allowing for quick adjustments to mandates, please note :s    
    - Any notification triggered by this operation will have priority UNATTENDED.
    - The initial API response indicates if ANZ has accepted or rejected the request, not the processing outcome of the request.
    - The processing outcome of the request will be delivered via the [Webhook API - Mandate Processing Outcomes](../../../payto/webhook/mandate/outcome)


---

[Technical requirements](#techrequiremenst) 

<h4 name="techrequiremenst" id="techrequiremenst"></h4>

#### Technical Requirements

- **API Endpoint:** `/v1.0/payto/mandates/{mandateId}/status`
- **Authentication:** OAuth 2.0 with Client Credential Grant flow for secure access to the API.
- **Request format:** JSON format specifying the mandate ID and the desired new status.
- **Security:** Status change requests are protected with OAuth 2.0 bearer tokens, and payloads are encrypted to maintain data security.

---

[Key features for developers](#keyfeatures) 

<h4 name="keyfeatures" id="keyfeatures"></h4>

#### Key features for developers

- **Immediate status application:** Status changes are applied in real-time, enabling immediate control over mandate behavior.
- **Error handling:** The API ensures robust error handling for invalid status transitions or unauthorised requests.
- **Notifications:** Optional notifications can be configured to inform stakeholders about status changes.

---

[Example workflow](#example) 

<h4 name="example" id="example"></h4>

#### Example workflow

<div class="mermaid">
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/status/change (Status Change Request)
    ANZ API-->>Customer: Notify Customer (if required)
    Customer->>ANZ API: Acknowledge Status Change (if required)
    ANZ API-->>Client: 200 OK (Status Changed)

    Note right of ANZ API: Status changes are immediate<br>or require acknowledgment

    Client->>ANZ API: GET /v1.0/payto/mandate/{mandateId} (Check Mandate Status)
    alt Status Changed
        ANZ API-->>Client: 200 OK (Status Updated Successfully)
    else Status Pending
        ANZ API-->>Client: 202 Accepted (Status Change Pending)
    end
</div>

---

[Usage notes](#notes) 

<h4 name="notes" id="notes"></h4>

#### Usage notes

- **Status transitions:** Common status transitions include activation, pausing, and cancellation. Each transition must comply with predefined rules to ensure mandate integrity.
- **Notifications:** Depending on configuration, status changes can trigger notifications to customers or stakeholders.
- **Version control:** Changes to the status do not affect the mandate version number but are recorded in the mandate's history for audit purposes.

---



[General rules](#generalrules) 
 
<h4 name="generalrules" id="generalrules"></h4>

#### General Rules

- **ChangeAndReasonCodeRule1**:  
  - When `change` is equal to `'CNCL'` (Cancel) or `'SUSP'` (Suspend), then `reason_code` must be present.

Status change

---
layout: code_tagged
title: Mandate list
menu_key: List
group: payto
hero_key: payto
payload_spec: "/fileactive/api/payto/data/payto-api.yaml"
filter_tag_groups:
  - Mandate List
overview_tab: "true"
payload_tab: "true"   
business_rules_tab: "false"
---


The PayTo Mandate List service in ANZ Fileactive’s PayTo API suite is designed to fetch a list of mandates based on either the payer’s PayID or account details, with an optional additional filter for mandate status (Active, Suspended, Cancelled).

This API can return either a high-level summary of mandate information or a comprehensive list of all mandate attributes. It supports pagination to efficiently handle large datasets.

This API is useful where a biller may have multiple agreements with the same customer for different services provided (i.e. a separate agreement for a mobile phone bill and then another for internet) or where a biller only offers once-off agreements and are wanting to see the history of interactions with a particular customer.
---

[Capabilities](#capabilities) 

<h4 name="capabilities" id="capabilities"></h4>

#### Capabilities

- **Mandate Retrieval:** Fetch a list of mandates corresponding to a specific PayID or BSB and Account Number.
- **Status Filtering:** Filter mandates by their status (active, suspended, created (pending), cancelled). Not specifying a status, will bring all status into scope.
- **Detail Levels:** Choose between a summary or comprehensive details response.
- **Pagination:** Efficiently manage large datasets with pagination support.

---

List

---
layout: code_tagged
title: Get the details of a mandate
menu_key: details
group: payto
hero_key: payto
payload_spec: "/fileactive/api/payto/data/payto-api.yaml"
filter_tag_groups:
  - Mandate Details
overview_tab: "true"
payload_tab: "true"
---
The PayTo Details service in ANZ Fileactive's PayTo API allows businesses to retrieve comprehensive information about existing mandates. This service provides key details about mandates, enabling effective management and monitoring of payment agreements between billers and payers.

---

[Where mandate details fits in the PayTo process flow:](#mandatedetailsflow) 

<h4 name="mandatedetailsflow" id="mandatedetailsflow"></h4>

#### Where mandate details fits in the PayTo process flow:

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

<img src="/images/PayTo/PayTo - Step 5.png" alt="PayTo Bilateral End to End Flow" style="width: 100%;">

---

[Capabilities](#capabilities) 

<h4 name="capabilities" id="capabilities"></h4>

#### Capabilities

- **Retrieve mandate information:** Access detailed information about individual mandates, including status, parties involved, and mandate terms.
- **Comprehensive data:** Fetches all relevant mandate data, ensuring that businesses have the necessary insights to manage mandates effectively.
- **Support for multiple mandates:** Allows querying of multiple mandates by various parameters, supporting robust mandate management strategies.

---

[Technical requirements](#techrequirements) 

<h4 name="techrequirements" id="techrequirements"></h4>

#### Technical requirements

- **API endpoint:** `/payto/v1/mandates/{mandateId}`
- **Authentication:** OAuth 2.0 with Client Credential Grant flow is required to securely access the API.
- **Request format:** Requests are made in JSON format, specifying mandate identifiers or query parameters.
- **Security:** All requests are authenticated using OAuth 2.0 bearer tokens, and responses are securely transmitted.

---

[Key features for developers](#keyfeatures) 

<h4 name="keyfeatures" id="keyfeatures"></h4>

#### Key features for developers

- **Detailed mandate insights:** Retrieve detailed mandate information, including payer details, payment schedules, and status history.
- **Flexible querying:** Supports querying by mandate ID, status, date range, and other relevant parameters.
- **Error handling:** Provides detailed error codes and messages to assist in troubleshooting request issues.

---

[Example workflow](#exampleworkflow) 

<h4 name="exampleworkflow" id="exampleworkflow"></h4>

#### Example workflow

<div class="mermaid">
sequenceDiagram
    participant Client
    participant ANZ API

    Client->>ANZ API: POST /v1.0/auth (OAuth 2.0 Client Credentials)
    ANZ API-->>Client: 200 OK (Bearer Token)

    Client->>ANZ API: GET /v1.0/payto/mandate/details (Fetch Mandate Details)
    ANZ API-->>Client: 200 OK (Mandate Details JSON)

    Note right of ANZ API: Provides detailed information<br>about the requested mandate
</div>

---

[Usage notes](#usagenotes) 

<h4 name="usagenotes" id="usagenotes"></h4>

#### Usage notes

- **Mandate identification:** Ensure that requests specify accurate mandate IDs or appropriate query parameters to retrieve the desired details.
- **Data utilization:** The returned data can be used for mandate management, customer service inquiries, or integrating with other systems.
- **Response handling:** Be prepared to handle various response statuses, including 200 OK for successful retrievals and error codes for failed requests.

---

Details

---
layout: code_tagged
title: Mandate actions
menu_key: actions
group: payto
hero_key: payto
payload_spec: "/fileactive/api/payto/data/payto-api.yaml"
filter_tag_groups:
  - Mandate Actions
overview_tab: "true"
payload_tab: "true"   
business_rules_tab: "false"
---


The PayTo Mandate Action History service in ANZ Fileactive’s PayTo API suite is designed to fetch a list of actions related to a specific mandate.

This API can return either pending only actions or both pending and completed actions and includes an optional filter for a specific date range. It supports pagination to efficiently handle large datasets.

This API is useful for tracking the history of a recurring mandate with a customer, particularly where amendments have been made such as a change in amount or frequency.

---

[Capabilities](#capabilities) 

<h4 name="capabilities" id="capabilities"></h4>

#### Capabilities

- **Action Retrieval:** Fetch actions for a given mandate.
- **Supported Actions:** Mandate Actions which can be returned are;
  - Create Mandate (Biller)
  - Amend Mandate (Biller & Payer)
  - Change Mandate Status (Biller & Payer)
- **Pending Only Filtering:** Optionally only return actions in a pending status. Not specifying pending only will return both pending and completed actions. Only bilateral create mandate and bilateral amend mandate actions are supported.
- **Date Range:** Optionally choose a from and/or to date when actions were created. Where from date is not provided it will default to mandate creation date. Where to date is not provided it will default to current date.
- **Pagination:** Efficiently manage large datasets with pagination support.
- **Ordering:** The mandate action list will be ordered by descending sequence of mandate action creation timestamp, i.e. most recently created mandate action will be first and the oldest mandate action will be last.
- **Mandate Status:** The mandate status returned is the current mandate status and not the status as per the date of the mandate action.

---

Actions

Mandate scenarios

---
layout: detail
title: PayTo Payment initiation (MPIR)
menu_key: mpir
group: payto
hero_key: payto
---


[What is an MPIR?](#question) 

<h4 name="question" id="question"></h4>

#### What is an MPIR?

A **Mandate Payment Initiation Request (MPIR)** is a request submitted by a business to initiate payments based on an underlying mandate agreement. The mandate outlines the agreement between the payer and the payee, authorizing the payer's bank to process payments on the payer's behalf. 

In the **PayTo** payment ecosystem, MPIRs play a crucial role in automating payment processes. When an MPIR is submitted, it initiates the payment flow as specified by the mandate. MPIRs can be processed as **single transactions** via API or as **bulk transactions** when multiple payments need to be handled together in a file format. 

Key elements of an MPIR include:
- **Mandate Identification:** The unique ID representing the agreement authorizing the payment.
- **Payment Details:** Information such as the amount to be paid, the beneficiary’s details, and the payment schedule.
- **Transaction Status Tracking:** The ability to track the status of each payment, ensuring visibility and control over the payment lifecycle.

For bulk payments, MPIRs are submitted in a file that contains multiple payment instructions, each uniquely identified for processing. This enables businesses to efficiently handle high volumes of payments through a single submission.


---

[Where payment initiation fits in the PayTo process flow](#question1) 

<h4 name="question1" id="question1"></h4>

#### Where Payment initiation fits in the PayTo process flow:

The diagram below illustrates the steps involved in the PayTo process and highlights where Mandate Payment Initiation Request play a critical role:

<img src="/images/PayToStep3.png" alt="PayTo Bilateral End to End Flow" style="width: 100%;">

---

[Capabilities](#capabilities) 

<h4 name="capabilities" id="capabilities"></h4>

#### Capabilities

- **Single and bulk payment submissions:** Supports both single MPIR requests via API and bulk submissions through file uploads for high-volume payment processing.
- **Automated workflows:** Streamlines payment processing through automated initiation and tracking of payment statuses.


---

[Technical requirements](#techrequirements) 

<h4 name="techrequirements" id="techrequirements"></h4>

#### Technical requirements

- **API Endpoint for single MPIR:** `/payto/v1/mpirs` (API-based)
- **Bulk submission via file:** Bulk MPIR requests are processed through file uploads via sFTP, ideal for businesses handling high volumes of payment mandates.
- **Authentication:** Requires OAuth 2.0 with Client Credential Grant flow for secure API access. sFTP file submissions are authenticated via secure keys.
- **Request Format:** Payments are initiated using JSON-formatted requests for single submissions, or a structured file format for bulk submissions,.
- **Security:** Utilizes OAuth 2.0 bearer tokens for API access and secure sFTP communication for bulk file submissions.

---

[Key features for developers](#keyfeatures) 

<h4 name="keyfeatures" id="keyfeatures"></h4>

#### Key features for developers

- **Robust payment creation:** Easily create and submit payment requests with required details, including beneficiary information and payment amount.
- **Bulk processing:** Handle large volumes of MPIRs through bulk file uploads, simplifying high-volume payment initiation.
- **Status tracking:** Retrieve real-time status updates on initiated payments, ensuring visibility and control over the payment lifecycle.
- **Error handling:** Comprehensive error responses and messages help in identifying and resolving issues promptly.

[Example workflow (Single MPIR via API)](#example) 

<h4 name="example" id="example"></h4>

#### Example workflow (Single MPIR via API)

<div class="mermaid">
sequenceDiagram
    participant Client
    participant ANZ API

    Client->>ANZ API: POST /v1.0/auth (OAuth 2.0 Client Credentials)
    ANZ API-->>Client: 200 OK (Bearer Token)

    Client->>ANZ API: POST /payto/v1/mpirs (Initiate Payment, JSON Payload)
    ANZ API-->>Client: 202 Accepted (Payment Request Received)

    Note right of ANZ API: Processes payment and provides<br>status updates upon completion.
</div>

---

[Usage notes](#usagenotes) 

<h4 name="usagenotes" id="usagenotes"></h4>

#### Usage notes

- **Payment details:** Ensure all required payment details are accurately provided in the request payload to avoid processing delays.
- **Monitoring payments:** Utilize the status tracking feature to monitor payment progress and handle any exceptions or rejections promptly.
- **Compliance and security:** Always ensure that the payment information complies with relevant regulations and security standards, using encrypted communication and verified tokens.


[General rules](#generalrules) 
 
<h4 name="generalrules" id="generalrules"></h4>


#### General Rules

- **MPSUserSchemeRule1**:  
  - `mps_user_id` must be the owner of the provided `mandate_identification`.
  
- **InstructedAmountSchemeRule1**:  
  - `instructed_amount` must not exceed the maximum amount specified in the associated mandate (`mandate_identification`).
  
- **CreditorDetailsSchemeRule1**:  
  - `creditor_information` must be present if it is not provided in the mandate.
  
- **CreditorDetailsSchemeRule2**:  
  - `creditor_information` should not be present if already provided on the mandate.
  
- **CreditorDetailsSchemeRule3**:  
  - If `creditor_information` is provided and also available on the mandate, then the details must be exactly the same.

---
layout: code_tagged
title: PayTo Payment initiation (MPIR)
menu_key: mpir
group: payto
hero_key: payto
payload_spec: "/fileactive/api/payto/data/payto-api.yaml"
filter_tag_groups:
  - Create MPIR
overview_tab: "true"
payload_tab: "true"   
business_rules_tab: "true"
---

The Payment Initiation service in ANZ Fileactive APIs enables businesses to create and manage payments efficiently. This service allows the initiation of various types of payments, supporting a seamless and automated payment workflow directly integrated into business processes.

---

[Where payment initiation fits in the PayTo process flow](#paymentinitiation) 

<h4 name="paymentinitiation" id="paymentinitiation"></h4>

#### Where Payment initiation fits in the PayTo process flow:

The diagram below illustrates the steps involved in the PayTo process and highlights where Mandate Payment Initiation Request play a critical role:

<img src="/images/PayTo/PayTo - Step 3.png" alt="PayTo Bilateral End to End Flow" style="width: 100%;">

---

[Capabilities](#Capabilities) 

<h4 name="Capabilities" id="Capabilities"></h4>

#### Capabilities

- **Create payments:** Initiate new payments, including domestic and international transactions, directly from your systems.
- **Flexible payment types:** Supports a range of payment methods, including ACH, RTGS, and FAST payments, tailored to regional requirements.
- **Automated workflows:** Streamlines payment processing through automated initiation and tracking of payment statuses.

---

[Technical requirements](#techrequirement) 

<h4 name="techrequirement" id="techrequirement"></h4>


#### Technical requirements

- **API Endpoint:** `/payto/v1/mpirs`
- **Authentication:** Requires OAuth 2.0 with Client Credential Grant flow for secure access.
- **Request Format:** Payments are initiated using JSON-formatted requests, specifying payment details like beneficiary information, amount, and payment type.
- **Security:** Utilizes OAuth 2.0 bearer tokens for authentication and secure communication.

---

[Key features for developers](#keyfeatures) 

<h4 name="keyfeatures" id="keyfeatures"></h4>

#### Key features for developers

- **Robust payment creation:** Easily create and submit payment requests with required details, including beneficiary information and payment amount.
- **Status tracking:** Retrieve real-time status updates on initiated payments to ensure visibility and control over the payment lifecycle.
- **Error handling:** Comprehensive error responses and messages help in identifying and resolving issues promptly.

[Example workflow](#exmpleworkflow) 

<h4 name="exmpleworkflow" id="exmpleworkflow"></h4>

#### Example workflow

<div class="mermaid">
sequenceDiagram
    participant Client
    participant ANZ API

    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/payment/initiate (Initiate Payment, JSON Payload)
    ANZ API-->>Client: 202 Accepted (Payment Request Received)

    Note right of ANZ API: Processes payment and provides<br>status updates upon completion.
</div>

---

[Usage notes](#usagenotes) 

<h4 name="usagenotes" id="usagenotes"></h4>

#### Usage notes

- **Payment details:** Ensure all required payment details are accurately provided in the request payload to avoid processing delays.
- **Monitoring payments:** Utilize the status tracking feature to monitor payment progress and handle any exceptions or rejections promptly.
- **Compliance and security:** Always ensure that the payment information complies with relevant regulations and security standards, using encrypted communication and verified tokens.



[General rules](#generalrules) 
 
<h4 name="generalrules" id="generalrules"></h4>

#### General Rules

- **MPSUserSchemeRule1**:  
  - `mps_user_id` must be the owner of the provided `mandate_identification`.
  
- **InstructedAmountSchemeRule1**:  
  - `instructed_amount` must not exceed the maximum amount specified in the associated mandate (`mandate_identification`).
  
- **CreditorDetailsSchemeRule1**:  
  - `creditor_information` must be present if it is not provided in the mandate.
  
- **CreditorDetailsSchemeRule2**:  
  - `creditor_information` should not be present if already provided on the mandate.
  
- **CreditorDetailsSchemeRule3**:  
  - If `creditor_information` is provided and also available on the mandate, then the details must be exactly the same.

- **CreditorDetailsSchemeRule4**:  
  - If in the **Create Mandate** the `creditor_information` block is not being populated, then within the **PayTo Payment Initiation (MPIR)** the `party_name` and `ultimate_party_name` are required to be populated accurately. Below rule applies:  
    - (a) If the initiating party is not involved in the settlement at all, then the ultimate beneficiary of the funds needs to be represented under `party_name` and `ultimate_party_name`.

Single request

Bulk request

---
layout: detail
title: Payment refunds
menu_key: fileactive-payto-refunds
group: payto
hero_key: payto
permalink: /fileactive/api/payto/refunds/
---
[Refunds](#Refunds) 
<h4 name="Refunds" id="Refunds"></h4>

#### Refunds

To refund a PayTo payment to the payer, you can initiate a new NPP Payment for the relevant amount via the [NPP / OSKO Payments API](../../payments/au/npp). This allows you to process refunds directly through NPP, ensuring the funds are returned to the payer promptly and securely.

If you are refunding more than one PayTo payment, it is recommended that you initiate a new NPP payment for each PayTo payment rather than making one payment for the aggregated amount.

When initiating a new NPP payment for the purpose of refunding/returning a PayTo payment, we recommended you map the payment submit request as follows : 


| **Field**                                | **Mapping**                                                                                                      | 
|------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| **PaymentSubmissionResourceNPP**.end_to_end_identification | **MPIRCreationRequest**.instruction_details.end_to_end_identification |
| **PaymentSubmissionResourceNPP**.remittance_information_unstructured | `"PayTo Refund"` + `" "` + **MPIRActionOutcome**.clearing_system_reference + `" "` + **MPIRCreationRequest**.instruction_details.mandate_identification |


 **Reference :**

**PaymentSubmissionResourceNPP** = [NPP Payments](../../payments/au/npp) >> Payload >> OpenAPI Spec <br> **MPIRCreationRequest** = [Payment Initiation](../../payto/mpir/single-request#tag/MPIR-Creation-Request) >> Payload >> OpenAPI Spec <br> **MPIRActionOutcome** = [Webhook - MPIR Outcome](../../payto/webhook/mpir/outcome#tag/MPIRActionOutcome) >> Payload >> OpenAPI Spec <br>     

---

---
layout: code_tagged
title: Query resolution
menu_key: query
group: payto
hero_key: payto
payload_spec: "/fileactive/api/payto/data/payto-api.yaml"
filter_tag_groups:
  - PayTo Query
overview_tab: "true"
payload_tab: "true"   
business_rules_tab: "true"
---

A PayTo query is a question or request related to a PayTo Agreement or Payment that is raised with ANZ by the payers Financial Insitution (on behalf of the payer). A PayTo Query has two types:

**1. Mandate Query Case:** a question about a PayTo Agreement or PayTo payment. <br>
**2. Mandate Query Payments:** a request for a refund of a PayTo payment initiated under a mandate (noting this can only ever be for the full amount of the payment, not a partial amount).

The Query Resolution feature in the ANZ Fileactive APIs provides a robust mechanism to handle and resolve queries related to mandates and payment transactions. This functionality is crucial for managing exceptions, disputes, or inquiries that arise during the lifecycle of a mandate or transaction. By using this feature, businesses can ensure smooth and efficient resolution of issues, maintaining the integrity and accuracy of payment processes.

A query will first be notified to a biller via the PayTo Query Webhook. **<a href="/product/PayTo%20API/code?path=Webhook/Query">PayTo Query Webhook</a>**
You must respond to, and action, the query within 2 Business Days of the date of the notification.

---
[Where query fits in the PayTo process flow](#wherequeryfits) 

<h4 name="wherequeryfits" id="wherequeryfits"></h4>

#### Where query fits in the PayTo process flow:

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

<img src="/images/PayTo/PayTo - Step 5.png" alt="PayTo Bilateral End to End Flow" style="width: 100%;">

---
[Capabilities](#capabilities) 

<h4 name="capabilities" id="capabilities"></h4>

#### Capabilities
- **Dispute management:** Efficiently handle disputes or enquiries regarding specific transactions or PayTo Agreements, enabling quick and structured resolution.
- **Exception handling:** Address exceptions that occur during the PayTo Agreement or payment lifecycle, such as mismatches or errors in the transaction process.
- **Integration:** Integrated with PayTo Agreement information to provide you with the relative agreement information specific to the request.

---
[Usage notes](#usagenotes) 

<h4 name="usagenotes" id="usagenotes"></h4>

#### Usage Notes
- If you accept a payment return query, ANZ will debit your account with the amount of the PayTo payment and return the funds to the Payer Customer's Financial Institution.
-  If you've already refunded a transaction related to a mandate payment query, you can reject the query with the reason "already returned."

---
[Technical requirements](#techrequirements) 

<h4 name="techrequirements" id="techrequirements"></h4>

#### Technical requirements
- **Authentication:** All query resolution requests require OAuth 2.0 authentication using bearer tokens. Ensure that your application is correctly authenticated before making requests.
- **Endpoints:** Use the designated query resolution endpoints provided in the API documentation. These endpoints allow you to submit queries, check statuses, and receive updates.
- **Payload format:** Requests should include relevant identifiers and details, such as mandate IDs, transaction references, and specific issues or queries to be resolved.
- **Error handling:** Implement robust error handling to manage common issues like invalid requests, unauthorised access, or processing errors.

---
[Key features for developers](#keyfeatures) 

<h4 name="keyfeatures" id="keyfeatures"></h4>

#### Key features for developers
- **Real-Time feedback:** Receive immediate responses on the status of your query, enabling you to take prompt action as needed.
- **Detailed responses:** Gain insights into the resolution process with detailed response messages, including resolution status and any required follow-up actions.
- **Security:** All interactions are secured with OAuth 2.0 and HTTPS, ensuring that sensitive information is protected throughout the query resolution process.

---
[Example workflow](#exampleworkflow) 

<h4 name="exampleworkflow" id="exampleworkflow"></h4>

#### Example workflow

<div class="mermaid">
sequenceDiagram
    participant Client
    participant ANZ
    participant Customer FI
    participant Customer

    Customer->>Customer FI: Raise Query with FI re: Transaction or Mandate
    Customer FI->>ANZ: Receive Payer Query 

    Note right of Client: Step 1 : Query Notification

    ANZ->>Client: Query Notification via (Webhook: QueryNotification)

    Note right of Client: Step 2 : Outcome Response

    Client->>ANZ: Respond to Query via (API: QueryResolutionRequest)

    ANZ->>Customer FI: Receive Biller Response
    Customer FI->>Customer: Receive Biller Response

</div>


---



[General rules](#generalrules) 
 
<h4 name="generalrules" id="generalrules"></h4>

#### General

- **CaseDecisionSchemeRule1**:  
  - If `case_decision` is equal to 'ACPT', then `reject_reason_code` and `return_transaction_identification` should not be provided.

- **CaseDecisionSchemeRule2**:  
  - If `case_decision` is equal to 'FINO', then `reject_reason_code` and `return_transaction_identification` should not be provided.

- **CaseDecisionSchemeRule3**:  
  - If `case_decision` is equal to 'PEND', then `reject_reason_code` and `return_transaction_identification` should not be provided.

- **CaseDecisionSchemeRule4**:  
  - If `case_decision` is equal to 'RJCT', then `reject_reason_code` must be provided.

- **CaseDecisionSchemeRule5**:  
  - If `case_decision` = **ACPT** then PayTo Query `case_type` **should** be `Mandate Query Payments` or `Mandate Query Payments - Third Party`.
        
- **CaseDecisionSchemeRule6**:  
  - If `case_decision` = **FINO** then PayTo Query `case_type` **should** be `Mandate Query Case`.

- **CaseDecisionSchemeRule7**:  
  - If `case_decision` = **PEND** then PayTo Query `case_type` **should** be `Mandate Query Case` or `Mandate Query Payments` or `Mandate Query Payments - Third Party`.

- **CaseDecisionSchemeRule8**:  
  - If `case_decision` = **RJCT** then PayTo Query `case_type` **should** be `Mandate Query Payments` or `Mandate Query Payments - Third Party`. 

- **RejectReasonSchemeRule1**:  
  - If `reject_reason_code` is equal to 'ARDT', then `return_transaction_identification` must be provided.

- **RejectReasonSchemeRule2**:  
  - If `reject_reason_code` is equal to 'CUST', then `return_transaction_identification` must not be provided.


<style>
  ol {
    list-style-type: decimal; /* This ensures numbers appear in ordered list */
    padding-left: 20px;
  }

  ul {
    list-style-type: disc; /* This ensures bullet points appear in unordered list */
    padding-left: 20px;
  }

Query resolution scenarios

---
layout: code
title: Lump Sum settlement report
menu_key: fileactive-payto
group: payto
hero_key: payto
overview_tab: "true"
---


Mandate Payment Initiation Requests (MPIR) have two options for settlement “itemised” and “lump sum” (LSS).

“Itemised” settlement is where transactions are settled and posted to the nominated account individually in real-time. When LSS is selected, payment confirmation occurs in real-time however all PayTo payments received will then be aggregated and credited to the nominated account as a lump sum credit transaction at pre-determined time. The frequency of a LSS can occur up to three times daily, every calendar day. Only one settlement method can be selected and will apply to all PayTo payments credited to the nominated account.

| Frequency of LSS per day | Time of LSS Aggregation |
|:------------------------:|-------------------------|
|            1             | 00:00 (midnight)        |
|            2             | 00:00 & 11:00           |
|            3             | 00:00, 10:00 & 14:00    |

- All timings are in AEST/AEDT
- Payments will be credited to nominated account once aggregation process has completed
- ANZ may need to change the time of LSS aggregation, you will be notified if this occurs

The balance and transaction report (BTR) will display the lump sum credit transactions with one of the following **narratives**; 
- PayTo *MPS User ID* LSS1*YYYYMMDD* 
- PayTo *MPS User ID* LSS2*YYYYMMDD* 
- PayTo *MPS User ID* LSS3*YYYYMMDD*

Where *YYYYMMDD* is the processing date the lump sum settlement cycle was run; e.g. **PayTo 10002005 LSS120240716**.

---
[Schema](#schema) 

<h4 name="schema" id="schema"></h4>

#### Schema

ISO20022 schema can be viewed here [camt.054.001.11.xsd](../../../../fileactive/file/xsd/camt.054.001.11.xsd)

---

<a name="spec"></a>
#### Specification

The Lump Sum Settlement (LSS) report will be provided in the ISO20022 standard CAMT.054.001.11, this is a XML format. Refer to the separately published ISO20022 Message Implementation Guides applicable to the relevant message for the full message schema, which should be used in conjunction with this document. For further details regarding ISO20022, please visit [ISO20022 Website](https://www.iso20022.org/)


| Index | Name                           | Path & Element                                                                    | Format         | Multiplicity | Description                                                                                                                                                                     |
|:-----:|:-------------------------------|:----------------------------------------------------------------------------------|:---------------|:------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|  1.0  | **Group Header**               | /Document/BkToCstmrDbtCdtNtfctn/GrpHdr                                            | Aggregate      |    [1..1]    | Common information for the message                                                                                                                                              |
|  1.1  | Message Identification         | /Document/BkToCstmrDbtCdtNtfctn/GrpHdr/MsgId                                      | String(35)     |    [1..1]    | Unique reference to identify the message                                                                                                                                        |
|  1.2  | Creation Date Time             | /Document/BkToCstmrDbtCdtNtfctn/GrpHdr/CreDtTm                                    | ISODateTime    |    [1..1]    | Local time with UTC offset format YYYY-MM-DDThh:mm:ss.sss+/-hh:mm                                                                                                               |
|  1.3  | Message Recipient              | /Document/BkToCstmrDbtCdtNtfctn/GrpHdr/MsgRcpt/Id/OrgId/Othr/Id                   | String(35)     |    [1..1]    | MPS User ID                                                                                                                                                                     |
|  2.0  | **Notification**               | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn                                            | Aggregate      |    [1..*]    | Notifies debit and credit entries for the account                                                                                                                               |
|  2.1  | Notification Identification    | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Id                                         | String(35)     |    [1..1]    | Unique identification as assigned by the account servicer, to unambiguously identify the account notification                                                                   |
|  2.2  | Account Identification         | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Acct/Id/Othr/Id                            | String(34)     |    [1..1]    | Identification of the account to which credit entries are made, prefixed with BSB (Bank-State-Branch)                                                                           |
|  2.3  | Scheme Code                    | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Acct/Id/Othr/SchmeNm/Cd                    | CodeSet        |    [1..1]    | Type of account identification<br><br> BBAN - Basic Bank Account Number, account number with BSB (Bank-State-Branch) prefix.                                                    |
|  2.4  | Servicer                       | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Acct/Svcr/FinInstnId/BICFI                 | String(11)     |    [1..1]    | Party that manages the account on behalf of the account owner, represented as a Business Identifier Code (BIC), i.e. ANZBAU3LXXX                                                |
|  3.0  | **Transaction Summary**        | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/TxsSummry                                  | Aggregate      |    [1..1]    | Provides summary information on entries                                                                                                                                         |
|  3.1  | Total Number of Entries        | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/TxsSummry/TtlNtries/NbOfNtries             | Numeric(15)    |    [1..1]    | Total number of entries being reported                                                                                                                                          |
|  3.2  | Total Sum of Entries           | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/TxsSummry/TtlNtries/Sum                    | Decimal(18,17) |    [1..1]    | Total value of entries being reported                                                                                                                                           |
|  3.3  | Total Number of Credit Entries | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/TxsSummry/TtlCdtNtries/NbOfNtries          | Numeric(15)    |    [1..1]    | Total number of credit entries being reported                                                                                                                                   |
|  3.4  | Total Sum of Credit Entries    | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/TxsSummry/TtlCdtNtries/Sum                 | Decimal(18,17) |    [1..1]    | Total value of credit entries being reported                                                                                                                                    |
|  3.5  | Total Number of Debit Entries  | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/TxsSummry/TtlDbtNtries/NbOfNtries          | Numeric(15)    |    [1..1]    | Total number of debit entries being reported                                                                                                                                    |
|  3.6  | Total Sum of Debit Entries     | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/TxsSummry/TtlDbtNtries/Sum                 | Decimal(18,17) |    [1..1]    | Total value of debit entries being reported                                                                                                                                     |
|  4.0  | **Entry**                      | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry                                       | Aggregate      |    [1..*]    | Specifies an entry in the debit credit notification                                                                                                                             |
|  4.1  | Entry Reference                | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/NtryRef                               | String(35)     |    [0..1]    | Unique reference for the entry. Will be the Creditor Reference from the mandate, where available                                                                                |
|  4.2  | Amount                         | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/Amt                                   | Decimal(18,5)  |    [1..1]    | Amount of money in the cash entry. Currency Code will be AUD                                                                                                                    |
|  4.3  | CreditDebitIndicator           | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/CdtDbtInd                             | CodeSet        |    [1..1]    | Indicates whether the entry is a credit or a debit entry<br><br> CRDT - Credit                                                                                                  |
|  4.4  | Status                         | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/Sts/Cd                                | CodeSet        |    [1..1]    | Status of an entry on the books of the account servicer<br><br> BOOK - Booked                                                                                                   |
|  4.5  | BookingDate                    | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/BookgDt/Dt                            | ISODate        |    [1..1]    | Date when an entry is posted to an account on the account servicer’s books. Format YYYY-MM-DD                                                                                   |
|  4.6  | ValueDate                      | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/ValDt/Dt                              | ISODate        |    [1..1]    | Date at which assets become available to the account owner in case of a credit entry, or cease to be available to the account owner in case of a debit entry. Format YYYY-MM-DD |
|  5.0  | **Bank Transaction Code**      | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/BkTxCd                                | Aggregate      |    [1..1]    | Set of elements used to fully identify the type of underlying transaction resulting in an entry                                                                                 |
|  5.1  | Domain Code                    | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/BkTxCd/Domn/Cd                        | CodeSet        |    [1..1]    | Specifies the business area of the underlying transaction<br><br> PMNT - Payment                                                                                                |
|  5.2  | Family Code                    | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/BkTxCd/Domn/Fmly/Cd                   | CodeSet        |    [1..1]    | Specifies the family and the sub-family of the bank transaction code, within a specific domain<br><br> RCDT - Received Credit Transfer                                          |
|  5.3  | Sub Family Code                | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/BkTxCd/Domn/Fmly/SubFmlyCd            | CodeSet        |    [1..1]    | Specifies the sub-product family within a specific family<br><br> DMCT - Domestic Credit Transfer                                                                               |
|  6.0  | **Transaction Details**        | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/NtryDtls/TxDtls                       | Aggregate      |    [1..1]    | Provides information on the underlying transaction(s)                                                                                                                           |
|  6.1  | EndToEnd Identification        | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/NtryDtls/TxDtls/Refs/EndToEndId       | String(35)     |    [1..1]    | Unique identification as assigned by the initiating party, to unambiguously identify the transaction                                                                            |
|  6.2  | Instruction Identification     | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/NtryDtls/TxDtls/Refs/InstrId          | String(35)     |    [1..1]    | Unique identification as assigned by ANZ for an instructed party to unambiguously identify the instruction                                                                      |
|  6.3  | Transaction Identification     | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/NtryDtls/TxDtls/Refs/TxId             | String(35)     |    [1..1]    | Unique reference, as assigned by a clearing system, to unambiguously identify the instruction                                                                                   |
|  6.4  | Mandate Identification         | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/NtryDtls/TxDtls/Refs/MndtId           | String(35)     |    [1..1]    | Unique identification as assigned by the MMS, to unambiguously identify the mandate.                                                                                            |
|  6.5  | Debtor Name                    | /Document/BkToCstmrDbtCdtNtfctn/Ntfctn/Ntry/NtryDtls/TxDtls/RltdPties/Dbtr/Pty/Nm | String(140)    |    [0..1]    | Party that owes an amount of money to the (ultimate) creditor                                                                                                                   |



[Sample](#sample) 

<h4 name="sample" id="sample"></h4>

#### Sample

```xml
<?xml version="1.0"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.054.001.11" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <BkToCstmrDbtCdtNtfctn>
    <GrpHdr>
      <MsgId>10002005 LSS120240716</MsgId>
      <CreDtTm>2024-07-16T04:05:00.000+10:00</CreDtTm>
      <MsgRcpt>
        <Id>
          <OrgId>
            <Othr>
              <Id>10002005</Id>
            </Othr>
          </OrgId>
        </Id>
      </MsgRcpt>
    </GrpHdr>
    <Ntfctn>
      <Id>10002005 LSS120240716</Id>
      <Acct>
        <Id>
          <Othr>
            <Id>014650108109622</Id>
            <SchmeNm>
              <Cd>BBAN</Cd>
            </SchmeNm>
          </Othr>
        </Id>
        <Svcr>
          <FinInstnId>
            <BICFI>ANZBAU3LXXX</BICFI>
          </FinInstnId>
        </Svcr>
      </Acct>
      <TxsSummry>
        <TtlNtries>
          <NbOfNtries>2</NbOfNtries>
          <Sum>100.02</Sum>
        </TtlNtries>
        <TtlCdtNtries>
          <NbOfNtries>2</NbOfNtries>
          <Sum>100.02</Sum>
        </TtlCdtNtries>
        <TtlDbtNtries>
          <NbOfNtries>0</NbOfNtries>
          <Sum>0</Sum>
        </TtlDbtNtries>
      </TxsSummry>
      <Ntry>
        <NtryRef>Credit Ref1</NtryRef>
        <Amt Ccy="AUD">100.01</Amt>
        <CdtDbtInd>CRDT</CdtDbtInd>
        <Sts>
          <Cd>BOOK</Cd>
        </Sts>
        <BookgDt>
          <Dt>2024-07-16</Dt>
        </BookgDt>
        <ValDt>
          <Dt>2024-07-16</Dt>
        </ValDt>
        <BkTxCd>
          <Domn>
            <Cd>PMNT</Cd>
            <Fmly>
              <Cd>RCDT</Cd>
              <SubFmlyCd>DMCT</SubFmlyCd>
            </Fmly>
          </Domn>
        </BkTxCd>
        <NtryDtls>
          <TxDtls>
            <Refs>
              <InstrId>ANZBAU3LXXXI20240716MP0000000448380</InstrId>
              <EndToEndId>4u9eML38Fd167UGyDNC1xkD3z690HHDcLbr</EndToEndId>
              <TxId>NATAAU33XXXN20240716000516437854710</TxId>
              <MndtId>1f61cd30f00511ee959ddeac42859dea</MndtId>
            </Refs>
            <RltdPties>
              <Dbtr>
                <Pty>
                  <Nm>Rocky</Nm>
                </Pty>
              </Dbtr>
            </RltdPties>
          </TxDtls>
        </NtryDtls>
      </Ntry>
      <Ntry>
        <Amt Ccy="AUD">0.01</Amt>
        <CdtDbtInd>CRDT</CdtDbtInd>
        <Sts>
          <Cd>BOOK</Cd>
        </Sts>
        <BookgDt>
          <Dt>2024-07-16</Dt>
        </BookgDt>
        <ValDt>
          <Dt>2024-07-16</Dt>
        </ValDt>
        <BkTxCd>
          <Domn>
            <Cd>PMNT</Cd>
            <Fmly>
              <Cd>RCDT</Cd>
              <SubFmlyCd>DMCT</SubFmlyCd>
            </Fmly>
          </Domn>
        </BkTxCd>
        <NtryDtls>
          <TxDtls>
            <Refs>
              <InstrId>ANZBAU3LXXXI20240716MP0000000448390</InstrId>
              <EndToEndId>oPz39lQdK8jU4pOOL32oSkZM0V5nuOqnIb3</EndToEndId>
              <TxId>NATAAU33XXXN20240716000517216850870</TxId>
              <MndtId>1f61cd30f00511ee959ddeac42859dea</MndtId>
            </Refs>
            <RltdPties>
              <Dbtr>
                <Pty>
                  <Nm>Rocky</Nm>
                </Pty>
              </Dbtr>
            </RltdPties>
          </TxDtls>
        </NtryDtls>
      </Ntry>
    </Ntfctn>
  </BkToCstmrDbtCdtNtfctn>
</Document>
```

<a name="xsd"></a>

---
layout: detail
title: PayTo API webhook 
menu_key: "fileactive-payto-webhook"
group: payto
hero_key: payto
overview_tab: "true"
---

[PayTo Webhooks: Real-Time notifications for seamless integration](#paytowebhooks) 

<h4 name="paytowebhooks" id="paytowebhooks"></h4>

#### PayTo Webhooks: Real-Time Notifications for Seamless Integration

PayTo Webhooks provide real-time notifications for key events related to PayTo agreements and payments. This allows your application to stay in sync with the latest changes without the need for polling.

---
[How It works](#howitworks) 

<h4 name="howitworks" id="howitworks"></h4>

#### How It Works:

- **Event-Driven Notifications:** Webhooks notify your application whenever there are specific changes or actions related to mandates and payments. Key events include:

  - **Mandate Creation Notification:** Triggered when a new mandate is created.

  - **Mandate Authorisation Notification:** Triggered when a mandate is authorised by the payer.

  - **Mandate Amendment Notification:** Triggered when the payer initiates a unilateral amendment to debtor details, authorizes (confirms or rejects) a bilateral mandate amendment request initiated by the Biller, or when such a bilateral mandate amendment request expires.

  - **Payment Initiation Notification:** Triggered when an initated payment is completed or pending due to being future-dated or settlement delays.

  - **Mandate Status Change Notification:** Triggered when the status of a mandate is changed (e.g., activated, suspended, or cancelled) unilaterally by the payer.
  
  - **Mandate Query Notification:** Triggered when a query is raised by your Payer customer through their Financial Institution related to a PayTo Agreement or payment.

- **Secure Delivery:** Each notification is delivered as an HTTPS POST request to your configured webhook endpoint, including a JWT signature and JWT payload encrypting to ensure the integrity and authenticity of the payload.

---
[Key steps](#keysteps) 

<h4 name="keysteps" id="keysteps"></h4>

#### Key Steps:

1. **Setup Your Webhook Endpoint:** Configure an endpoint on your server to receive webhook notifications.

2. **Verify Incoming Notifications:** Use the JWT signature included in each notification to verify its authenticity.

3. **Process the Notification:** Update your application state based on the event details in the webhook payload.

4. **Technical Considerations:** Handling of duplicate notifications and handling of notifications arriving out of sequence.

[PayTo webhook notification flow](#paytonotificationflow) 

<h4 name="paytonotificationflow" id="paytonotificationflow"></h4>

#### PayTo Webhook Notification Flow

The diagram below illustrates how PayTo sends specific notifications to your webhook endpoint:

<div class="mermaid">
sequenceDiagram
    participant PayTo API
    participant Webhook Endpoint
    participant Application

    %% Webhook Notification Flow
    PayTo API->>Webhook Endpoint: POST Mandate Creation Notification (JWT Signature)
    Webhook Endpoint->>Application: Process Mandate Creation Notification
    Application-->>Webhook Endpoint: 200 OK (Acknowledgement)

    PayTo API->>Webhook Endpoint: POST Mandate authorisation Notification (JWT Signature)
    Webhook Endpoint->>Application: Process Mandate authorisation Notification
    Application-->>Webhook Endpoint: 200 OK (Acknowledgement)

    PayTo API->>Webhook Endpoint: POST Mandate Amendment Notification (JWT Signature)
    Webhook Endpoint->>Application: Process Mandate Amendment Notification
    Application-->>Webhook Endpoint: 200 OK (Acknowledgement)

    PayTo API->>Webhook Endpoint: POST Payment Initiation Notification (JWT Signature)
    Webhook Endpoint->>Application: Process Payment Initiation Notification
    Application-->>Webhook Endpoint: 200 OK (Acknowledgement)

    PayTo API->>Webhook Endpoint: POST Mandate Status Change Notification (JWT Signature)
    Webhook Endpoint->>Application: Process Mandate Status Change Notification
    Application-->>Webhook Endpoint: 200 OK (Acknowledgement)

    PayTo API->>Webhook Endpoint: POST Mandate Query Notification (JWT Signature)
    Webhook Endpoint->>Application: Process Mandate Query Notification
    Application-->>Webhook Endpoint: 200 OK (Acknowledgement)
</div>

---

test-spec.yaml

---
layout: code_tagged
title: Webhook Mandate outcome
menu_key: "payto-webhook-outcome"
group: payto
hero_key: payto
payload_spec: "/fileactive/api/payto/data/payto-api-webhook.yaml"
filter_tag_groups:
  - Processing Outcomes
testing_spec: "/fileactive/api/payto/data/testing-outcome-api-schema.yaml"
overview_tab: "true"
payload_tab: "true"   
testing_tab: "false"
---
[PayTo API outcome webhook - developer overview](#paytowebhook) 

<h4 name="paytowebhook" id="paytowebhook"></h4>

#### PayTo API Outcome Webhook - Developer Overview

The PayTo Outcome Webhook notifies your system of the processing outcomes following mandate actions initiated by the Biller. It delivers real-time updates on the results of actions such as mandate creation or a change in status, to ensure your systems stay synchronised with the current status. Actions supported are;
1. Create Mandate
2. Amend Mandate
3. Change Mandate Status
4. Recall Mandate Action

---
[Webhook security](#webhooksecuirty) 

<h4 name="webhooksecuirty" id="webhooksecuirty"></h4>

#### Webhook Security

To ensure data authenticity and security, the Outcome Webhook uses signed JWT (JSON Web Token) tokens. You will need to verify the JWT signature to ensure the payload's authenticity. It is crucial that your application validates the token before processing the outcome event.

---
[Endpoints](#endpoints) 

<h4 name="endpoints" id="endpoints"></h4>

#### Endpoints

Your application must expose a publicly accessible HTTPS endpoint to receive these webhook events. This endpoint should handle retries and timeouts effectively, as the webhook system will resend events if delivery fails.

---

[Use cases](#usecases) 

<h4 name="usecases" id="usecases"></h4>

#### Use Cases

1. **Real-Time Notifications**  
   Update internal systems instantly when a PayTo mandate is created, amended or its status is changed.

2. **Error Handling**  
   Proactively manage mandate issues by responding to real-time failure notifications.

---

[Handling webhook events](#handlingwebhookevents) 

<h4 name="handlingwebhookevents" id="handlingwebhookevents"></h4>

#### Handling Webhook Events

Ensure that your system responds to webhook events with a `2xx` status code to acknowledge successful receipt. If your endpoint doesn't respond within a specific timeframe or returns an error status, the webhook delivery will be retried. 

---
[Example workflow](#exampleworkflow) 

<h4 name="exampleworkflow" id="exampleworkflow"></h4>

#### Example Workflow

1. A create/amend request is performed on the mandate.
2. The request is validated and current status of the mandate is sent in the form of Mandate Outcome webhook.
3. Your system informs the customer to authorise the request in their internet banking portal or mobile app.

---
[Error management](#errormanagement) 

<h4 name="errormanagement" id="errormanagement"></h4>

#### Error Management

In case of a validation failure, for reasons as per <a href="/product/PayTo API/code?path=Event codes">PayTo Mandate Event Codes</a>, your system should take corrective action based on the outcome notification and respond appropriately, like retrying the request.

<style>
  ol {
    list-style-type: decimal; /* This ensures numbers appear in ordered list */
    padding-left: 20px;
  }

  ul {
    list-style-type: disc; /* This ensures bullet points appear in unordered list */
    padding-left: 20px;
  }

Mandate outcome

---
layout: code_tagged
title: Webhook - Mandate notification
menu_key: "fileactive-payto-webhook-notifcation"
group: payto
hero_key: payto
permalink: /fileactive/api/payto/webhook/mandate/notification/
payload_spec: "/fileactive/api/payto/data/payto-api-webhook.yaml"
filter_tag_groups:
  - Mandate Notifications
testing_spec: "/fileactive/api/payto/data/testing-notification-api-schema.yaml"
overview_tab: "true"
payload_tab: "true"   
testing_tab: "true"
---

[PayTo API webhook notification - developer overview](#paytowebhook) 

<h4 name="paytowebhook" id="paytowebhook"></h4>

#### PayTo API Webhook Notification - Developer Overview

The PayTo API Webhook Notification provides real-time updates where a Payer has taken an action (or in some cases not taken an action) to a PayTo Mandate. It allows applications to respond instantly to changes in the state of a mandate, ensuring that systems remain up-to-date. Notifications supported are;
1. Bilateral Amend Mandate Resolution (Authorised/Declined)
2. Bilateral Amend Mandate Timeout
3. Bilateral Create Mandate Resolution (Authorised/Declined)
4. Bilateral Create Mandate Timeout
5. Unilateral Amend Mandate
6. Unilateral Change Mandate Status

To simulate webhook notifications and test your integration, you can use the test API. Simply select the **Testing** tab above to trigger a test notification and verify your system's handling of webhook events.


---

[Webhook security](#webhooksecuirty) 

<h4 name="webhooksecuirty" id="webhooksecuirty"></h4>

#### Webhook Security

To maintain data integrity and authenticity, all webhook payloads are signed using JWT (JSON Web Token) tokens. The receiving application must validate the JWT signature to confirm the authenticity of the event data before processing it.

---

[Endpoints](#endpoints) 

<h4 name="endpoints" id="endpoints"></h4>

#### Endpoints

Your application must expose a publicly accessible HTTPS endpoint to receive these webhook events. This endpoint should handle retries and timeouts effectively, as the webhook system will resend events if delivery fails.

---

[Use cases](#usecases) 

<h4 name="usecases" id="usecases"></h4>

#### Use Cases

1. **Real-Time Notifications**  
   Update systems instantly when a PayTo payment is paused or cancelled by the payer and automatically trigger follow-up actions if needed.

2. **Payment Workflow Automation**  
   Automate workflows to trigger payments once notification has been received of Mandate being authorised by the payer.

3. **Proactive Mandate Management**  
   Receive real-time information on any amendments made by the Payer to a PayTo Mandate, such as a changing of account details or a closure of the account.

---
[Handling webhook events](#handlingwebhookevents) 

<h4 name="handlingwebhookevents" id="handlingwebhookevents"></h4>

#### Handling Webhook Events

To ensure successful receipt of webhook events, your system must respond with a `2xx` status code. If the endpoint does not respond within the specified timeframe or returns an error status, the webhook notification will be retried. The endpoint should support deduplication and idempotency to avoid processing duplicate events.

---

[Example workflow](#exampleworkflow) 

<h4 name="exampleworkflow" id="exampleworkflow"></h4>

#### Example Workflow

1. A PayTo mandate is created/amended by the biller.
2. The Mandate Notification Webhook sends a notification once the Payer authorises the request.
3. The Biller updates records and initiates any necessary actions (e.g. notifying the payer or triggering a payment request).

---

[Error management](#errormanagment) 

<h4 name="errormanagment" id="errormanagment"></h4>

#### Error Management

1. Reason codes used for Bilateral Create/Amend Mandate Declined Notifications : <a href="/product/PayTo API/code?path=Event codes">PayTo Mandate Action Decline Codes</a>
2. Reason codes used for Mandate Status Change Notifications : <a href="/product/PayTo API/code?path=Event codes">PayTo Mandate Status Change Codes</a>

---

By integrating the PayTo API Webhook Notification, your application can stay updated with real-time information, enabling immediate responses to changes in mandate or payment statuses, and reducing the need for manual intervention.


<style>
  ol {
    list-style-type: decimal; /* This ensures numbers appear in ordered list */
    padding-left: 20px;
  }

  ul {
    list-style-type: disc; /* This ensures bullet points appear in unordered list */
    padding-left: 20px;
  }

Mandate notification

---
layout: code_tagged
title:  Webhook - MPIR outcome
menu_key: "fileactive-payto-webhook-mpir-outcome"
group: payto
hero_key: payto
payload_spec: "/fileactive/api/payto/data/payto-api-webhook.yaml"
filter_tag_groups:
  - MPIR Outcome
overview_tab: "true"
payload_tab: "true"   
---

[Fileactive payTo API webhook - MPIR outcome developer overview](#fileactive) 

<h4 name="fileactive" id="fileactive"></h4>

#### Fileactive PayTo API Webhook - MPIR Outcome Developer Overview

The **Fileactive PayTo API Webhook MPIR Outcome** notifies your system of the result (outcome) of a PayTo Mandate Payment Initiation Request (MPIR). This webhook ensures that your application is informed of the status of a payment request in real-time, allowing for faster processing and system updates based on the payment's outcome.

---
[Webhook security](#webhooksecuirty) 

<h4 name="webhooksecuirty" id="webhooksecuirty"></h4>

#### Webhook Security

To ensure data integrity and authenticity, all webhook notifications are secured using signed JWT (JSON Web Tokens). Your system must validate the JWT signature and authenticate the token before processing the outcome event.

---

[Endpoints](#endpoints) 

<h4 name="endpoints" id="endpoints"></h4>

#### Endpoints

Your application should expose a public HTTPS endpoint to receive MPIR Outcome webhook events. The endpoint must be capable of handling retries and timeouts, as the webhook system will attempt redelivery in case of failure or non-acknowledgment.

---

[Use cases](#usecases) 

<h4 name="usecases" id="usecases"></h4>

#### Use Cases

1. **Real-time Payment Status Updates:**  
   Receive instant notification of the payment result, whether it’s successful or failed, allowing your system to take appropriate action based on the outcome.

2. **Automated Workflows:**  
   Automatically trigger downstream processes such as updating customer records, sending confirmation emails, or adjusting balances based on the payment outcome.

3. **Error Handling:**  
   Automatically handle failed payment initiations, such as logging the failure, retrying the request, or notifying users of the issue.

 ---  

[Handling webhook events](#handlingwebhookevents) 

<h4 name="handlingwebhookevents" id="handlingwebhookevents"></h4>

#### Handling Webhook Events

When your system receives the webhook event, it should:
- Verify the authenticity of the JWT token.
- Process the payload to extract the MPIR outcome details.
- Respond with a `2xx` HTTP status code to acknowledge the webhook.
- In case of an invalid response, the webhook service will retry the event delivery.

---
[Example workflow](#exampleworkflow) 

<h4 name="exampleworkflow" id="exampleworkflow"></h4>

#### Example Workflow

- A PayTo payment initiation request (MPIR) is submitted.
- The PayTo system processes the payment and generates an outcome (success or failure).
- The Webhook sends the MPIR Outcome event to your application.
- Your system processes the outcome, updating internal records or triggering appropriate workflows (e.g., notifying customers of success or failure).
- The webhook service retries delivery if no acknowledgment (`2xx` HTTP status code) is received.

---
[Error management](#errormanagment) 

<h4 name="errormanagment" id="errormanagment"></h4>

#### Error Management

Reason codes used for failures related to Payment Initiations returned in the MPIR Outcome Webhook : <a href="/product/PayTo API/code?path=Event codes">PayTo MPIR Event Codes</a>
---

[Benefits of integration](#benefitsofintegration) 

<h4 name="benefitsofintegration" id="benefitsofintegration"></h4>

#### Benefits of Integration

- **Real-time insight into payment statuses:**  
   You can adjust business processes immediately, minimizing delays between payment initiation and system updates.
  
- **Improved automation:**  
   Allows you to automate workflows triggered by successful or failed payments, reducing manual intervention and improving operational efficiency.
  
- **Better customer experience:**  
   Enables faster responses to customers, informing them of the status of their payments in real-time.


<style>
  ol {
    list-style-type: decimal; /* This ensures numbers appear in ordered list */
    padding-left: 20px;
  }

  ul {
    list-style-type: disc; /* This ensures bullet points appear in unordered list */
    padding-left: 20px;
  }

MPIR Outcome

---
layout: code_tagged
title: Webhook - query
menu_key: "payto-webhook-query"
group: payto
hero_key: payto
payload_spec: "/fileactive/api/payto/data/payto-api-webhook.yaml"
filter_tag_groups:
  - Query
testing_spec: "/fileactive/api/payto/data/testing-query-api-schema.yaml"
overview_tab: "true"
payload_tab: "true"   
testing_tab: "true"
---

[PayTo API webhook - query notification developer overview](#paytoapiwebhook) 

<h4 name="paytoapiwebhook" id="paytoapiwebhook"></h4>

#### PayTo API Webhook - Query Notification Developer Overview

The PayTo Query Webhook notifies you when a query is raised by your Payer customer through their Financial Institution related to a PayTo Agreement or payment. A PayTo Query has three types:

**1. Mandate Query Case:** a question about a PayTo Agreement or PayTo payment.<br>
**2. Mandate Query Payments:** a request for a refund of a PayTo payment initiated under a mandate (noting this can only ever be for the full amount of the payment, not a partial amount).<br/>
**3. Mandate Query Payments - 3rd Party:** a request for a refund of a payment initiated under a mandate (noting this can only ever be for the full amount of the payment, not a partial amount) where a Biller 3rd party received the funds.

When a query is received by ANZ, we will notify you via the webhook and you must respond to and action the query using the PayTo Query Resolution API **<a href="/product/PayTo%20API/code?path=Query%20resolution">PayTo Query Resolution API</a>** within 2 Business Days of the notification date.

To simulate webhook queries and test your integration, you can use the test API. Simply select the Testing tab above to trigger a test queries and verify your system’s handling of webhook events.

---

[Webhook security](#webhooksecurity) 

<h4 name="webhooksecurity" id="webhooksecurity"></h4>

#### Webhook Security

All webhook notifications are secured using signed JWT (JSON Web Tokens) to ensure the integrity of the payload. Your system will need to verify the JWT signature and validate the token before processing the query event data.

---

[Endpoints](#Endpoints) 

<h4 name="Endpoints" id="Endpoints"></h4>

#### Endpoints

Your application must expose a public HTTPS endpoint to receive Query Webhook events. This endpoint must be configured to handle retries and timeouts, as the webhook system will attempt redelivery in case of failures.

---
[Use cases](#usecases) 

<h4 name="usecases" id="usecases"></h4>

#### Use Cases

1. **Automated Query Management:**  
   When a PayTo query is raised, this webhook can notify your system to automatically process and respond to the query in real-time.

2. **Internal Process Integration:**  
   Use query notifications to trigger internal workflows, such as investigation or escalation to customer support teams.

3. **Customer Notification:**  
   Leverage the Query Webhook to inform customers immediately if a query arises, providing transparency and efficient resolution.

---
[Handling webhook events](#handlingwebhookevents) 

<h4 name="handlingwebhookevents" id="handlingwebhookevents"></h4>


#### Handling Webhook Events

Ensure your system acknowledges the webhook events by responding with a `2xx` HTTP status code. If your endpoint fails to respond within the required timeframe or returns an error, the webhook system will retry the delivery.

---

[Example workflow](#exampleworkflow) 

<h4 name="exampleworkflow" id="exampleworkflow"></h4>

#### Example Workflow

1. A query is raised for a PayTo mandate or payment (e.g., due to an incorrect payment detail or dispute).
2. The PayTo Query Webhook sends a notification to your system.
3. Your system processes the query and may trigger internal workflows, such as notifying customer support or requesting additional details from the customer.
4. Your system resolves the query and provides a response back through the<a href="/product/PayTo%20API/code?path=Query%20resolution">Query Resolution </a> API call.

---

[Error management](#errormanagment) 

<h4 name="errormanagment" id="errormanagment"></h4>

#### Error Management

In the event of webhook failures (e.g., invalid endpoint response), the webhook service will retry delivery until acknowledged. Ensure your system logs failed events and implements error handling to prevent data loss or missed notifications.


<style>
  ol {
    list-style-type: decimal; /* This ensures numbers appear in ordered list */
    padding-left: 20px;
  }

  ul {
    list-style-type: disc; /* This ensures bullet points appear in unordered list */
    padding-left: 20px;
  }

Query

---
layout: detail
title: Pay-To API code catalogue
menu_key: fileactive-payto
group: payto
hero_key: payto
---

The PayTo API offers a modern and efficient way to manage real-time account-to-account payments in Australia, utilizing the capabilities of the New Payments Platform (NPP). Designed for seamless integration into your applications, PayTo allows you to initiate payments directly from your customers' bank accounts with enhanced control and security. This API supports the creation, authorisation, and management of payment agreements, providing a streamlined solution for handling recurring, scheduled, and one-off payments

---
[Key features:](#throttle) 

<h4 name="throttle" id="throttle"></h4>

#### Key Features:

- **Real-Time Payment Processing:** Leverage the power of NPP to process payments instantly, ensuring funds are transferred quickly and efficiently between accounts.

- **Secure Authentication:** Utilize OAuth 2.0 for secure access control and JWT encryption to protect sensitive transaction data, ensuring compliance with industry standards.

- **Flexibility and Control:** Supports various payment types, including one-time payments, scheduled transactions, and recurring payments, giving developers the flexibility to build solutions that meet diverse business needs.

- **Status Tracking and Notifications:** Easily track the status of payment agreements and transactions with dedicated API endpoints, and receive real-time notifications to keep your application in sync with payment events.

---
[Key Points for developers:](#points) 

<h4 name="points" id="points"></h4>

#### Key Points for Developers:

- **Authentication Flow:** Begin by securing access with OAuth 2.0 to authenticate and receive a token, which will be used in subsequent API requests.

- **Agreement Management:** Manage agreements efficiently through creation, authorisation, or amendment endpoints, which are central to setting up payment terms.

- **Payment Initiation:** Use the API to initiate payments directly from the customer's bank account, ensuring that each transaction adheres to the agreed terms.

- **Status Checks:** Utilize the API to check the status of agreements and payments, allowing for real-time tracking and management of transactions.

- **Webhook Integration:** Incorporate webhooks to receive real-time notifications about agreement outcomes and payment statuses, keeping your application updated with the latest transaction information.

- **Integration Tips:** Make use of the APIs endpoints to seamlessly integrate PayTo into your payment processes, enhancing the overall efficiency and control over your financial operations.

---

[PayID alias processing:](#mermai) 

<h4 name="mermai" id="mermai"></h4>

#### PayID Alias Processing

PayIDs allow businesses and consumers to set an alias in place of their BSB and Account Numbers. This aliases can be a telephone number, an email address, an Australian Business Number (ABN) or and Organisation ID.  

When establishing a PayTo agreement, customers are able to utilise a PayID in place of their BSB and Account Number to identify the bank account where they want funds to be debited from.  

The below table provides formatting guidelines for the permitted types of PayIDs.  

**Alias Information**

| Alias Identifier Type | Example | Description |
|----------------------|---------|-------------|
| TELI - TELEPHONE NUMBER | +61-397656547 (landline) or +61-423765879 (mobile) or +61-131234 (professional) | Must consist of a "+" followed by the country code (from 1 to 3 characters) then a "-" and finally, any combination of numbers (up to 30 characters). Participants should use the country code from the list of ITU-T Recommendation E.164 Assigned Country Codes. NPPA will communicate any changes. |
| EMAL - EMAIL ADDRESS | npp@mail.com | Consists of a character string with a maximum length of 256 characters in lower case. This must include the "@" symbol with leading and trailing characters and no white spaces. |
| AUBN - AUSTRALIAN BUSINESS NUMBER | 601428737 | Consists of a nine to eleven digit number where the first two digits are a checksum. An ABN is assigned by the Australian Taxation Office to identify an individual Australian Business. An ACN, ARBN or ARSN is allocated by ASIC. |
| ORGN - ORGANISATION ID | aardvark plumbing mosman nsw tru blu loyalty program | The Identifier must include the company/organisation name and both/either the description of the business/trade/product/campaign and/or geographic location (suburb/town/state). Maximum of 256 characters in lower case, to be drawn from Printable ASCII (decimal 32-126) and without leading or trailing whitespace. |

---

**Alias Regular Expressions (REGEX)**

| Alias Identifier Type | Alias Regular Expression |
|----------------------|-------------------------|
| TELI - TELEPHONE NUMBER | ^\+[0-9]{1,3}-[1-9]{1,1}[0-9]{1,29}$ |
| EMAL - EMAIL ADDRESS | ^(?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{\|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$ |
| ABN - AUSTRALIAN BUSINESS NUMBER | ^((\d{9})\|(\d{11}))$ |
| ORGN - ORGANISATION ID | ^[!-@[-~][ -@[-~]{0,254}[!-@[-~]$ |

---
[Rate limits and throttling:](#limits) 

<h4 name="limits" id="limits"></h4>

#### Rate limits and throttling:

By default the following rate limits are applied.

| Type | TPH (Transactions Per Hour) | TPM (Transactions Per Minute) | TPS (Transactions Per Second) |
|------|----------------------------|------------------------------|------------------------------|
| Authorisation | 10 | n/a | 2 |
| PayTo Create Mandate | n/a | n/a | 10 |
| PayTo Change Mandate Status | n/a | n/a | 10 |
| PayTo Get Mandate Details | n/a | n/a | 5 |
| PayTo Create MPIR | n/a | n/a | 5 |

---
[Rate limiting algorithms:](#limiting) 

<h4 name="limiting" id="limiting"></h4>

#### Rate limiting algorithms:

For most use cases one of two algorithms is implemented for rate limiting.

**Fixed Window**
The system uses a window size of `n` seconds (typically using human-friendly values, such as 60 or 3600 seconds) to track the fixed window algorithm rate. Each incoming request increments the counter for the window. It discards the request if the counter exceeds a threshold. The current timestamp floor typically defines the windows, so 12:00:03, with a 60-second window length, would be in the 12:00:00 window.

**Sliding Window**
Sliding Window is a hybrid approach. Like the fixed window algorithm, we track a counter for each fixed window. Next, we account for a weighted value of the previous window's request rate based on the current timestamp to smooth out bursts of traffic.

[Sliding window example:](#example) 

<h4 name="example" id="example"></h4>

#### Sliding window example:

**Given a limit of 100 transactions per hour.**

- **Window 1 (13:00 - 14:00)**  
  Between 13:00 - 14:00, 80 requests are received. This is within the 100 tph limit, so all are allowed.

- **Window 2 (14:00 - 15:00)**  
  By 14:15, 20 requests are received. This is 25% (15 minutes) into window 2, so the weighted average would include 75% from the previous window.

  **Request rate**: 20 (all requests within window 2) + 60 (75% of requests from window 1) = 80 requests.  
  The request rate is still within the 100 tph maximum.

  By 14:30, 75 requests have been received. This is 50% (30 minutes) into window 2, so the weighted average would include 50% from the previous window.

  **Request rate**: 75 (all requests within window 2) + 40 (50% weighted average from previous window) = 115 requests.  
  This exceeds the 100 tph limit, so further requests would return an HTTP 429 (Too Many Requests) status code until the weighted request rate is below the agreed limit.

  By 14:45, no further requests have been made. This is 75% (45 minutes) through window 2.

  **Request rate**: 75 (current window) + 20 (25% weighted average from previous window) = 95 requests.  
  As this is below the 100 tph limit, further requests will be accepted.

---
layout: code
title: Authentication
menu_key: fileactive-btr-auth
group: statements
hero_key: statements
payload_spec: "/gcis/api-portal/fileactive/api/btr/data/auth-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
schema_tab: "false"
---

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](#keypoints) 

<h4 name="keypoints" id="keypoints"></h4>

#### Key points:

- **Endpoint:** All authentication requests should be sent to the `/v1.0/auth` endpoint.
- **Grant Type:** Use `client_credentials` as the grant type for obtaining tokens.
- **Token URL:** The token URL is `https://api.fileactive.anzgcis.com/v1.0/auth`.
- **Scopes:** Specific scopes define the permissions, such as:
  - `GBL.INSTO.ACCOUNTS.STATEMENT.READ` - Request Account Statement.     
- **Headers:** Include an API key in the header using `apikey` as the parameter name.

---
[Example request](#examplerequest) 

<h4 name="examplerequest" id="examplerequest"></h4>

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

```http
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=GBL.INSTO.ACCOUNTS.STATEMENT.READ&
client_assertion=<your_client_assertion_here>
```

[Example response](#exampleResponse) 

<h4 name="exampleResponse" id="exampleResponse"></h4>

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

```json
{
  "expires_in": 3600,
  "token_type": "Bearer",
  "access_token": "eaaa13ee-b596-a8cc-b9d4-f778f8bb9377"
}
```
[Usage notes](#usagenotes) 

<h4 name="usagenotes" id="usagenotes"></h4>

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

openapi: 3.0.1
info:
    title: Fileactive Authentication API
    version: 2.1.0
servers:
  - url: https://api.fileactive.uat.anzgcis.com
    description: UAT Test environment
  - url: https://api.fileactive.anzgcis.com
    description: Production Environment
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /v1.0/auth:
    post:
      security:
        - apiKeyAuth: []
          oAuth2: []
      summary: Auth Token Request
      description: >
        ANZ uses OAuth 2.0 to authenticate inbound token requests, a bearer token
        is returned as a response which is then used to authorise against ANZ
        resources.
      operationId: auth
      requestBody:
        description: 'Information and examples of Auth request body '
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/authTokenRequest'
      responses:
        '200':
          $ref: '#/components/responses/200OKAuth'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorised'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalError'
        '502':
          $ref: '#/components/responses/502BadGateway'
        '503':
          $ref: '#/components/responses/503Unavailable'
        '504':
          $ref: '#/components/responses/504Timeout'
        default:
          $ref: '#/components/responses/default'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: uuid
      description: Bearer token obtained during token exchange
    apiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: API key to authorise requests.
    oAuth2:
      type: oauth2
      description: OAuth2 flows for both Production and UAT environments
      flows:
        clientCredentials:
          tokenUrl: https://api.fileactive.anzgcis.com/v1.0/auth
          scopes:
            GBL.INSTO.ACCOUNTS.STATEMENT.READ: Request Account Statement     
    apiKey:
          type: apiKey
          in: header
          name: apikey
          description: API key to authorise requests.
  responses:
    200OKAuth:
      description: Bearer token (Opaque Token) returned after a token request
      headers:
        x-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/authTokenResponse'
    400BadRequest:
      description: Bad Request, message format does not match expected schema
      content: {}
    401Unauthorised:
      description: Application is not unauthorised to perform a specific action
      content: {}
    403Forbidden:
      description: Action is not authorised using current authentication credentils
      content: {}
    404NotFound:
      description: No record found
      content: {}
    429TooManyRequests:
      description: Action exceeds allocated limits
      content: {}
    500InternalError:
      description: Internal Server Error, contact support
      content: {}
    502BadGateway:
      description: Bad Gateway, contact support
      content: {}
    503Unavailable:
      description: Service Unavailable or down for maintainance
      content: {}
    504Timeout:
      description: Gateway Timeout, retry or contact support
      content: {}
    default:
      description: Unexpected error
      content: {}
  schemas:
    authTokenRequest:
      required:
        - grant_type
        - client_assertion_type
        - scope
        - client_assertion
      type: object
      properties:
        grant_type:
          description: Specify the type credential requested
          type: string
          example: client_credentials
        client_assertion_type:
          description: >-
            Describes the type of client assertion provided in the message
            request
          type: string
          example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
        scope:
          $ref: '#/components/securitySchemes/oAuth2/flows/clientCredentials/scopes'
        client_assertion:
          $ref: '#/components/schemas/ClientAssertion'
    authTokenResponse:
      type: object
      description: Response to report the status of a customer credit transfer.
      additionalProperties: false
      properties:
        expires_in:
          description: Indication on how long a token is valid for
          type: integer
        token_type:
          description: Type of token returned
          type: string
        access_token:
          description: >-
            Opaque token returned as part of request, Fileactive does not provide the
            full access token
          type: string
      example:
        expires_in: 3600
        token_type: Bearer
        access_token: eaaa13ee-b596-a8cc-b9d4-f778f8bb9377
    ClientAssertion:
      required:
        - sub
        - exp
        - aud
      type: object
      properties:
        sub:
          type: string
          description: Customer Code as provided by ANZ onboarding
          example: CUSTOMERA
        exp:
          type: integer
          description: EPOCH date and time
          example: '1619658591'
          maxLength: 10
          minLength: 10
        aud:
          type: string
          description: Specify the intended audience of the token request
          example: https://api.fileactive.anzgcis.com/auth
    UUID:
      type: string
      example: 71d6fb19-7515-40dc-b045-e17550b67600
      pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
  parameters:
    requestKey:
      name: X-REQUESTKEY
      in: header
      description: Internal End to End key used for support and reporting purposes
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275

openapi: 3.0.1
info:
  title: Fileactive Intra Day Statement API
  version: 2.1.1
servers:
- url: https://api.fileactive.uat.anzgcis.com
  description: 'UAT (non-production) environment'
- url: https://api.fileactive.anzgcis.com
  description: 'Production Environment'
  variables:
    basePath:
      default: accounts/v2.0
security:
  - apiKeyAuth: []
    bearerAuth: []
paths:
  /accounts/v2.0/statement:
    post:
      summary: Statement Request
      description: Get the statement of an account - For IntraDay reporting
      operationId: Submit Statement equest
      requestBody:
        description: Statement Request of an account on Intraday basis.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatementRequest'
            examples:
              Intraday:
                value:
                  {
                    "accountId" : "012123999999999",
                    "sortOrder" : "forward",
                    "cursor" : "MjAyMjA3MDQ6Ng==",
                    "maxEntries": 1,
                    "includeNarrative": true  
                  }
        required: true
      security:
        - apiKeyAuth: []
          bearerAuth: [GBL.INSTO.ACCOUNTS.STATEMENT.READ]
      responses:
        200:
          $ref: '#/components/responses/200'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        413:
          $ref: '#/components/responses/413'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        503:
          $ref: '#/components/responses/503'
        504:
          $ref: '#/components/responses/504'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: uuid
      description: Bearer token obtained during token exchange
    apiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: API key to authorize requests.
    oAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.fileactive.anzgcis.com/v1.0/auth
          scopes:
            GBL.INSTO.ACCOUNTS.STATEMENT.READ: Request Account Statement     
  parameters:
    requestKey:
      name: X-REQUESTKEY
      in: header
      description: Internal End to End key used for support and reporting purposes
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275
    id:
      name: REQUESTKEY
      in: path
      description: Internal End to End key need to be passed for getting Prior day statement
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275
      required: true
  responses:
    200:
      description: Statement Response
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatementResponse'
          examples:
              Intraday:
                value:
                  {
                    "accountId" : "012123999999999",
                    "sortOrder" : "forward",
                    "payload": "[camt.052.001.06 XML]",
                    "requestKey": "71d6fb19-7515-40dc-b045-e17550b67600",
                    "cursor" : "MjAyMjA3MDQ6Ng==",
                    "moreTransactionsAvailable": true  
                  }
              Priorday:
                value:
                  {
                    "accountId" : "012123999999999",
                    "requestKey" : "71d6fb19-7515-40dc-b045-e17550b67600"
                  }
    200OKAuth:
      description: Bearer token (Opaque Token) returned after a token request
      headers:
        x-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/authTokenResponse'
    204:
      description: Success, but CAMT.053 is not ready
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
    200Created:
      description: Prior Day Statement(CAMT.053) Requested for an account is returned successfully.
      headers:
        x-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetStatementResponse'
          examples:
              PriorDay:
                value:
                  {
                    "accountId" : "012123999999999",
                    "extract" : "priorday",
                    "sortOrder" : "forward",
                    "payload": "[camt.053.001.06 XML]",
                    "requestKey": "71d6fb19-7515-40dc-b045-e17550b67600",
                    "moreTransactionsAvailable": false  
                  }
    400:
      description: Bad Request
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    401:
      description: Unauthorised
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content: {}
    403:
      description: Forbidden
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes. This is not applicable for Corporate API.
          schema:
            $ref: '#/components/schemas/UUID'
      content: {}
    404:
      description: Not Found
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes. This is not applicable for Corporate API.
          schema:
            $ref: '#/components/schemas/UUID'
      content: {}
    413:
      description: Payload Too Large
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content: {}
    429:
      description: Too many requests
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content: {}
    500:
      description: Internal Error
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            PriorDay:
              value:
                {
                  "error": {
                    "statusCode" : "EC000_01",
                    "title" : "Internal Server Error, please contact support."        
                  },
                  "requestKey": "71d6fb19-7515-40dc-b045-e17550b67600"  
                }
    502:
        description: Bad Gateway, contact support
        headers:
          X-RequestKey:
            description: Request Key provided to customer for support and reporting
              purposes.
            schema:
              $ref: '#/components/schemas/UUID'
        content: {}
    503:
      description: Service Unavailable
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content: {}
    504:
      description: Gateway Timeout
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content: {}
    default:
      description: Unexpected error
      content: {}
  schemas:
    authTokenRequest:
      required:
        - grant_type
        - client_assertion_type
        - scope
        - client_assertion
      type: object
      properties:
        grant_type:
          description: Specify the type credential requested
          type: string
          example: client_credentials
        client_assertion_type:
          description: >-
            Describes the type of client assertion provided in the message
            request
          type: string
          example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
        scope:
          $ref: '#/components/securitySchemes/oAuth2/flows/clientCredentials/scopes'
        client_assertion:
          $ref: '#/components/schemas/ClientAssertion'
    authTokenResponse:
      type: object
      description: Response to report the status of a customer credit transfer.
      additionalProperties: false
      properties:
        expires_in:
          description: Indication on how long a token is valid for
          type: integer
        token_type:
          description: Type of token returned
          type: string
        access_token:
          description: >-
            Opaque token returned as part of request, GCIS does not provide the
            full access token
          type: string
      example:
        expires_in: 3600
        token_type: Bearer
        access_token: eaaa13ee-b596-a8cc-b9d4-f778f8bb9377
    Camt05200106Xml:
      type: string
      description: Message payload. Provided as camt.052.001.06 xml. 
        An empty camt.052.001.06 XML will be returned incase of PriorDay.
      example: '[camt.052.001.06 XML]'
      externalDocs:
        description: CAMT.052.001.06 xml message implementation guide with examples
        url: '../../fileactive/specs/accounts-statement.html'
    Camt05300106Xml:
      type: string
      description: Message payload. Provided as camt.053.001.06 xml.
      example: '[camt.053.001.06 XML]'
      externalDocs:
        description: CAMT.053.001.06 xml message implementation guide with examples
        url: '../../fileactive/specs/accounts-get-statement.html'
    ClientAssertion:
      required:
        - sub
        - exp
        - aud
      type: object
      properties:
        sub:
          type: string
          description: Customer Code as provided by ANZ onboarding
          example: CUSTOMERA
        exp:
          type: integer
          description: EPOCH date and time
          example: '1619658591'
          maxLength: 10
          minLength: 10
        aud:
          type: string
          description: Specify the intended audience of the token request
          example: https://api.fileactive.anzgcis.com/auth
    ErrorResponse:
      type: object
      properties:
        error:
          required:
          - statusCode
          - title
          type: object
          properties:
            statusCode:
              type: string
              description: Error code supplied to assist with support investigation
              example: EC42001
            title:
              type: string
              example: Failed to validate request body against JSON schema for customer.
        requestKey:
          type: string
          description: Unique identifier <UUID> used to correlate the message with
            ANZ
          example: 7380C995-2C70-4F25-8BBC-47DD1E60D5EA
    StatementRequest:
      required:
      - accountId
      type: object
      properties:
        accountId:
          title: Account Identifier
          maxLength: 35
          minLength: 1
          pattern: ^[a-zA-Z0-9.]*$
          type: string
          description: |
            Uniquely identify the account. For AU and NZ domestic accounts this will include BSB + account number.
          example: "012123999999999"
        extract:
          title: Extract
          type: string
          description: Extract is a request to API for generating statement details for a Prior Day.
            If no extract is passed, default will be IntraDay.
          example: "priorday"
        sortOrder:
          title: Sort order
          type: string
          description: Sort transactions &quot;forward&quot; (default) from least
            recent to most recent or &quot;backward&quot; from most recent to least
            recent.
          enum:
          - forward
          - backward
        cursor:
          title: Cursor
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          description: Statement entry cursor used for call back if requesting additional pages.
            Cursor is not applicable for Prior Day, as all statements will be sent in single CAMT.053
          example: "MjAyMjA3MDQ6Ng=="
        maxEntries:
          title: Maximum Entries.
          maximum: 1000
          minimum: 1
          type: string
          description: Maximum number of entries to return (1-1000), default to 1000. This is not applicable for Prior Day.
        includeNarrative:
          title: Include Narative.
          type: string
          description: 'Include extended narrative relevant (e.g. NPP 280 characters),
            (default: true).'
        startDate:
          title: Start Date of the prior day request.
          type: string
          description: 'Start Date (AEST format) can be passed for Prior Day upto 7 days backdated.'
        endDate:
          title: End Date of the prior day request.
          type: string
          description: 'End Date (AEST format) can be anything within 7 days from Start Date.'
    StatementResponse:
      required:
      - accountId
      - moreTransactionsAvailable
      - payload
      - requestKey
      - sortOrder
      type: object
      properties:
        accountId:
          type: string
          description: Uniquely identify the account.
          example: "012123999999999"
        sortOrder:
          type: string
          description: Sort transactions &quot;forward&quot; (default) from least
            recent to most recent or &quot;backward&quot; from most recent to least
            recent. Sort Order will always be forward incase of priorday.
          enum:
          - forward
          - backward
        payload:
          $ref: '#/components/schemas/Camt05200106Xml'
        requestKey:
          type: string
          description: Unique identifier used to correlate the message with ANZ
          example: 71d6fb19-7515-40dc-b045-e17550b67600
          pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
        cursor:
          type: string
          description: Statement entry cursor used for call back if requesting additional pages.
          example: "MjAyMjA3MDQ6Ng=="
        moreTransactionsAvailable:
          type: boolean
          description: More transactions available, use cursor in subsequent calls.
            It will be false by default for Prior Day.
          example: true
    GetStatementResponse:
      required:
      - accountId
      - extract
      - sortOrder
      - payload
      - requestKey
      - moreTransactionsAvailable
      type: object
      properties:
        accountId:
          type: string
          description: Uniquely identify the account.
          example: "012123999999999"
        extract:
          title: Extract
          type: string
          description: Extract is a request to API for generating statement details for a Prior Day.
          example: "priorday"
        sortOrder:
          type: string
          description: SortOrder will be forward by default for priorday.
          example: "forward"
        payload:
          $ref: '#/components/schemas/Camt05300106Xml'
        requestKey:
          type: string
          description: Unique identifier used to correlate the message with ANZ
          example: 71d6fb19-7515-40dc-b045-e17550b67600
          pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
        moreTransactionsAvailable:
          type: boolean
          description: More transactions available will be false by default for Prior Day.
          example: false
    UUID:
      type: string
      example: 71d6fb19-7515-40dc-b045-e17550b67600
      pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'

---
layout: code
title: End of day statements
menu_key: fileactive-btr-eod
group: statements
hero_key: statements
schema_spec: "/gcis/api-portal/fileactive/api/btr/data/eod-api-schema.yaml"
overview_tab: "true"
payload_tab: "false"   
schema_tab: "true"
stub_tab: "false"
---
---

End of Day Statements offer a consolidated summary of all account activities that occurred throughout the day. These statements are essential for businesses needing a comprehensive overview of their financial status at the close of each business day, supporting activities such as reconciliation, reporting, and financial analysis.

---
[Key capabilities](#keycapabilities) 

<h4 name="keycapabilities" id="keycapabilities"></h4>

#### Key Capabilities:
- **Daily Summary:** Provides a complete record of all transactions and account balances at the end of each business day, giving a clear snapshot of the day's financial activity.
- **Detailed Reporting:** Includes comprehensive details on each transaction, such as amounts, types, timestamps, and references, helping businesses maintain accurate and thorough financial records.
- **Consistency and Reliability:** End of Day Statements are generated automatically, ensuring consistent availability of financial data for daily reconciliation and reporting processes.
- **Customizable Data:** Allows businesses to select specific criteria, such as transaction types or account details, to tailor the content of the statements to meet specific reporting needs.

---

[Technical requirements](#techrequirements) 

<h4 name="techrequirements" id="techrequirements"></h4>

#### Technical Requirements:
- **Authentication:** Access to End of Day Statements requires OAuth 2.0 authentication with a bearer token, obtained through the Client Credential Grant flow.
- **Endpoints:** API endpoints are available to request and retrieve end-of-day statements in a structured and secure manner.
- **Response Format:** Statements are provided in JSON format, facilitating easy integration into various financial systems and workflows.
- **Error Handling:** Detailed error codes and responses support efficient management of requests and ensure reliable access to statement data.

---

[Key features for developers](#keyfeatures) 

<h4 name="keyfeatures" id="keyfeatures"></h4>

#### Key Features for Developers:
- **API Integration:** Integrate End of Day Statements into your financial systems through APIs, automating the collection and processing of daily financial data.
- **Structured Data Delivery:** Utilize JSON-based responses for straightforward parsing and integration, reducing the time and effort needed to incorporate data into existing systems.
- **Secure Data Access:** All data exchanges are protected using HTTPS and OAuth 2.0, ensuring that sensitive financial information remains secure.
- **Automation Friendly:** Set up automated retrieval of statements at the end of each business day to streamline reconciliation and reporting processes.

---

[Example use cases](#exampleusecases) 

<h4 name="exampleusecases" id="exampleusecases"></h4>

#### Example Use Cases:
- **Daily Reconciliation:** Use end-of-day data to reconcile transactions across different systems, ensuring accuracy in financial records and reducing discrepancies.
- **Financial Reporting:** Generate daily financial reports that summarize account activity, helping stakeholders maintain oversight of financial performance.
- **Audit Preparation:** Maintain a comprehensive log of daily transactions that can be easily accessed and reviewed during audits or compliance checks.
- **Cash Position Management:** Review the end-of-day cash position to make informed decisions about investments, loans, or other financial actions.

openapi: 3.0.1
info:
  title: Fileactive Prior Day Statement API
  version: 2.1.1
servers:
- url: https://api.fileactive.uat.anzgcis.com
  description: 'UAT (non-production) environment'
- url: https://api.fileactive.anzgcis.com
  description: 'Production Environment'
  variables:
    basePath:
      default: accounts/v2.0
security:
  - apiKeyAuth: []
    bearerAuth: []
paths:
  /accounts/v2.0/statement:
    post:
      summary: Statement Request
      description: Get the statement of an account - For Prior Day
      operationId: Submit Statement Request
      requestBody:
        description: Statement Request of an account on Priorday basis.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatementRequest'
            examples:
              Priorday:
                value:
                  {
                    "accountId" : "012123999999999",
                    "extract" : "priorday",
                    "startDate": "2022-12-04",
                    "endDate": "2022-12-07"
                  }
        required: true
      security:
        - apiKeyAuth: []
          bearerAuth: [GBL.INSTO.ACCOUNTS.STATEMENT.READ]
      responses:
        200:
          $ref: '#/components/responses/200'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        413:
          $ref: '#/components/responses/413'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        503:
          $ref: '#/components/responses/503'
        504:
          $ref: '#/components/responses/504'
  /accounts/v2.0/statement/requestKey:
    get:
      summary: Get Statement Request for prior day.
      description: Get the statement of an account - For prior day or a date range (up to 7 days)
      tags:
        - Statements
      operationId: getStatement
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        200:
          $ref: '#/components/responses/200Created'
        204:
          $ref: '#/components/responses/204'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        503:
          $ref: '#/components/responses/503'
        504:
          $ref: '#/components/responses/504'
      security:
        - apiKeyAuth: []
          bearerAuth: [GBL.INSTO.ACCOUNTS.STATEMENT.READ]
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: uuid
      description: Bearer token obtained during token exchange
    apiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: API key to authorize requests.
    oAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.fileactive.anzgcis.com/v1.0/auth
          scopes:
            GBL.INSTO.ACCOUNTS.STATEMENT.READ: Request Account Statement     
  parameters:
    requestKey:
      name: X-REQUESTKEY
      in: header
      description: Internal End to End key used for support and reporting purposes
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275
    id:
      name: REQUESTKEY
      in: path
      description: Internal End to End key need to be passed for getting Prior day statement
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275
      required: true
  responses:
    200:
      description: Statement Response
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatementResponse'
          examples:
              Intraday:
                value:
                  {
                    "accountId" : "012123999999999",
                    "sortOrder" : "forward",
                    "payload": "[camt.052.001.06 XML]",
                    "requestKey": "71d6fb19-7515-40dc-b045-e17550b67600",
                    "cursor" : "MjAyMjA3MDQ6Ng==",
                    "moreTransactionsAvailable": true  
                  }
              Priorday:
                value:
                  {
                    "accountId" : "012123999999999",
                    "requestKey" : "71d6fb19-7515-40dc-b045-e17550b67600"
                  }
    200OKAuth:
      description: Bearer token (Opaque Token) returned after a token request
      headers:
        x-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/authTokenResponse'
    204:
      description: Success, but CAMT.053 is not ready
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
    200Created:
      description: Prior Day Statement(CAMT.053) Requested for an account is returned successfully.
      headers:
        x-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetStatementResponse'
          examples:
              PriorDay:
                value:
                  {
                    "accountId" : "012123999999999",
                    "extract" : "priorday",
                    "sortOrder" : "forward",
                    "payload": "[camt.053.001.06 XML]",
                    "requestKey": "71d6fb19-7515-40dc-b045-e17550b67600",
                    "moreTransactionsAvailable": false  
                  }
    400:
      description: Bad Request
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    401:
      description: Unauthorised
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content: {}
    403:
      description: Forbidden
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes. This is not applicable for Corporate API.
          schema:
            $ref: '#/components/schemas/UUID'
      content: {}
    404:
      description: Not Found
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes. This is not applicable for Corporate API.
          schema:
            $ref: '#/components/schemas/UUID'
      content: {}
    413:
      description: Payload Too Large
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content: {}
    429:
      description: Too many requests
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content: {}
    500:
      description: Internal Error
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            PriorDay:
              value:
                {
                  "error": {
                    "statusCode" : "EC000_01",
                    "title" : "Internal Server Error, please contact support."        
                  },
                  "requestKey": "71d6fb19-7515-40dc-b045-e17550b67600"  
                }
    502:
        description: Bad Gateway, contact support
        headers:
          X-RequestKey:
            description: Request Key provided to customer for support and reporting
              purposes.
            schema:
              $ref: '#/components/schemas/UUID'
        content: {}
    503:
      description: Service Unavailable
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content: {}
    504:
      description: Gateway Timeout
      headers:
        X-RequestKey:
          description: Request Key provided to customer for support and reporting
            purposes.
          schema:
            $ref: '#/components/schemas/UUID'
      content: {}
    default:
      description: Unexpected error
      content: {}
  schemas:
    authTokenRequest:
      required:
        - grant_type
        - client_assertion_type
        - scope
        - client_assertion
      type: object
      properties:
        grant_type:
          description: Specify the type credential requested
          type: string
          example: client_credentials
        client_assertion_type:
          description: >-
            Describes the type of client assertion provided in the message
            request
          type: string
          example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
        scope:
          $ref: '#/components/securitySchemes/oAuth2/flows/clientCredentials/scopes'
        client_assertion:
          $ref: '#/components/schemas/ClientAssertion'
    authTokenResponse:
      type: object
      description: Response to report the status of a customer credit transfer.
      additionalProperties: false
      properties:
        expires_in:
          description: Indication on how long a token is valid for
          type: integer
        token_type:
          description: Type of token returned
          type: string
        access_token:
          description: >-
            Opaque token returned as part of request, GCIS does not provide the
            full access token
          type: string
      example:
        expires_in: 3600
        token_type: Bearer
        access_token: eaaa13ee-b596-a8cc-b9d4-f778f8bb9377
    Camt05200106Xml:
      type: string
      description: Message payload. Provided as camt.052.001.06 xml. 
        An empty camt.052.001.06 XML will be returned incase of PriorDay.
      example: '[camt.052.001.06 XML]'
      externalDocs:
        description: CAMT.052.001.06 xml message implementation guide with examples
        url: '../../btr/accounts-statement'
    Camt05300106Xml:
      type: string
      description: Message payload. Provided as camt.053.001.06 xml.
      example: '[camt.053.001.06 XML]'
      externalDocs:
        description: CAMT.053.001.06 xml message implementation guide with examples
        url: '../../btr/accounts-get-statement'
    ClientAssertion:
      required:
        - sub
        - exp
        - aud
      type: object
      properties:
        sub:
          type: string
          description: Customer Code as provided by ANZ onboarding
          example: CUSTOMERA
        exp:
          type: integer
          description: EPOCH date and time
          example: '1619658591'
          maxLength: 10
          minLength: 10
        aud:
          type: string
          description: Specify the intended audience of the token request
          example: https://api.fileactive.anzgcis.com/auth
    ErrorResponse:
      type: object
      properties:
        error:
          required:
          - statusCode
          - title
          type: object
          properties:
            statusCode:
              type: string
              description: Error code supplied to assist with support investigation
              example: EC42001
            title:
              type: string
              example: Failed to validate request body against JSON schema for customer.
        requestKey:
          type: string
          description: Unique identifier <UUID> used to correlate the message with
            ANZ
          example: 7380C995-2C70-4F25-8BBC-47DD1E60D5EA
    StatementRequest:
      required:
      - accountId
      type: object
      properties:
        accountId:
          title: Account Identifier
          maxLength: 35
          minLength: 1
          pattern: ^[a-zA-Z0-9.]*$
          type: string
          description: |
            Uniquely identify the account. For AU and NZ domestic accounts this will include BSB + account number.
          example: "012123999999999"
        extract:
          title: Extract
          type: string
          description: Extract is a request to API for generating statement details for a Prior Day.
            If no extract is passed, default will be IntraDay.
          example: "priorday"
        sortOrder:
          title: Sort order
          type: string
          description: Sort transactions &quot;forward&quot; (default) from least
            recent to most recent or &quot;backward&quot; from most recent to least
            recent.
          enum:
          - forward
          - backward
        cursor:
          title: Cursor
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          description: Statement entry cursor used for call back if requesting additional pages.
            Cursor is not applicable for Prior Day, as all statements will be sent in single CAMT.053
          example: "MjAyMjA3MDQ6Ng=="
        maxEntries:
          title: Maximum Entries.
          maximum: 1000
          minimum: 1
          type: string
          description: Maximum number of entries to return (1-1000), default to 1000. This is not applicable for Prior Day.
        includeNarrative:
          title: Include Narative.
          type: string
          description: 'Include extended narrative relevant (e.g. NPP 280 characters),
            (default: true).'
        startDate:
          title: Start Date of the prior day request.
          type: string
          description: 'Start Date (AEST format) can be passed for Prior Day upto 7 days backdated.'
        endDate:
          title: End Date of the prior day request.
          type: string
          description: 'End Date (AEST format) can be anything within 7 days from Start Date.'
    StatementResponse:
      required:
      - accountId
      - moreTransactionsAvailable
      - payload
      - requestKey
      - sortOrder
      type: object
      properties:
        accountId:
          type: string
          description: Uniquely identify the account.
          example: "012123999999999"
        sortOrder:
          type: string
          description: Sort transactions &quot;forward&quot; (default) from least
            recent to most recent or &quot;backward&quot; from most recent to least
            recent. Sort Order will always be forward incase of priorday.
          enum:
          - forward
          - backward
        payload:
          $ref: '#/components/schemas/Camt05200106Xml'
        requestKey:
          type: string
          description: Unique identifier used to correlate the message with ANZ
          example: 71d6fb19-7515-40dc-b045-e17550b67600
          pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
        cursor:
          type: string
          description: Statement entry cursor used for call back if requesting additional pages.
          example: "MjAyMjA3MDQ6Ng=="
        moreTransactionsAvailable:
          type: boolean
          description: More transactions available, use cursor in subsequent calls.
            It will be false by default for Prior Day.
          example: true
    GetStatementResponse:
      required:
      - accountId
      - extract
      - sortOrder
      - payload
      - requestKey
      - moreTransactionsAvailable
      type: object
      properties:
        accountId:
          type: string
          description: Uniquely identify the account.
          example: "012123999999999"
        extract:
          title: Extract
          type: string
          description: Extract is a request to API for generating statement details for a Prior Day.
          example: "priorday"
        sortOrder:
          type: string
          description: SortOrder will be forward by default for priorday.
          example: "forward"
        payload:
          $ref: '#/components/schemas/Camt05300106Xml'
        requestKey:
          type: string
          description: Unique identifier used to correlate the message with ANZ
          example: 71d6fb19-7515-40dc-b045-e17550b67600
          pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
        moreTransactionsAvailable:
          type: boolean
          description: More transactions available will be false by default for Prior Day.
          example: false
    UUID:
      type: string
      example: 71d6fb19-7515-40dc-b045-e17550b67600
      pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'

---
layout: detail
title: Return codes
menu_key: fileactive-btr
group: statements
hero_key: statements
---
---

[Default API event codes](#defaultapicode) 

<h4 name="defaultapicode" id="defaultapicode"></h4>

### Default API Event Codes

| Event Code | Name                   | HTTP <BR> Response | Description                                    |
| :--------- | :--------------------- | :----------------: | :--------------------------------------------- |
| EC000_001  | Internal Server Error  |        500         | Internal Server Error, please contact support. |
| EC000_002  | Unauthorized           |        401         | The request is not authorized                  |
| EC000_003  | Validation Failure     |        400         | The request failed validation                  |
| EC000_004  | Resource Not Found     |        404         | The requested resource is not found            |
| EC000_005  | Method Not Allowed     |        405         | The requested HTTP method is not allowed       |
| EC000_006  | Unsupported Media Type |        405         | Content-Type provided is not supported         |
| EC000_007  | Invalid Content        |        400         | Invalid secured payload  

[Account statement event codes](#accountstatementeventcodes) 

<h4 name="accountstatementeventcodes" id="accountstatementeventcodes"></h4>

### Account Statement Event Codes

| Code    | Name                               | Description                                                                       |
|:--------|:-----------------------------------|:----------------------------------------------------------------------------------|
| EC20001 | Account Id not found               | Account Id: '{0}' not found                                                       |
| EC20003 | Error retrieving account statement | Error retrieving account statement for account id: '{0}'                          |
| EC20005 | Internal error                     | An unknown error has occurred, please contact support and quote requestKey: '{0}' |

---
layout: detail
title: Account statements API catalogue
menu_key: fileactive-btr
group: statements
hero_key: statements
---
---
The Statements feature of the Fileactive API allows businesses to generate detailed transaction statements, providing a comprehensive view of financial activities. This capability supports various reporting needs, including reconciliation, auditing, and financial analysis, by offering accurate and timely access to transaction data. The API ensures secure access through OAuth 2.0 and JWT encryption, making it a reliable solution for managing financial records.

[Key features](#keyfeatures) 

<h4 name="keyfeatures" id="keyfeatures"></h4>

#### Key Features:
- **Detailed Transaction Data:** Retrieve statements with detailed information on individual transactions, including amounts, dates, fees, and other relevant data.

- **Customizable Reports:** Generate statements based on specific criteria such as date ranges, transaction types, or account details, allowing for tailored financial reporting.

- **On-Demand and Scheduled Statements:** Access statements on demand or set up scheduled generation to keep financial records up to date automatically.

- **Secure Access:** Statements are securely generated and accessed using OAuth 2.0 authentication and JWT encryption, safeguarding sensitive financial information.

#### Technical Details:
- **API Endpoints:** Provides endpoints for requesting statements, specifying filters, and retrieving completed reports.

- **JSON-Based Responses:** Statements are delivered in JSON format for easy parsing and integration into your systems.

- **Error Handling:** Detailed error codes and responses to assist in managing requests and resolving issues efficiently.

[Use cases](#usecase) 

<h4 name="usecase" id="usecase"></h4>

#### Use Cases:
- **Financial Reporting:** Generate accurate and detailed financial statements for auditing, tax preparation, or internal reporting.

- **Account Reconciliation:** Use statements to match payments with invoices, helping to identify discrepancies and ensure financial accuracy.

- **Business Analytics:** Leverage transaction data from statements to perform financial analysis, aiding in decision-making and strategy development.

<div class="mermaid">
sequenceDiagram
    participant Customer
    participant Fileactive

    %% Authentication Flow
    Customer->>Fileactive: POST /v1.0/auth (OAuth Client Assertion)
    Fileactive-->>Customer: 200 OK (Bearer Token)

    %% Statement Request Flow
    Customer->>Fileactive: POST /accounts/v2.0/statement (Request Statement, JSON Payload)
    Fileactive-->>Customer: 202 Accepted (Statement Request Received)

    %% Statement Generation and Status Check
    Note right of Fileactive: Fileactive processes the request<br>and generates the statement

    Customer->>Fileactive: GET /accounts/v2.0/statement/{requestKey} (Check Statement Status)
    alt Statement Ready
        Fileactive-->>Customer: 200 OK (Statement Ready, CAMT.053 XML)
    else Statement Not Ready
        Fileactive-->>Customer: 204 No Content (Statement Not Ready)
    end

    %% Statement Download Flow
    Customer->>Fileactive: GET /accounts/v2.0/statement/{requestKey}/download (Download Statement)
    Fileactive-->>Customer: 200 OK (Statement File, CAMT.053 XML)
</div>

---
[Key points for developers](#keypoints) 

<h4 name="keypoints" id="keypoints"></h4>

#### Key Points for Developers:
- **Consistent API Design:** The API follows a uniform structure, making it easier to integrate with other Fileactive APIs and reducing the learning curve for developers.
  
- **Real-Time Access:** Utilize the API to fetch the most recent financial data, supporting applications that require up-to-date transaction information.

- **Secure Data Handling:** Implement secure data handling practices, including validating OAuth tokens and verifying JWT signatures to ensure the integrity and confidentiality of your data.

- **Scalability:** The API is designed to handle high-volume requests, making it suitable for large-scale applications and high-frequency data retrieval needs.

- **Efficient Error Management:** Use the detailed error responses provided by the API to implement robust error handling, ensuring smooth operation even when issues arise.

----
[Rate limits and throttling](#ratelimits) 

<h4 name="ratelimits" id="ratelimits"></h4>

#### Rate limits and throttling:

By default the following rate limits are applied.

| Type             | TPH (Transactions Per Hour) | TPM (Transactions Per Minute) | TPS (Transactions Per Second) |
|------------------|-----------------------------|-------------------------------|-------------------------------|
| Authorisation     | 10                          | n/a                           | 2                             |
| Statement / BTR   | 25                          | n/a                           | n/a                           |


---

[Rate limiting algorithms](#ratelimitsalgorithms) 

<h4 name="ratelimitsalgorithms" id="ratelimitsalgorithms"></h4>

#### Rate limiting algorithms:

For most use cases one of two algorithms is implemented for rate limiting.

**Fixed Window**
The system uses a window size of `n` seconds (typically using human-friendly values, such as 60 or 3600 seconds) to track the fixed window algorithm rate. Each incoming request increments the counter for the window. It discards the request if the counter exceeds a threshold. The current timestamp floor typically defines the windows, so 12:00:03, with a 60-second window length, would be in the 12:00:00 window.

**Sliding Window**
Sliding Window is a hybrid approach. Like the fixed window algorithm, we track a counter for each fixed window. Next, we account for a weighted value of the previous window’s request rate based on the current timestamp to smooth out bursts of traffic.

[Sliding window example](#slidingwindowexample) 

<h4 name="slidingwindowexample" id="slidingwindowexample"></h4>

#### Sliding window example:

**Given a limit of 100 transactions per hour.**

- **Window 1 (13:00 - 14:00)**  
  Between 13:00 - 14:00, 80 requests are received. This is within the 100 tph limit, so all are allowed.

- **Window 2 (14:00 - 15:00)**  
  By 14:15, 20 requests are received. This is 25% (15 minutes) into window 2, so the weighted average would include 75% from the previous window.

  **Request rate**: 20 (all requests within window 2) + 60 (75% of requests from window 1) = 80 requests.  
  The request rate is still within the 100 tph maximum.

  By 14:30, 75 requests have been received. This is 50% (30 minutes) into window 2, so the weighted average would include 50% from the previous window.

  **Request rate**: 75 (all requests within window 2) + 40 (50% weighted average from previous window) = 115 requests.  
  This exceeds the 100 tph limit, so further requests would return an HTTP 429 (Too Many Requests) status code until the weighted request rate is below the agreed limit.

  By 14:45, no further requests have been made. This is 75% (45 minutes) through window 2.

  **Request rate**: 75 (current window) + 20 (25% weighted average from previous window) = 95 requests.  
  As this is below the 100 tph limit, further requests will be accepted.

---
layout: detail
title: Real time notifications australia NPP code catalogue
menu_key: fileactive-rtn
group: rtn
hero_key: rtn
---
&nbsp;

The NPP Real-Time Notification (RTN) service enables instant, secure notifications for payment-related events within the New Payments Platform (NPP) ecosystem. This service provides real-time updates to subscribers, ensuring that businesses can react promptly to various financial events such as payment initiations, completions, and failures.

---
[Key capabilities](#capabilities) 

<h4 name="capabilities" id="capabilities"></h4>

#### Key Capabilities:
- **Instant Notifications:** RTN delivers real-time alerts for payment events, allowing for immediate action or reconciliation.
- **Secure Delivery:** Notifications are securely transmitted using HTTPS, ensuring data integrity and confidentiality.
- **Event Subscription:** Clients can subscribe to specific events based on their business needs, such as payment acknowledgments or rejections.
- **Scalable Integration:** Designed to handle high volumes of transactions, RTN can be integrated into existing systems with minimal impact on performance.

---

[Technical requirements](#technical) 

<h4 name="technical" id="technical"></h4>

#### Technical Requirements:
- **Authentication:** Access to RTN requires OAuth 2.0 authentication, using a bearer token obtained via the Client Credential Grant flow.
- **Endpoints:** RTN operates through dedicated endpoints that handle various notification types. Ensure your system is set up to receive and process these events.
- **Payloads:** Notification payloads are delivered in JSON format, containing essential details such as transaction IDs, timestamps, and status updates.
- **Error Handling:** Robust error management is necessary to handle scenarios where notifications fail to be delivered or processed correctly.

---

[Key features for developers](#features) 

<h4 name="features" id="features"></h4>

#### Key Features for Developers:
- **Webhooks Integration:** RTN uses webhooks to push notifications to a specified endpoint, reducing the need for polling and improving efficiency.
- **Customizable Subscriptions:** Developers can configure which events to receive, allowing for tailored integrations that align with specific business requirements.
- **Retry Mechanism:** Built-in retry logic ensures that notifications are resent in case of initial failures, maintaining the reliability of the notification service.
- **Security Best Practices:** Notifications include digital signatures for verification, and HTTPS is used for all communication to protect sensitive data.

---

[Example use cases](#usecases) 

<h4 name="usecases" id="usecases"></h4>

#### Example Use Cases:
- **Payment Tracking:** Automatically update payment statuses in your system as soon as an event occurs, improving financial visibility.
- **Fraud Detection:** Receive alerts on suspicious transactions in real-time, enabling quick responses to potential security threats.
- **Customer Notifications:** Inform customers immediately about the status of their payments, enhancing the customer experience with timely updates.

openapi: 3.0.1
info:
  title: Request A Real Time Notification Test API
  version: 1.0.3

servers:
  - url: https://api.fileactive.uat.anzgcis.com/testingfileactive/v1.0
    description: 'UAT (non-production) environment'
security:
  - apiKeyAuth: []
paths:
  /rtn:
    post:
      summary: Submit
      description: |-
        Request includes attributes which will be included in the RTN. All unspecified RTN fields will be defaulted  
      operationId: submitRTNRequest
      parameters:
        - $ref: '#/components/parameters/correlationID'
        - $ref: '#/components/parameters/messageID'
        - $ref: '#/components/parameters/apikey'    
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestRTN'
            examples:
              NPP:
                value:
                  {
                    "account_identification" : "014814800000010",
                    "entry_reference" : "Reference entered in the channel",
                    "amount" : "7120.86",
                    "puid": "PTM2022101389715",
                    "debtor_name": "Andras Arato",
                    "creditor_name": "Holden Holdings",
                    "arm_creditor_account_identification": "063678965323010",
                    "creditor_alias": {
                      "type": "TELI",
                      "identification": "+61403736550"
                      },
                    "remittance_information": {
                      "unstructured": [
                      "👨‍👩‍👧‍👦Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim a",
                      "d minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit i"
                      ]
                      },
                    "return_information": {
                      "reason_code": "NARR",
                      "additional_information": [
                      "Beneficiary is",
                      "unknown"
                      ]
                      }  
                  }
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201Created'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorised'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalError'
        '502':
          $ref: '#/components/responses/502BadGateway'
        '503':
          $ref: '#/components/responses/503Unavailable'
        '504':
          $ref: '#/components/responses/504Timeout'
        default:
          $ref: '#/components/responses/default'
components:
  parameters:
    correlationID:
      name: x-Correlation-Id
      in: header
      description: >-
        Optional correlation ID provided by the data consumer that should be
        reflected back in the response headers. Can be used for reporting and
        logging.
      schema:
        $ref: '#/components/schemas/UUID'
      example: 'baf7b2b0-449d-48c7-a63a-876e72cd7b02'
    messageID:
      name: x-Message-Id
      in: header
      description: >-
        Point to point reference, as assigned by the
        instructing party, and sent to the next party in the chain to
        unambiguously identify the message
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
      example: '3c40b28a-b902-477f-8400-6cb97d41cb06'
    apikey:
      name: apikey
      in: header
      description: >-
        API key to authorise requests.
      required: true
      example: 'BDmjSQDvOlZC5ExDfr3rf2GwFE1tWQ3D'      
    priority:
      name: priority
      in: header
      description: Priority (attended/unattended) to be included in any generated notification.
      required: true
      schema:
        $ref: '#/components/schemas/NotificationPriority1Code'
    priority2:
      name: priority
      in: header
      description: Priority (attended/unattended) to be included in any generated notification. <br><br> Only **UNATTENDED** is supported for this request type.
      required: true
      schema:
        $ref: '#/components/schemas/NotificationPriority2Code'    
  responses:
    201Created:
      description: Created, request was successful
      headers:
        x-Correlation-Id:
          description: GUID echoed from request. Example baf7b2b0-449d-48c7-a63a-876e72cd7b02
          schema:
            $ref: '#/components/schemas/UUID'
        x-RequestKey:
          description: Request Key provided to customer for support and reporting purposes. Example 7eda441d-5716-4f28-b5fe-d3dc7458d526
          schema:
            $ref: '#/components/schemas/UUID'
    400BadRequest:
      description: Bad Request, message format does not match expected schema
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorCode'
          example:
            status:
              code: EC000_003
              severity: Fatal
              text: The request failed validation {reason}
    401Unauthorised:
      description: Request is not authenticated
      content: {}
    403Forbidden:
      description: Request is authenticated but action is not allowed 
      content: 
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorCode'
          example:
            status:
              code: EC013_003
              severity: Fatal
              text: The provided account_identification = 013999012345678 is not authorised to receive real time notifications. Provide an authorised account or please contact support
    429TooManyRequests:
      description: Action exceeds allocated limits
      content: {}
    500InternalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorCode'
          example:
            status:
              code: EC000_001
              severity: Fatal
              text: Internal Server Error, please contact support
    502BadGateway:
      description: Bad Gateway, contact support
      content: {}
    503Unavailable:
      description: Service Unavailable or down for maintainance
      content: {}
    504Timeout:
      description: Gateway Timeout, retry or contact support
      content: {}
    default:
      description: Unexpected error
      content: {}
  schemas:
    NotificationPriority1Code:
      type: string
      description: |-
        Defines the notification priority.
        <table><tr><th>Code</th><th>Description</th></tr><tr><td>ATTENDED</td><td> Attended mode of operation.</td></tr><tr><td>UNATTENDED</td><td>Unattended mode of operation.</td></tr></table>
      enum:
      - ATTENDED
      - UNATTENDED
    NotificationPriority2Code:
      type: string
      description: |-
        Defines the notification priority.
        <table><tr><th>Code</th><th>Description</th></tr><tr><td>UNATTENDED</td><td>Unattended mode of operation.</td></tr></table>
      enum:
      - UNATTENDED
    RequestRTN:
      required:
      - entry_reference
      - amount
      type: object
      properties:
        account_identification:
          type: string
          description: >-
            Account identification assigned by an institution, includes BSB. 
            This field is not applicable for Singapore FAST
          minLength: 1
          maxLength: 34
          example: '014814800000010'
        entry_reference:
          type: string
          minLength: 1
          maxLength: 35
          description: Unique reference for the entry
          example: Reference entered in the initiating channel     
        amount:
          type: string
          description: Notified amount in AUD for NPP. This will be in SGD for Singapore FAST.
          minLength: 1
          maxLength: 19
          example: 7120.86
        puid:
          type: string
          minLength: 1
          maxLength: 16
          description: An optionally provided identifier which is returned in the requested RTN
          example: "PTM2022101389715"
        debtor_name:
          type: string
          minLength: 1
          maxLength: 140  
          description: Debtor (payer) account name 
          example: Andras Arato
        creditor_name:
          type: string
          minLength: 1
          maxLength: 140  
          description: Creditor (biller) account name 
          example: Holden Holdings
        arm_creditor_account_identification:
          type: string
          description: >-
            ARM(virtual)account identification, includes BSB for NPP. 
            Only has account number for SG FAST
          minLength: 1
          maxLength: 34
          example: '063678965323010'
        creditor_alias:
          required:
          - type
          - identification
          type: object
          description: Creditor account alias (Applicable for NPP only)
          properties:
            type:
              type: string
              enum:
                - 'TELI'
                - 'EMAL'
                - 'AUBN'
                - 'ORGN'
              description: Creditor account alias type
              example: 'TELI'
            identification:
              type: string
              description: Creditor account alias identification
              minLength: 1
              maxLength: 2048
              example: '+61403736550'
        remittance_information:
          type: object
          properties:
            unstructured:
              type: array
              description: >-
                Information supplied to enable the matching/reconciliation of an entry 
                with the items that the payment is intended to settle, such as commercial 
                invoices in an accounts receivable system, in an unstructured form.
              example: ['👨‍👩‍👧‍👦Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim a','d minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit i']
              items:
                type: string
                minLength: 1
                maxLength: 140
              minItems: 1
              maxItems: 2
        return_information:
          type: object
          description: Applicable only for NPP
          properties:
            reason_code:
              type: string
              description: Payment return reason code
              minLength: 4
              maxLength: 4
              example: NARR   
            additional_information:
              type: array
              description: Further details on the return reason  
              example: ['Beneficiary is','unknown']
              items:
                type: string
                minLength: 1
                maxLength: 105
              minItems: 1
              maxItems: 3
        hierarchy:
            type: string
            description: Always SG/PAYMENTS (Applicable for SG FAST only)
            minLength: 1
            maxLength: 11
            example: 'SG/PAYMENT'     
        postingBsb:
              type: string
              description: Will be the BIC where the funds were posted (Applicable for SG FAST only)
              minLength: 1
              maxLength: 11
              example: 'ANZBSGSXXXX'
        postingAcctNmbr:
              type: string
              description: will be the account number where the funds are posted (Applicable for SG FAST only)
              minLength: 1
              maxLength: 34
              example: '148148000000333'
        acctBsb:
                type: string
                description: Will be populated with the real/natural BIC or the virtual BIC (Applicable for SG FAST only)
                minLength: 1
                maxLength: 11
                example: 'ANZBSGSXXXY'
        acctNmbr:
              type: string
              description: Will be populated with the real/natural account number or the ARM/virtual account number (Applicable for SG FAST only)
              minLength: 1
              maxLength: 34
              example: '148148000000333'
    UUID:
      type: string
      pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
    ErrorCode:
      type: object
      properties: 
        status:
          type: object
          required:
          - code
          - severity
          - text
          properties:
            code:
              type: string
              example: EC000_001
            severity: 
              type: string
              enum:
                - Fatal
                - Transient
              example: Fatal
            text:
              type: string
              example: Internal Server Error, please contact support   

---
layout: code
title: Real time notification NPP
menu_key: fileactive-rtn-npp
group: rtn
hero_key: fileactive
schema_spec: "/gcis/api-portal/fileactive/api/rtn/data/npp-rtn-api-schema.yaml"
testing_spec: "/gcis/api-portal/fileactive/api/rtn/data/testing-npp-rtn-api-schema.yaml"
overview_tab: "false"
payload_tab: "false"   
schema_tab: "true"
testing_tab: "true"
---

UAT scenarios

---
layout: detail
title: NPP RTN User acceptance testing scenarios
menu_key: fileactive-rtn
group: rtn
hero_key: rtn
---

<br />

[Question](#question) 

<h4 name="question" id="question"></h4>

**Question**

What UAT scenarios does ANZ recommend a customer complete prior to activating the NPP Real Time Notification service?

[Answer](#answer) 

<h4 name="answer" id="answer"></h4>

**Answer**

Using the Fileactive Self Service Testing API it is recommended a customer complete the following testing scenarios. <br><br>

<table>
    <thead>
  <tr>
    <th>#</th>
    <th>Scenario</th>
    <th>Description</th>
    <th>RTN Self-Service Request</th>
    <th>NPP Payment Notification Response Snipet</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>1</td>
    <td>ARM customer receipt</td>
    <td>The Corporate Customer is configured with an ARM account and receives a payment to their virtual account</td>
    <td>
    <pre>
  {
    "account_identification": "014814800000010",
    "entry_reference": "Trading transfer",
    "amount": "100.50",
    "debtor_name": "Andras Arato",
    "creditor_name": "Holden Holdings",
    "arm_creditor_account_identification": "063678965323010",
    "remittance_information": {
      "unstructured": [
        "Testing ARM Customer"
      ]
    }
  }
    </pre>
    </td>
    <td>
    <pre>
  {
    "identification": "D942DD0B23674C3FBDC2702ECB0C837F",
    "creation_date_time": "2022-07-27T23:44:01.9842888+00:00",
    "account_identification": "014814800000010",
    "account_issuer": "014814",
    "entry": [
      {
        "related_parties": {
          "creditor_account_identification": "965323010",
          "creditor_account_issuer": "063678"
        }
      }
    ]
  }
    </pre>
    </td>
  </tr>

  <tr>
    <td>2</td>
    <td>Non-ARM customer receipt</td>
    <td>The Corporate Customer receives a payment to their settlement account.</td>
    <td>
    <pre>
  {
    "account_identification": "014814800000010",
    "entry_reference": "Bill payment",
    "amount": "200.25",
    "debtor_name": "Andras Arato",
    "creditor_name": "Holden Holdings",
    "remittance_information": {
      "unstructured": [
        "Testing Non-ARM Customer"
      ]
    }
  }
    </pre>
    </td>
    <td>
    <pre>
  {
    "identification": "D942DD0B23674C3FBDC2702ECB0C837F",
    "creation_date_time": "2022-07-27T23:44:01.9842888+00:00",
    "account_identification": "014814800000010",
    "account_issuer": "014814",
    "entry": [
      {
        "related_parties": {
          "creditor_account_identification": "800000010",
          "creditor_account_issuer": "014814"
        }
      }
    ]
  }
    </pre>
    </td>
  </tr>

  <tr>
    <td>3</td>
    <td>Remittance information with emojis - binary</td>
    <td>Include any emoji in the remittance information</td>
    <td>
    <pre>
  {
    "account_identification": "014814800000010",
    "entry_reference": "Bill payment",
    "amount": "10.50",
    "debtor_name": "Andras Arato",
    "creditor_name": "Holden Holdings",
    "remittance_information": {
      "unstructured": [
        " Testing with emojis"
      ]
    }
  }
    </pre>
    </td>
    <td>
    <pre>
  {
    "identification": "D942DD0B23674C3FBDC2702ECB0C837F",
    "creation_date_time": "2022-07-27T23:44:01.9842888+00:00",
    "account_identification": "014814800000010",
    "account_issuer": "014814",
    "entry": [
      {
        "remittance_information": {
          "unstructured": [
            "&amp;#x1F600;&amp;#x1F680; Testing with emojis"
          ]
        }
      }
    ]
  }
    </pre>
    </td>
  </tr>
  
  <tr>
    <td>4</td>
    <td>Remittance information with emojis - NCR HEX code points</td>
    <td>Include any emoji in the remittance information</td>
    <td>
    <pre>
  {
    "account_identification": "014814800000010",
    "entry_reference": "Bill payment",
    "amount": "10.50",
    "debtor_name": "Andras Arato",
    "creditor_name": "Holden Holdings",
    "remittance_information": {
      "unstructured": [
        "&amp;#x1f6f8; TC-04 testing emoji"
      ]
    }
  }
    </pre>
    </td>
    <td>
    <pre>
  {
    "identification": "D942DD0B23674C3FBDC2702ECB0C837F",
    "creation_date_time": "2022-07-27T23:44:01.9842888+00:00",
    "account_identification": "014814800000010",
    "account_issuer": "014814",
    "entry": [
      {
        "remittance_information": {
          "unstructured": [
            "&amp;#x1f6f8; TC-04 testing emoji"
          ]
        }
      }
    ]
  }
    </pre>
    </td>
  </tr>
  
  <tr>
    <td>5</td>
    <td>Pay ID - Mobile</td>
    <td>The payer/debtor has used a Pay ID when making the payment to the Corporate Customer's account.</td>
    <td>
    <pre>
  {
    "account_identification": "014814800000010",
    "entry_reference": "Bill payment",
    "amount": "150.00",
    "debtor_name": "Andras Arato",
    "creditor_name": "Holden Holdings",
    "creditor_alias": {
      "type": "TELI",
      "identification": "+61403736550"
    },
    "remittance_information": {
      "unstructured": [
        "Testing with PayId"
      ]
    }
  }
    </pre>
    </td>
    <td>
    <pre>
  {
    "identification": "D942DD0B23674C3FBDC2702ECB0C837F",
    "creation_date_time": "2022-07-27T23:44:01.9842888+00:00",
    "account_identification": "014814800000010",
    "account_issuer": "014814",
    "entry": [
      {
        "related_parties": {
          "creditor_account_proxy": {
            "proxy_type": "TELI",
            "proxy_identification": "+61403736550"
          }
        }
      }
    ]
  }
    </pre>
    </td>
  </tr>
    
  <tr>
    <td>6</td>
    <td>Pay ID - eMail</td>
    <td>The payer/debtor has used a Pay ID when making the payment to the Corporate Customer's account.</td>
    <td>
    <pre>
  {
    "account_identification": "014814800000010",
    "entry_reference": "Bill payment",
    "amount": "150.00",
    "debtor_name": "Andras Arato",
    "creditor_name": "Holden Holdings",
    "creditor_alias": {
      "type": "EMAL",
      "identification": "npp@mail.com"
    },
    "remittance_information": {
      "unstructured": [
        "Testing with PayId"
      ]
    }
  }
    </pre>
    </td>
    <td>
    <pre>
  {
    "identification": "D942DD0B23674C3FBDC2702ECB0C837F",
    "creation_date_time": "2022-07-27T23:44:01.9842888+00:00",
    "account_identification": "014814800000010",
    "account_issuer": "014814",
    "entry": [
      {
        "related_parties": {
          "creditor_account_proxy": {
            "proxy_type": "EMAL",
            "proxy_identification": "npp@mail.com"
          }
        }
      }
    ]
  }
    </pre>
    </td>
  </tr>
    
  <tr>
    <td>7</td>
    <td>Return of Funds (PACS.004)</td>
    <td>The Corporate Customer is receiving a credit to their settlement account.</td>
    <td>
    <pre>
  {
    "account_identification": "014814800000010",
    "entry_reference": "Bill payment",
    "amount": "500.00",
    "debtor_name": "Andras Arato",
    "creditor_name": "Holden Holdings",
    "remittance_information": {
      "unstructured": [
        "Testing Return of Funds"
      ]
    },
    "return_information": {
      "reason_code": "NARR",
      "additional_information": [
        "Beneficiary is",
        "unknown"
      ]
    }
  }
    </pre>
    </td>
    <td>
    <pre>
  {
  "identification": "D942DD0B23674C3FBDC2702ECB0C837F",
  "creation_date_time": "2022-07-27T23:44:01.9842888+00:00",
  "account_identification": "014814800000010",
  "account_issuer": "014814",
  "entry": [
    {
      "return_information": {
        "reason": {
          "code": "NARR"
        },
        "additional_information": [
          "Beneficiary is",
          "unknown"
        ]
      }
    }
  ]
}
    </pre>
    </td>
  </tr>
      
  <tr>
    <td>8</td>
    <td>Duplicate Check</td>
    <td>ANZ to reposcess a previously sent Notification which the customer should not process.</td>
    <td>n/a</td>
    <td>ANZ will send a previously sent Notification which has the same account_servicer_reference.</td>
  </tr>

  <tr>
    <td>9</td>
    <td>Invalid API Key</td>
    <td>ANZ to update customer Notificaiton profile with incorrect API Key. Customer to reject  Notifications with invalid API key.</td>
    <td>Send a valid RTN request</td>
    <td>ANZ will send a well formed Notification which customer should reject with HTTP 401</td>
  </tr>
</tbody>
</table>

---
layout: detail
title: NPP Emoji handling
menu_key: fileactive-rtn
group: rtn
hero_key: rtn
---
[Question](#question) 

<h4 name="question" id="question"></h4>

**Question**

How are emoji's represented in NPP ?<br>
NPP has a 280 character requirement for payment description (narrative), does this mean 280 emoji's?

[Answer](#answer) 

<h4 name="answer" id="answer"></h4>

**Answer**

An emoji character is represented by one or more code points, when the encoding is UTF-8<br>
A character in UTF-8 is a "code point", therefore in NPP payments you must allow 280 code points.

[What does a code point look like](#point) 

<h4 name="point" id="point"></h4>

### What does a code point look like?

Taking the example of the "Family: Man, Woman, Girl, Boy" emoji: 👨‍👩‍👧‍👦 [https://emojipedia.org/family-man-woman-girl-boy/](https://emojipedia.org/family-man-woman-girl-boy/)

The emoji consists of 7 code points:

| # | Code Point |
|---|------------|
| 1 | 👨 U+1F468 |
| 2 | U+200D     |
| 3 | 👩 U+1F469 |
| 4 | U+200D     |
| 5 | 👧 U+1F467 |
| 6 | U+200D     |
| 7 | 👦 U+1F466 |

[Representing emoji's in JSON](#representing) 

<h4 name="representing" id="representing"></h4>

### Representing emoji's in JSON

A code point can be represented in binary or using Numerical Character Reference (NCR), for the example the "Family: Man, Woman, Girl, Boy" emoji:

```
- binary:         👨‍👩‍👧‍👦
- NCR (hex):      &#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;
- NCR (decimal):  &#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;
```

Note, the recommended representation is NCR (hex), however some NPP participants have used binary and NCR (decimal).  The recommendation is to send NCR (hex) and accept NCR (hex), NCR (decimal) and binary

Using the example of the NPP Real Time Notification schema, the unstructured array within the remittance_information object is:

```yaml
          remittance_information:
            type: object
            properties:
              unstructured:
                type: array
                description: >-
                  Information supplied to enable the matching/reconciliation of an entry 
                  with the items that the payment is intended to settle, such as commercial 
                  invoices in an accounts' receivable system, in an unstructured form.
                items:
                  type: string
                  minLength: 1
                  maxLength: 140
                minItems: 1
                maxItems: 2
```

When aligned to the NPP limit of 280 characters this corresponds to two unstructured fields each being a maximum of 140 characters. This means a maximum of 280 code points can be supported. For example:

```json
{
  "remittance_information": {
    "unstructured": [
      "abcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghij",
      "abcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghij"
    ]
  }
}
```

When using emoji's the string length is calculated using code points, therefore the unstructured array element is restricted to 140 code points.

[Sample JSON emoji's (NCR hex)](#jsonemoji) 

<h4 name="jsonemoji" id="jsonemoji"></h4>

###### Sample JSON Emoji's (NCR hex)

```json
{
  "remittance_information": {
    "unstructured": [
      "&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;",
      "&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;"
    ]
  }
}
```
[Sample JSON Emoji's (NCR decimal)](#decimal) 

<h4 name="decimal" id="decimal"></h4>

##### Sample JSON Emoji's (NCR decimal)

```json
{
  "remittance_information": {
    "unstructured": [
      "&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;",
      "&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;&#128104;&#8205;&#128105;&#8205;&#128103;&#8205;&#128102;"
    ]
  }
}
```
[Sample JSON Emoji's (binary)](#binary) 

<h4 name="binary" id="binary"></h4>

##### Sample JSON Emoji's (binary)

```json
{
  "remittance_information": {
    "unstructured": [
      "👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦",
      "👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦👨‍👩‍👧‍👦"
    ]
  }
}
```
[Mixing characters](#mixing-characters) 

<h4 name="mixing-characters" id="mixing-characters"></h4>

### Mixing characters

Note the 280 character limit allows for any combination of UTF-8 characters, for example the following are all valid 280 code point narratives:

[Mixed narrative](#mixednarrative) 

<h4 name="mixednarrative" id="mixednarrative"></h4>

##### Mixed Narrative

```
你好👨👨‍👩‍👧‍👦Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text 你好👨👨‍👩‍👧‍👦Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text
```
[Mixed narrative in NPP Real time notification ](#narrative) 

<h4 name="narrative" id="narrative"></h4>

##### Mixed Narrative in NPP Real Time Notification 

_Note: Chinese characters also converted to NCR (hex)_

```json
{
  "remittance_information": {
    "unstructured": [
      "&#x4F60;&#x597D;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text",
      "&#x4F60;&#x597D;&#x1F468;&#x200D;&#x1F469;&#x200D;&#x1F467;&#x200D;&#x1F466;Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text"
    ]
  }
}
```

---

Emoji handling

---
layout: detail
title: Real time notifications singapore code catalogue
menu_key: fileactive-rtn
group: rtn
hero_key: rtn
---
---

The Singapore FAST Real-Time Notification (RTN) service provides immediate updates for payment-related events within the Singapore FAST (Fast and Secure Transfers) system. This service is essential for businesses looking to enhance their payment processing workflows by receiving instant notifications for critical financial events such as payment initiations, completions, and failures.

---
[Key capabilities](#capabilities) 

<h4 name="capabilities" id="capabilities"></h4>

#### Key Capabilities:
- **Immediate Alerts:** Receive real-time notifications for payment events, enabling swift action and improved transaction monitoring.
- **Secure Communication:** All notifications are transmitted securely using HTTPS, ensuring the confidentiality and integrity of the data.
- **Subscription-Based Model:** Clients can subscribe to specific event types, allowing them to tailor the notifications they receive based on business needs.
- **High Scalability:** The RTN service is designed to support high transaction volumes, making it suitable for businesses of all sizes.

---

[Technical requirements](#requirements) 

<h4 name="requirements" id="requirements"></h4>

#### Technical Requirements:
- **Authentication:** Access to the RTN service requires OAuth 2.0 authentication with a bearer token, which is obtained via the Client Credential Grant flow.
- **Endpoints:** Notifications are delivered through dedicated endpoints configured to handle the various event types related to the FAST system.
- **Payload Structure:** Notifications are sent in JSON format, containing key details such as transaction IDs, timestamps, and status information.
- **Error Handling:** Implement robust error handling to manage scenarios where notifications fail to be delivered or processed.

---

[Key features for developers](#developers) 

<h4 name="developers" id="developers"></h4>

#### Key Features for Developers:
- **Webhook Integration:** RTN uses webhooks to push notifications directly to your application, eliminating the need for frequent polling and reducing latency.
- **Event Filtering:** Customize event subscriptions to receive only the notifications relevant to your business, improving the efficiency of your processes.
- **Built-in Retry Logic:** Notifications include retry mechanisms to ensure delivery, enhancing the reliability of the service even in the case of transient errors.
- **Security Compliance:** Each notification is digitally signed, and HTTPS is used for all communications, ensuring adherence to security best practices.

---

[Example use cases](#usecases) 

<h4 name="usecases" id="usecases"></h4>

#### Example Use Cases:
- **Automated Reconciliation:** Use real-time notifications to automatically update payment records in your system, streamlining reconciliation processes.
- **Customer Notifications:** Provide instant updates to customers regarding the status of their payments, enhancing service transparency and customer satisfaction.
- **Risk Management:** Monitor payment events in real-time to quickly identify and respond to potential issues, such as payment rejections or delays.

openapi: 3.0.1
info:
  title: Request A Real Time Notification Test API
  version: 1.0.3

servers:
  - url: https://api.fileactive.uat.anzgcis.com/testingfileactive/v1.0
    description: 'UAT (non-production) environment'
security:
  - apiKeyAuth: []
paths:
  /rtn:
    post:
      summary: Submit
      description: |-
        Request includes attributes which will be included in the RTN. All unspecified RTN fields will be defaulted  
      operationId: submitRTNRequest
      parameters:
        - $ref: '#/components/parameters/correlationID'
        - $ref: '#/components/parameters/messageID'
        - $ref: '#/components/parameters/apikey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestRTN'
            examples:
              SG FAST:
                value:
                  {
                    "hierarchy": "SG/PAYMENTS",
                    "postingBsb": "ANZBSGSXXXX",
                    "postingAcctNmbr": "148148000000333",
                    "acctBsb": "ANZBSGSXXXY",
                    "acctNmbr": "148148000000333",
                    "entry_reference": "MY BILL PAYMENT",
                    "amount": "121.5",
                    "puid": "PTM0000011111111",
                    "debtor_name": "MIKE SMITH",
                    "creditor_name": "MY BILLER",
                    "arm_creditor_account_identification": "148150000000111",
                    "remittance_information": {
                      "unstructured": [
                        "This is Singapore FAST RTN"
                      ]
                    } 
                  }
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201Created'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorised'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalError'
        '502':
          $ref: '#/components/responses/502BadGateway'
        '503':
          $ref: '#/components/responses/503Unavailable'
        '504':
          $ref: '#/components/responses/504Timeout'
        default:
          $ref: '#/components/responses/default'
components:
  parameters:
    correlationID:
      name: x-Correlation-Id
      in: header
      description: >-
        Optional correlation ID provided by the data consumer that should be
        reflected back in the response headers. Can be used for reporting and
        logging.
      schema:
        $ref: '#/components/schemas/UUID'
      example: 'baf7b2b0-449d-48c7-a63a-876e72cd7b02'
    messageID:
      name: x-Message-Id
      in: header
      description: >-
        Point to point reference, as assigned by the
        instructing party, and sent to the next party in the chain to
        unambiguously identify the message
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
      example: '3c40b28a-b902-477f-8400-6cb97d41cb06'
    apikey:
      name: apikey
      in: header
      description: >-
        API key to authorise requests.
      required: true
      example: 'BDmjSQDvOlZC5ExDfr3rf2GwFE1tWQ3D'      
    priority:
      name: priority
      in: header
      description: Priority (attended/unattended) to be included in any generated notification.
      required: true
      schema:
        $ref: '#/components/schemas/NotificationPriority1Code'
    priority2:
      name: priority
      in: header
      description: Priority (attended/unattended) to be included in any generated notification. <br><br> Only **UNATTENDED** is supported for this request type.
      required: true
      schema:
        $ref: '#/components/schemas/NotificationPriority2Code'    
  responses:
    201Created:
      description: Created, request was successful
      headers:
        x-Correlation-Id:
          description: GUID echoed from request. Example baf7b2b0-449d-48c7-a63a-876e72cd7b02
          schema:
            $ref: '#/components/schemas/UUID'
        x-RequestKey:
          description: Request Key provided to customer for support and reporting purposes. Example 7eda441d-5716-4f28-b5fe-d3dc7458d526
          schema:
            $ref: '#/components/schemas/UUID'
    400BadRequest:
      description: Bad Request, message format does not match expected schema
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorCode'
          example:
            status:
              code: EC000_003
              severity: Fatal
              text: The request failed validation {reason}
    401Unauthorised:
      description: Request is not authenticated
      content: {}
    403Forbidden:
      description: Request is authenticated but action is not allowed 
      content: 
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorCode'
          example:
            status:
              code: EC013_003
              severity: Fatal
              text: The provided account_identification = 013999012345678 is not authorised to receive real time notifications. Provide an authorised account or please contact support
    429TooManyRequests:
      description: Action exceeds allocated limits
      content: {}
    500InternalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorCode'
          example:
            status:
              code: EC000_001
              severity: Fatal
              text: Internal Server Error, please contact support
    502BadGateway:
      description: Bad Gateway, contact support
      content: {}
    503Unavailable:
      description: Service Unavailable or down for maintainance
      content: {}
    504Timeout:
      description: Gateway Timeout, retry or contact support
      content: {}
    default:
      description: Unexpected error
      content: {}
  schemas:
    NotificationPriority1Code:
      type: string
      description: |-
        Defines the notification priority.
        <table><tr><th>Code</th><th>Description</th></tr><tr><td>ATTENDED</td><td> Attended mode of operation.</td></tr><tr><td>UNATTENDED</td><td>Unattended mode of operation.</td></tr></table>
      enum:
      - ATTENDED
      - UNATTENDED
    NotificationPriority2Code:
      type: string
      description: |-
        Defines the notification priority.
        <table><tr><th>Code</th><th>Description</th></tr><tr><td>UNATTENDED</td><td>Unattended mode of operation.</td></tr></table>
      enum:
      - UNATTENDED
    RequestRTN:
      required:
      - entry_reference
      - amount
      type: object
      properties:
        account_identification:
          type: string
          description: >-
            Account identification assigned by an institution, includes BSB. 
            This field is not applicable for Singapore FAST
          minLength: 1
          maxLength: 34
          example: '014814800000010'
        entry_reference:
          type: string
          minLength: 1
          maxLength: 35
          description: Unique reference for the entry
          example: Reference entered in the initiating channel     
        amount:
          type: string
          description: Notified amount in AUD for NPP. This will be in SGD for Singapore FAST.
          minLength: 1
          maxLength: 19
          example: 7120.86
        puid:
          type: string
          minLength: 1
          maxLength: 16
          description: An optionally provided identifier which is returned in the requested RTN
          example: "PTM2022101389715"
        debtor_name:
          type: string
          minLength: 1
          maxLength: 140  
          description: Debtor (payer) account name 
          example: Andras Arato
        creditor_name:
          type: string
          minLength: 1
          maxLength: 140  
          description: Creditor (biller) account name 
          example: Holden Holdings
        arm_creditor_account_identification:
          type: string
          description: >-
            ARM(virtual)account identification, includes BSB for NPP. 
            Only has account number for SG FAST
          minLength: 1
          maxLength: 34
          example: '063678965323010'
        creditor_alias:
          required:
          - type
          - identification
          type: object
          description: Creditor account alias (Applicable for NPP only)
          properties:
            type:
              type: string
              enum:
                - 'TELI'
                - 'EMAL'
                - 'AUBN'
                - 'ORGN'
              description: Creditor account alias type
              example: 'TELI'
            identification:
              type: string
              description: Creditor account alias identification
              minLength: 1
              maxLength: 2048
              example: '+61403736550'
        remittance_information:
          type: object
          properties:
            unstructured:
              type: array
              description: >-
                Information supplied to enable the matching/reconciliation of an entry 
                with the items that the payment is intended to settle, such as commercial 
                invoices in an accounts receivable system, in an unstructured form.
              example: ['👨‍👩‍👧‍👦Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim a','d minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit i']
              items:
                type: string
                minLength: 1
                maxLength: 140
              minItems: 1
              maxItems: 2
        return_information:
          type: object
          description: Applicable only for NPP
          properties:
            reason_code:
              type: string
              description: Payment return reason code
              minLength: 4
              maxLength: 4
              example: NARR   
            additional_information:
              type: array
              description: Further details on the return reason  
              example: ['Beneficiary is','unknown']
              items:
                type: string
                minLength: 1
                maxLength: 105
              minItems: 1
              maxItems: 3
        hierarchy:
            type: string
            description: Always SG/PAYMENTS (Applicable for SG FAST only)
            minLength: 1
            maxLength: 11
            example: 'SG/PAYMENT'     
        postingBsb:
              type: string
              description: Will be the BIC where the funds were posted (Applicable for SG FAST only)
              minLength: 1
              maxLength: 11
              example: 'ANZBSGSXXXX'
        postingAcctNmbr:
              type: string
              description: will be the account number where the funds are posted (Applicable for SG FAST only)
              minLength: 1
              maxLength: 34
              example: '148148000000333'
        acctBsb:
                type: string
                description: Will be populated with the real/natural BIC or the virtual BIC (Applicable for SG FAST only)
                minLength: 1
                maxLength: 11
                example: 'ANZBSGSXXXY'
        acctNmbr:
              type: string
              description: Will be populated with the real/natural account number or the ARM/virtual account number (Applicable for SG FAST only)
              minLength: 1
              maxLength: 34
              example: '148148000000333'
    UUID:
      type: string
      pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
    ErrorCode:
      type: object
      properties: 
        status:
          type: object
          required:
          - code
          - severity
          - text
          properties:
            code:
              type: string
              example: EC000_001
            severity: 
              type: string
              enum:
                - Fatal
                - Transient
              example: Fatal
            text:
              type: string
              example: Internal Server Error, please contact support   

---
layout: code
title: Real time notification code SG FAST
menu_key: fileactive-rtn-sg
group: rtn
hero_key: fileactive
schema_spec: "/gcis/api-portal/fileactive/api/rtn/data/sg-rtn-api-schema.yaml"
testing_spec: "/gcis/api-portal/fileactive/api/rtn/data/testing-sg-rtn-api-schema.yaml"
overview_tab: "false"
payload_tab: "false"   
schema_tab: "true"
testing_tab: "true"
---

---
layout: detail
title: SG FAST RTN user acceptance testing scenarios
menu_key: fileactive-rtn
group: rtn
hero_key: rtn
---

---

[Question](#question) 

<h4 name="question" id="question"></h4>

**Question**

What UAT scenarios does ANZ recommend a customer complete prior to activating the SG FAST Real Time Notification service?

[Answer](#answer) 

<h4 name="answer" id="answer"></h4>

**Answer**

Using the Fileactive Self Service Testing API it is recommended a customer complete the following testing scenarios. <br><br>

<table>
    <thead>
  <tr>
    <th>#</th>
    <th>Scenario</th>
    <th>Description</th>
    <th>RTN Self-Service Request</th>
    <th>SG FAST Payment Notification Response Snipet</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>1</td>
    <td>Virtual account customer receipt</td>
    <td>The Corporate Customer is configured with a virtual account and receives a payment to their virtual account</td>
    <td>
    <pre>
  {
    "account_identification": "800000010",
    "entry_reference": "Trading transfer",
    "amount": "100.50",
    "debtor_name": "Andras Arato",
    "creditor_name": "Holden Holdings",,
    "arm_creditor_account_identification": "965323010",
    "remittance_information": {
      "unstructured": [
        "Testing Virtual account Customer"
      ]
    }
  }
    </pre>
    </td>
    <td>
    <pre>
  {
   "identification": "D942DD0B23674C3FBDC2702ECB0C837F",
   "creation_date_time": "2022-07-27T23:44:01.9842888+00:00",
    "account_identification": "014814800000010",
   "account_issuer": "ANZBSGSXXXX",
    "entry": [
     {
       "related_parties": {
         "creditor_account_identification": "965323010",
         "creditor_account_issuer": "ANZBSGSXXXX"
      }
    }
  ]
}
    </pre>
    </td>
  </tr>

  <tr>
    <td>2</td>
    <td>Non-Virtual account customer receipt</td>
    <td>The Corporate Customer receives a payment to their settlement account.</td>
    <td>
    <pre>
  {
    "account_identification": "800000010",
    "entry_reference": "Bill payment",
    "amount": "200.25",
    "debtor_name": "Andras Arato",
    "creditor_name": "Holden Holdings",
    "remittance_information": {
      "unstructured": [
        "Testing Non-ARM Customer"
    ]
  }
}
    </pre>
    </td>
    <td>
    <pre>
  {
    "identification": "D942DD0B23674C3FBDC2702ECB0C837F",
    "creation_date_time": "2022-07-27T23:44:01.9842888+00:00",
    "account_identification": "800000010",
    "account_issuer": "ANZBSGSXXXX",
    "entry": [
      {
       "related_parties": {
          "creditor_account_identification": "800000010",
          "creditor_account_issuer": "ANZBSGSXXXX"
      }
    }
  ]
}
    </pre>
    </td>
  </tr>

  <tr>
    <td>3</td>
    <td>Duplicate Check</td>
    <td>ANZ to reprocess a previously sent Notification which the customer should not process</td>
    <td>n/a</td>
    <td>ANZ will send a previously sent Notification which has the same account_servicer_reference</td>
  </tr>

  <tr>
    <td>4</td>
    <td>Invalid API Key</td>
    <td>ANZ to update customer Notificaiton profile with incorrect API Key. Customer to reject Notifications with invalid API key</td>
    <td>Send a valid RTN request</td>
    <td>ANZ will send a well formed Notification which customer should reject with HTTP 40</td>
  </tr>
</tbody>
</table>

---
layout: detail
title: Real time notifications API code catalogue
menu_key: fileactive-rtn
group: rtn
hero_key: rtn
---
---

[Real-Time notifications for NPP RTN and Singapore FAST inward](#singaporefast) 

<h4 name="singaporefast" id="singaporefast"></h4>

#### Real-Time notifications for NPP RTN and Singapore FAST inward

The Real-Time Notifications (RTN) API for NPP (New Payments Platform) and Singapore FAST Inward provides developers with immediate updates on key payment events. These notifications are designed to keep your systems synchronized with the latest payment statuses, enhancing the responsiveness of your applications without the need for continuous polling.

---

[Key features](#keyfeatures) 

<h4 name="keyfeatures" id="keyfeatures"></h4>

#### Key features:

- **Instant event notifications:** Receive real-time updates when payments are credited to a customer’s bank account via NPP in Australia or Singapore FAST Inward.

- **Supported events:**
  - **NPP payment settlement:** Notification when funds are credited to an ANZ account via NPP.

  - **Singapore FAST inward payment:** Notification when funds are received via Singapore FAST Inward.

- **Secure and reliable:** Notifications are delivered securely with JWT signatures, ensuring the authenticity and integrity of the data received.

---

[Integration overview](#integrationoverview) 

<h4 name="integrationoverview" id="integrationoverview"></h4>

#### Integration overview:

**Webhook setup:** Configure your webhook endpoint to receive real-time notifications from ANZ via the Fileactive API. Ensure your endpoint is HTTPS-secured.

**Notification verification:** Each notification includes a JWT signature. Verify this signature to confirm the authenticity of the notification.

**Processing logic:** Implement logic to process the notifications and update your application state accordingly.

**Acknowledge receipt:** Respond to each notification with a 200 OK status to acknowledge receipt.

---

[Real-Time notification flow](#notificationflow) 

<h4 name="notificationflow" id="notificationflow"></h4>

#### Real-Time notification flow

The diagram below illustrates the flow of notifications for NPP RTN and Singapore FAST Inward, where ANZ receives inward notifications and forwards them to the customer's API endpoints:

---
<div class="mermaid">
sequenceDiagram
    participant ANZ
    participant CustomerEndpoint as Customer's Endpoint
    participant Application

    %% Payment Notification Flow
    ANZ->>CustomerEndpoint: POST Payment Notification (JWT Signature)
    CustomerEndpoint->>Application: Process Payment Notification
    Application-->>CustomerEndpoint: 200 OK (Acknowledgement)
</div>

---

---
layout: code
title: Authentication
menu_key: auth
group: fx
hero_key: fx
payload_spec: "/fx/api/data/auth-api-payload.yaml"
schema_spec: "/fx/api/data/auth-api-schema.yaml"
overview_tab: "true"
payload_tab: "true"   
schema_tab: "false"
---
&nbsp;

To interact with the ANZ Fileactive FX RFQ Pricing Service, authentication is managed via OAuth 2.0 using the Client Credential Grant flow. This method ensures secure access by obtaining a bearer token, which is then used for authorizing API requests within the FX RFQ service.

[Key points](#access) 

<h4 name="access" id="access"></h4>

#### Key Points:
- **Endpoint:** Authentication requests should be directed to the `/v1.0/auth` endpoint.
- **Grant Type:** Use `client_credentials` as the grant type to acquire tokens.
- **Token URL:** The token URL is `https://api.fileactive.anzgcis.com/v1.0/auth`.
- **Scopes:** Specific scopes define access permissions, such as:
  - `FX.RFQ.CREATE` - For creating FX RFQ (Request for Quote) resources.
  - `FX.RFQ.READ` - For retrieving FX RFQ details.
  - `FX.DEAL.CREATE` - For creating FX Deal resources.
  - `FX.DEAL.READ` - For retrieving FX Deal details.
- **Headers:** Include an API key in the request header using `apikey` as the parameter name.

[Example request](#send) 

<h4 name="send" id="send"></h4>

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

```http
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=FX.RFQ.CREATE&
client_assertion=<your_client_assertion_here>
```

[Example response](#receive) 

<h4 name="receive" id="receive"></h4>

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

```json
{
  "expires_in": 3600,
  "token_type": "Bearer",
  "access_token": "eaaa13ee-b596-a8cc-b9d4-f778f8bb9377"
}
```
[Usage notes](#expire) 

<h4 name="expire" id="expire"></h4>

#### 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](#field) 

<h4 name="field" id="field"></h4>

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

openapi: 3.0.1
info:
    title: Fileactive Authentication API
    version: 2.1.0
servers:
  - url: https://api.fileactive.uat.anzgcis.com
    description: 'UAT (non-production) environment'
  - url: https://api.fileactive.anzgcis.com
    description: 'Production Environment'
security:
  - bearerAuth: []
    apiKeyAuth: []
paths:
  /v1.0/auth:
    post:
      security:
          - apiKeyAuth: []
            oAuth2: []
      summary: Obtain authorisation token
      description: >
        ANZ use OAuth 2.0 to authenticate inbound token requests, a bearer token is returned as a response which is then used to authorise against ANZ resources
      operationId: auth
      requestBody:
        description: 'Information and examples of Auth request body'
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/authTokenRequest'
      responses:
        200:
          $ref: '#/components/responses/200OKAuth'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        502:
          $ref: '#/components/responses/502Auth'
        default:
          $ref: '#/components/responses/default'  
components:
  securitySchemes:
    bearerAuth:            
          type: http
          scheme: bearer
          bearerFormat: uuid
          description: Bearer token obtained during token exchange
    apiKeyAuth:        
      type: apiKey
      in: header
      name: apikey
      description: API key to authorise requests.
    oAuth2:
      type: oauth2
      flows:
        clientCredentials:  
          tokenUrl: https://api.fileactive.anzgcis.com/v1.0/auth
          scopes:
            GBL.INSTO.FX.RFQ: Request FX Quote and create FX Deal
  parameters:
    requestKey:
      name: X-RequestKey
      in: header
      description: Internal End to End key used for support and reporting purposes
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275
  responses:
    200OKAuth:
        description: 'Bearer token (Opaque Token) returned after a token request'
        headers:
          x-RequestKey:
            schema:
              $ref: '#/components/parameters/requestKey'
        content: 
          application/json:
            schema:
             $ref: '#/components/schemas/authTokenResponse'
    400:
        description: Bad Request, message format does not match expected schema
    401:
      description: Application is not unauthorised to perform a specific action
    429:
      description: Action exceeds allocated limits
    500:
      description: Internal Server Error, contact support
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    502Auth:
        description: Bad Gateway, contact support
    default:
      description: Internal Server Error, Bad Request/Syntactically incorrect
            etc.,
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    authTokenRequest:
      required:
      - grant_type
      - client_assertion_type
      - scope
      - client_assertion
      type: object
      properties:
        grant_type:
          description: Specify the type credential requested
          type: string
          example: 'client_credentials'
        client_assertion_type:
          description: Describes the type of client assertion provided in the message request
          type: string
          example: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
        scope:
          $ref: '#/components/securitySchemes/oAuth2/flows/clientCredentials/scopes'
        client_assertion:
          $ref: '#/components/schemas/ClientAssertion'
    authTokenResponse:
      type: object
      description: Response to report the status of a customer credit transfer.
      additionalProperties: false
      properties:
        expires_in:
          description: Indication on how long a token is valid for
          type: integer
        token_type: 
          description: Type of token returned
          type: string
        access_token:
          description: Opaque token returned as part of request, Fileactve does not provide the full access token
          type: string   
      example:
        expires_in: 3600
        token_type: 'Bearer'
        access_token: 'eaaa13ee-b596-a8cc-b9d4-f778f8bb9377'
    ClientAssertion:
        required:
        - sub
        - exp
        - aud
        type: object
        properties:
          sub:
            type: string
            description: Customer Code as provided by ANZ onboarding
            example: 'CUSTOMERA'
          exp:
            type: integer
            description: EPOCH date and time
            example: '1619658591'
            maxLength: 10
            minLength: 10
          aud:
            type: string
            description: Specify the intended audience of the token request
            example: 'https://api.fileactive.anzgcis.com/auth'
    ErrorDetail:
      type: object
      properties:
        severity:
          type: string
          description: Severity of the error
          enum:
            - Fatal
            - Transient
          example: Fatal
        code:
          type: string
          description: |
            Error code (format: ECxxx_xxx)
          example: EC014_003
        text:
          type: string
          description: Human readable description of the error
          example: Internal Server Error, please contact support.
    ErrorResponse:
      type: object
      required:
      - status
      properties:
        status:
          type: object
          description: Summary of the error
          $ref: '#/components/schemas/ErrorDetail'
    UUID:
        type: string
        example: '71d6fb19-7515-40dc-b045-e17550b67600'
        pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'

---
layout: detail
title: Submit and poll for FX quotes
menu_key: "quote"
group: fx
hero_key: fx

---
---
[Submit and poll for FX quotes](#allows) 

<h4 name="allows" id="allows"></h4>

#### Submit and poll for FX Quotes

The "Request a Quote" operation allows developers to submit an asynchronous Request for Quote (RFQ) for foreign exchange (FX) transactions through the ANZ Fileactive FX RFQ Pricing Service. This API call initiates the quote process by submitting FX trade parameters, enabling users to receive a quote for a specific currency pair.

---

[Key points](#access) 

<h4 name="access" id="access"></h4>

#### Key Points:
- **Endpoint:** Submit requests to the `/fx/v1.0/quotes/{country-code}` endpoint.
- **Method:** `POST`
- **authorisation:** Requires a valid bearer token obtained via OAuth 2.0, included in the `authorisation` header as `Bearer <access_token>`.
- **Headers:**
  - `X-Correlation-Id` (optional): A unique identifier for tracking requests across services.
  - `X-Message-Id` (required): A unique identifier for duplicate checks and traceability.
- **Request Body:** The request body should be in JSON format and include details such as:
  - `customerExternalIdentifier` (string): A customer-specific identifier used for internal tracking.
  - `channelTransactionIdentifier` (string, required): A unique identifier for the quote request, provided by the initiating channel.
  - `currencyPair` (string): The currency pair for which the quote is requested (e.g., "AUD/USD").
  - `requestLegs` (array, required): Specifies the details of the FX trade legs.

---

[Example request](#send) 

<h4 name="send" id="send"></h4>

#### Example Request:
```http
POST /fx/v1.0/quotes/NZ HTTP/1.1
Host: api.fileactive.anzgcis.com
authorisation: Bearer <access_token>
Content-Type: application/json
X-Message-Id: 71d6fb19-7515-40dc-b045-e17550b67600

{
  "customerExternalIdentifier": "CRN0000000001",
  "channelTransactionIdentifier": "0123456789",
  "currencyPair": "AUD/USD",
  "requestLegs": [
    {
      // Request leg details
    }
  ]
}
```

---

[Example response](#receive) 

<h4 name="receive" id="receive"></h4>

### Example Response:
On success, the service will acknowledge the quote request with a `202 Accepted` status, and a unique quote identifier will be issued for tracking.

```json
{
  "channelTransactionIdentifier": "0123456789",
  "quoteIdentifier": "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed",
  "status": "ACCEPTED"
}
```

---

[Usage notes](#expire) 

<h4 name="expire" id="expire"></h4>

### Usage Notes:
- **Tracking:** Use the `quoteIdentifier` from the response to track the status of the RFQ and for any further actions, such as polling for the response or accepting the quote.
- **Error Handling:** Ensure to handle common HTTP errors such as:
  - **400 Bad Request:** Malformed requests.
  - **401 Unauthorised:** Missing or invalid tokens.
  - **503 Service Unavailable:** If the service is down.

openapi: '3.0.0'
info:
  title:  Submit Quote Request API Payload
  version: 1.3.0
servers:
  - url: https://api.fileactive.uat.anzgcis.com
    description: 'UAT (non-production) environment'
  - url: https://api.fileactive.anzgcis.com
    description: 'Production Environment'
paths:
  /fx/v1.0/quotes/{country-code}:
    post:
      summary: Submit an asynchronous request for a new quote
      description: This endpoint is be used to submit a RFQ (request for quote).
      operationId: submitQuoteRequest
      parameters:
        - $ref: '#/components/parameters/correlationID'
        - $ref: '#/components/parameters/messageID'
        - $ref: '#/components/parameters/countryCode'
      requestBody:
        description: A request for quote object
        required: true
        content:
          application/json:
            schema: 
              $ref: '#/components/schemas/ClientQuoteRequest'
      responses:
        202:
          description: Accepted the request for quote ('RFQ')
          $ref: '#/components/responses/202'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401' 
        403:
          description: Country code parameter is invalid for has not been configured
          $ref: '#/components/responses/403'
        422:
          description: 'RFQ not accepted: Failed Business Rule'
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
        502:
          description: 'Request failure: Bad Gateway i.e, one or more of the downstream services is unavailable'
          $ref: '#/components/responses/502'
        503:
          $ref: '#/components/responses/503'
        default:
          description: Internal Server Error, Bad Request/Syntactically incorrect etc.,
          $ref: '#/components/responses/default'
      security:
        - bearerAuth: [GBL.INSTO.FX.RFQ]
          apiKeyAuth: []
components:
  parameters:
    correlationID:  
      name: X-Correlation-Id
      in: header
      description: Optional correlation ID provided by the data consumer that should
        be reflected back in the response headers. Can be used for reporting and
        logging.
      schema:
        $ref: '#/components/schemas/UUID'
    countryCode:
      name: country-code
      in: path
      required: true
      description: ISO 3166, Alpha-2 country code
      schema:
        type: string
        enum:
          - NZ
    messageID:
      name: X-Message-Id
      in: header
      description: Duplicate check using point to point reference, as assigned by
        the instructing party, and sent to the next party in the chain to unambiguously
        identify the message
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    quoteIdentifier:
      name: quoteIdentifier
      in: path
      description: A unique id provided by this service to identify a quote. MUST be
        provided in any further interactions (Polling, Acceptance, Declination, Cancellation)
      required: true
      schema:
        $ref: '#/components/schemas/QuoteIdentifier'
    requestKey:
      name: X-RequestKey
      in: header
      description: Internal End to End key used for support and reporting purposes
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275
  responses:
    200Quote:
      description: The response polled for is available and the business outcome is affirmative i.e., quote was issued
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/fx/v1.0/quotes/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientQuoteResponse'
    202:
      description: Accepted the request for quote ('RFQ') or request for deal
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/fx/v1.0/quotes/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    400:
        description: Bad Request, message format does not match expected schema
    401:
      description: Application is not unauthorised to perform a specific action
    403:
      description: Action is not authorised using current authentication credentials
    404:
      description: The response polled for is not yet available.
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/payments/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    422:
      description: 'RFQ or Deal request not accepted: Failed Business Rule; or the response polled for is unknown'
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    500:
      description: Internal Server Error, contact support
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    502:
      description: 'Request failure: Bad Gateway i.e, one or more of the downstream
            services is unavailable'
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    503:
      description: Service Unavailable
    default:
      description: Internal Server Error, Bad Request/Syntactically incorrect
            etc.,
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ClientQuoteRequest:
      type: object
      required:
      - channelTransactionIdentifier
      - requestLegs
      properties:
        customerExternalIdentifier:
          type: string
          description: A customer identifier that will be purely used for MIS purposes.
          example: CRN0000000001
        channelTransactionIdentifier:
          type: string
          description: An id used by a channel to uniquely identify it's quote request.
          example: "0123456789"
        currencyPair:
          type: string
          description: A valid currency pair, based on market convention and verified
            by pricing engine.
          pattern: ^[A-Z]{3}[/][A-Z]{3}$
          example: AUD/USD
        parentDealSourceSystem:
          type: string
          description: Parent deal source system. When provided, parentDealId must also
            be provided.
          example: ABCDEF
        parentDealId:
          type: string
          description: Parent deal id. When provided, parentDealSourceSystem must also
            be provided.
          example: "123456789"
        auxiliaryType:
          type: string
          description: Auxiliary type
          example: HR_EXT
        requestLegs:
          type: array
          minItems: 1
          maxItems: 2
          items:
            $ref: '#/components/schemas/RequestLeg'
    ClientQuoteResponse:
      type: object
      required:
      - channelTransactionIdentifier
      - quoteIdentifier
      - currencyPair
      - responseLegs
      - quoteExpiry
      - securityType
      properties:
        channelTransactionIdentifier:
          type: string
          description: Echoed from request
          example: "CRN123456789"
        quoteIdentifier:
          type: string
          description: A unique id generated by this service to identify a quote. This
            MUST be provided in any further interactions (Polling, Acceptance, Declination,
            Cancellation)
          example: "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed"
        currencyPair:
          type: string
          example: AUD/USD
          pattern: ^[A-Z]{3}[/][A-Z]{3}$
        swapPoints:
          type: number
          format: int32
          example: "1.3"
          description: Number of basis points between near and far leg. Signed and scaled.
        quoteExpiry:
          type: string
          format: date-time
          description: Timestamp in UTC.
          example: "2019-12-31T11:59:59Z"
        securityType:
          type: string
          description: Security that this Quote represents.
          example: HR_EXT
        responseLegs:
          type: array
          minItems: 1
          maxItems: 2
          items:
            $ref: '#/components/schemas/ResponseLeg'
    ErrorDetail:
      type: object
      properties:
        severity:
          type: string
          description: Severity of the error
          enum:
            - Fatal
            - Transient
          example: Fatal
        code:
          type: string
          description: |
            Error code (format: ECxxx_xxx)
          example: EC014_003
        text:
          type: string
          description: Human readable description of the error
          example: Internal Server Error, please contact support.
    ErrorResponse:
      type: object
      required:
      - status
      properties:
        status:
          type: object
          description: Summary of the error
          $ref: '#/components/schemas/ErrorDetail'
    QuoteIdentifier:
      description: A unique id provided by this service to identify a quote.
      type: string
      example: "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed"
    RequestLeg:
      type: object
      required:
      - customerBuyCurrency
      - customerSellCurrency
      properties:
        customerBuyCurrency:
          type: string
          description: Valid ISO Currency Code
          example: USD
          pattern: ^[A-Z]{3}$
        customerSellCurrency:
          type: string
          description: Valid ISO Currency Code
          example: USD
          pattern: ^[A-Z]{3}$
        customerBuyAmount:
          type: number
          format: int32
          description: Amount to Buy. Only one of either customerBuyAmount or customerSellAmount
            has to be provided.
          example: "10000"
        customerSellAmount:
          type: number
          description: Sell amount. Only one of either customerBuyAmount or customerSellAmount
            has to be provided.
          format: int32
          example: "10000"
        valueDate:
          type: string
          format: date
          description: Absence of this field implies a TODAY/TOM; adjusted for Ccy holidays
          example: "2020-05-31"
    ResponseLeg:
      type: object
      required:
      - customerBuyAmount
      - customerBuyAmountDps
      - customerBuyCurrency
      - customerSellAmount
      - customerSellAmountDps
      - customerSellCurrency
      - valueDate
      - customerDealtCurrency
      - customerAllInRate
      - customerAllInRateDps
      properties:
        customerBuyAmount:
          type: number
          format: int32
          example: "1000.00"
        customerBuyAmountDps:
          type: integer
          format: int32
          example: "2"
        customerBuyCurrency:
          type: string
          example: USD
          pattern: ^[A-Z]{3}$
        customerSellAmount:
          type: number
          format: int32
          example: "1250.50"
        customerSellAmountDps:
          type: integer
          format: int32
          example: "2"
        customerSellCurrency:
          type: string
          example: AUD
          pattern: ^[A-Z]{3}$
        customerDealtCurrency:
          type: string
          example: USD
        valueDate:
          type: string
          format: date
          example: "2020-05-31"
        customerAllInRate:
          type: number
          format: int32
          example: "0.68712"
        customerAllInRateDps:
          type: integer
          format: int32
          example: "5"
        customerSpotPrice:
          type: number
          nullable: true
          format: int32
          example: "0.6871"
        customerSpotPriceDps:
          type: integer
          nullable: true
          format: int32
          example: "4"
        customerForwardPoints:
          type: number
          nullable: true
          format: int32
          example: "0.2"
          description: Signed adjustment to Spot Rate in basis (scaled) points.
        customerForwardPtDps:
          type: integer
          nullable: true
          format: int32
          example: "1"
        legType:
          type: string
          nullable: true
          enum:
            - NEAR-LEG
            - FAR-LEG
            - OFFSET
          description: The type that this leg represents.
    StatusUpdateResponse:
      type: object
      required:
      - status
      - text
      properties:
        channelTransactionIdentifier:
          type: string
          description: Echoed from request when available and if quoteIdentifier is
            not provided.
        quoteIdentifier:
          type: string
          description: Echoed from request when available
        status:
          type: string
          enum:
          - ACCEPTED
          - IN PROGRESS
          - CANCELLED
          - DECLINED
          - FAILED
          - REJECTED
          - EXPIRED
          - DEALER INTERVENTION
          - NOT PERMISSIONED
          - NOT IMPLEMENTED
          - NOT SUPPORTED
        text:
          type: string
          description: Additional text for elaborating on the status.
          example: Bad Gateway
    UUID:
        type: string
        example: '71d6fb19-7515-40dc-b045-e17550b67600'
        pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'

---
layout: code
title: Submit a RFQ (Request for quote).
menu_key: "submit"
group: fx
hero_key: fx
payload_spec: "/gcis/api-portal/fx/api/data/quote-submit-api-payload.yaml"
schema_spec: "/gcis/api-portal/fx/api/data/quote-submit-api-schema.yaml"
overview_tab: "true"
payload_tab: "true"   
schema_tab: "false"
---

&nbsp;

The **Submit a New Quote** endpoint allows developers to request a new foreign exchange quote asynchronously. This operation is essential for initiating the RFQ (Request for Quote) process, which can be used to obtain competitive pricing for FX transactions. Upon submission, the system processes the request and returns a unique quote identifier, enabling further interactions such as polling for the quote's status or accepting the quote.

---

[Key points](#access) 

<h4 name="access" id="access"></h4>

#### Key Points:
- **Endpoint:** `POST /fx/v1.0/quotes/{country-code}`

- **Purpose:** To initiate a new quote request for a specified currency pair.

- **Asynchronous Process:** The quote request is processed asynchronously, allowing for efficient handling of large volumes of requests.

- **authorisation:** Requires a bearer token obtained via OAuth 2.0 to authorise the request.

---

[Request details](#details) 

<h4 name="details" id="details"></h4>

#### Request Details:
- **Headers:**
  - `authorisation: Bearer <access_token>` - Include the bearer token for authorisation.

  - `X-Correlation-Id` (Optional) - Used for tracing and logging purposes.

  - `X-Message-Id` (Required) - Ensures unique identification of each request to avoid duplicates.

- **Body Parameters:**
  - `customerExternalIdentifier` - A unique identifier for the customer, used for MIS purposes.

  - `channelTransactionIdentifier` - An identifier used by the channel to uniquely identify the quote request.

  - `currencyPair` - A valid currency pair, following market conventions and verified by the pricing engine.

  - Additional fields may include details about the parent deal and auxiliary types, depending on the specific use case.

---

[Example response](#receive) 

<h4 name="receive" id="receive"></h4>

#### Example Response:
On success, the service will acknowledge the quote request with a `202 Accepted` status, and a unique quote identifier will be issued for tracking.

```json
{
  "channelTransactionIdentifier": "0123456789",
  "quoteIdentifier": "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed",
  "status": "ACCEPTED"
}
```

---

[Usage notes](#expire) 

<h4 name="expire" id="expire"></h4>

### Usage Notes:

- **Tracking:** Use the `quoteIdentifier` from the response to track the status of the RFQ and for any further actions, such as polling for the response or accepting the quote.

- **Error Handling:** Ensure to handle common HTTP errors such as:
  - **400 Bad Request:** Malformed requests.
  - **401 Unauthorised:** Missing or invalid tokens.
  - **503 Service Unavailable:** If the service is down.

Submit

openapi: '3.0.0'
info:
  title:  Response Poll API Payload
  version: 1.3.0
servers:
  - url: https://api.fileactive.uat.anzgcis.com
    description: 'UAT (non-production) environment'
  - url: https://api.fileactive.anzgcis.com
    description: 'Production Environment'
paths:
  /fx/v1.0/quotes/{quoteIdentifier}:
    get:
      summary: Poll for the response corresponding to a submitted RFQ
      description: This endpoint is used to poll for the business outcome/result of a submitted RFQ.
      tags:
        - FX RFQ Pricing Service
      operationId: pollQuoteResponse
      parameters:
        - $ref: '#/components/parameters/correlationID'
        - $ref: '#/components/parameters/messageID'
        - $ref: '#/components/parameters/quoteIdentifier'
      responses:
        200:
          description: The response polled for is available and the business outcome is affirmative i.e., quote was issued
          $ref: '#/components/responses/200Quote'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401' 
        404:
          description: The response polled for is not yet available.
          $ref: '#/components/responses/404'
        422:
          description: The response polled for is available and the business outcome is not affirmative or is unknown
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
        502:
          description: 'Request failure: Bad Gateway i.e, one or more of the downstream services is unavailable'
          $ref: '#/components/responses/502'
        503:
          $ref: '#/components/responses/503'
        default:
          description: Internal Server Error, Bad Request/Syntactically incorrect request etc.,
          $ref: '#/components/responses/default'
      security:
        - bearerAuth: [GBL.INSTO.FX.RFQ]
          apiKeyAuth: []
components:
  parameters:
    correlationID:  
      name: X-Correlation-Id
      in: header
      description: Optional correlation ID provided by the data consumer that should
        be reflected back in the response headers. Can be used for reporting and
        logging.
      schema:
        $ref: '#/components/schemas/UUID'
    countryCode:
      name: country-code
      in: path
      required: true
      description: ISO 3166, Alpha-2 country code
      schema:
        type: string
        enum:
          - NZ
    messageID:
      name: X-Message-Id
      in: header
      description: Duplicate check using point to point reference, as assigned by
        the instructing party, and sent to the next party in the chain to unambiguously
        identify the message
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    quoteIdentifier:
      name: quoteIdentifier
      in: path
      description: A unique id provided by this service to identify a quote. MUST be
        provided in any further interactions (Polling, Acceptance, Declination, Cancellation)
      required: true
      schema:
        $ref: '#/components/schemas/QuoteIdentifier'
    requestKey:
      name: X-RequestKey
      in: header
      description: Internal End to End key used for support and reporting purposes
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275
  responses:
    200Quote:
      description: The response polled for is available and the business outcome is affirmative i.e., quote was issued
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/fx/v1.0/quotes/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientQuoteResponse'
    202:
      description: Accepted the request for quote ('RFQ') or request for deal
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/fx/v1.0/quotes/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    400:
        description: Bad Request, message format does not match expected schema
    401:
      description: Application is not unauthorised to perform a specific action
    403:
      description: Action is not authorised using current authentication credentials
    404:
      description: The response polled for is not yet available.
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/payments/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    422:
      description: 'RFQ or Deal request not accepted: Failed Business Rule; or the response polled for is unknown'
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    500:
      description: Internal Server Error, contact support
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    502:
      description: 'Request failure: Bad Gateway i.e, one or more of the downstream
            services is unavailable'
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    503:
      description: Service Unavailable
    default:
      description: Internal Server Error, Bad Request/Syntactically incorrect
            etc.,
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ClientQuoteRequest:
      type: object
      required:
      - channelTransactionIdentifier
      - requestLegs
      properties:
        customerExternalIdentifier:
          type: string
          description: A customer identifier that will be purely used for MIS purposes.
          example: CRN0000000001
        channelTransactionIdentifier:
          type: string
          description: An id used by a channel to uniquely identify it's quote request.
          example: "0123456789"
        currencyPair:
          type: string
          description: A valid currency pair, based on market convention and verified
            by pricing engine.
          pattern: ^[A-Z]{3}[/][A-Z]{3}$
          example: AUD/USD
        parentDealSourceSystem:
          type: string
          description: Parent deal source system. When provided, parentDealId must also
            be provided.
          example: ABCDEF
        parentDealId:
          type: string
          description: Parent deal id. When provided, parentDealSourceSystem must also
            be provided.
          example: "123456789"
        auxiliaryType:
          type: string
          description: Auxiliary type
          example: HR_EXT
        requestLegs:
          type: array
          minItems: 1
          maxItems: 2
          items:
            $ref: '#/components/schemas/RequestLeg'
    ClientQuoteResponse:
      type: object
      required:
      - channelTransactionIdentifier
      - quoteIdentifier
      - currencyPair
      - responseLegs
      - quoteExpiry
      - securityType
      properties:
        channelTransactionIdentifier:
          type: string
          description: Echoed from request
          example: "CRN123456789"
        quoteIdentifier:
          type: string
          description: A unique id generated by this service to identify a quote. This
            MUST be provided in any further interactions (Polling, Acceptance, Declination,
            Cancellation)
          example: "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed"
        currencyPair:
          type: string
          example: AUD/USD
          pattern: ^[A-Z]{3}[/][A-Z]{3}$
        swapPoints:
          type: number
          format: int32
          example: "1.3"
          description: Number of basis points between near and far leg. Signed and scaled.
        quoteExpiry:
          type: string
          format: date-time
          description: Timestamp in UTC.
          example: "2019-12-31T11:59:59Z"
        securityType:
          type: string
          description: Security that this Quote represents.
          example: HR_EXT
        responseLegs:
          type: array
          minItems: 1
          maxItems: 2
          items:
            $ref: '#/components/schemas/ResponseLeg'
    ErrorDetail:
      type: object
      properties:
        severity:
          type: string
          description: Severity of the error
          enum:
            - Fatal
            - Transient
          example: Fatal
        code:
          type: string
          description: |
            Error code (format: ECxxx_xxx)
          example: EC014_003
        text:
          type: string
          description: Human readable description of the error
          example: Internal Server Error, please contact support.
    ErrorResponse:
      type: object
      required:
      - status
      properties:
        status:
          type: object
          description: Summary of the error
          $ref: '#/components/schemas/ErrorDetail'
    QuoteIdentifier:
      description: A unique id provided by this service to identify a quote.
      type: string
      example: "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed"
    RequestLeg:
      type: object
      required:
      - customerBuyCurrency
      - customerSellCurrency
      properties:
        customerBuyCurrency:
          type: string
          description: Valid ISO Currency Code
          example: USD
          pattern: ^[A-Z]{3}$
        customerSellCurrency:
          type: string
          description: Valid ISO Currency Code
          example: USD
          pattern: ^[A-Z]{3}$
        customerBuyAmount:
          type: number
          format: int32
          description: Amount to Buy. Only one of either customerBuyAmount or customerSellAmount
            has to be provided.
          example: "10000"
        customerSellAmount:
          type: number
          description: Sell amount. Only one of either customerBuyAmount or customerSellAmount
            has to be provided.
          format: int32
          example: "10000"
        valueDate:
          type: string
          format: date
          description: Absence of this field implies a TODAY/TOM; adjusted for Ccy holidays
          example: "2020-05-31"
    ResponseLeg:
      type: object
      required:
      - customerBuyAmount
      - customerBuyAmountDps
      - customerBuyCurrency
      - customerSellAmount
      - customerSellAmountDps
      - customerSellCurrency
      - valueDate
      - customerDealtCurrency
      - customerAllInRate
      - customerAllInRateDps
      properties:
        customerBuyAmount:
          type: number
          format: int32
          example: "1000.00"
        customerBuyAmountDps:
          type: integer
          format: int32
          example: "2"
        customerBuyCurrency:
          type: string
          example: USD
          pattern: ^[A-Z]{3}$
        customerSellAmount:
          type: number
          format: int32
          example: "1250.50"
        customerSellAmountDps:
          type: integer
          format: int32
          example: "2"
        customerSellCurrency:
          type: string
          example: AUD
          pattern: ^[A-Z]{3}$
        customerDealtCurrency:
          type: string
          example: USD
        valueDate:
          type: string
          format: date
          example: "2020-05-31"
        customerAllInRate:
          type: number
          format: int32
          example: "0.68712"
        customerAllInRateDps:
          type: integer
          format: int32
          example: "5"
        customerSpotPrice:
          type: number
          nullable: true
          format: int32
          example: "0.6871"
        customerSpotPriceDps:
          type: integer
          nullable: true
          format: int32
          example: "4"
        customerForwardPoints:
          type: number
          nullable: true
          format: int32
          example: "0.2"
          description: Signed adjustment to Spot Rate in basis (scaled) points.
        customerForwardPtDps:
          type: integer
          nullable: true
          format: int32
          example: "1"
        legType:
          type: string
          nullable: true
          enum:
            - NEAR-LEG
            - FAR-LEG
            - OFFSET
          description: The type that this leg represents.
    StatusUpdateResponse:
      type: object
      required:
      - status
      - text
      properties:
        channelTransactionIdentifier:
          type: string
          description: Echoed from request when available and if quoteIdentifier is
            not provided.
        quoteIdentifier:
          type: string
          description: Echoed from request when available
        status:
          type: string
          enum:
          - ACCEPTED
          - IN PROGRESS
          - CANCELLED
          - DECLINED
          - FAILED
          - REJECTED
          - EXPIRED
          - DEALER INTERVENTION
          - NOT PERMISSIONED
          - NOT IMPLEMENTED
          - NOT SUPPORTED
        text:
          type: string
          description: Additional text for elaborating on the status.
          example: Bad Gateway
    UUID:
        type: string
        example: '71d6fb19-7515-40dc-b045-e17550b67600'
        pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'

---
layout: code
title: Poll for the response corresponding to a submitted RFQ
menu_key: "poll"
group: fx
hero_key: fx
payload_spec: "/gcis/api-portal/fx/api/data/quote-poll-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
schema_tab: "false"

---
&nbsp;

The Poll for a Response operation allows you to check the status of a previously submitted RFQ (Request for Quote). By polling the service, you can retrieve the outcome of the RFQ, such as whether a quote has been issued or if additional action is required.

---

[Example request](#send) 

<h4 name="send" id="send"></h4>

#### Example Request:
To poll for a response, send a `GET` request to the `/fx/v1.0/quotes/{quoteIdentifier}` endpoint, where `{quoteIdentifier}` is the unique identifier received when the RFQ was submitted.

---

[Example response](#receive) 

<h4 name="receive" id="receive"></h4>

#### Example Response:
On success, the service will return the current status of the quote.

```json
{
  "channelTransactionIdentifier": "0123456789",
  "quoteIdentifier": "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed",
  "currencyPair": "AUD/USD",
  "swapPoints": "1.3",
  "quoteExpiry": "2019-12-31T11:59:59Z",
  "status": "COMPLETED"
}
```

---

[Usage notes](#expire) 

<h4 name="expire" id="expire"></h4>

#### Usage Notes:

- **Tracking:** Use the `quoteIdentifier` from the response to keep track of the status of the quote. Poll the endpoint periodically until the quote status is confirmed as complete or reaches another final state.

- **Error Handling:** Handle common HTTP errors effectively:
  - **400 Bad Request:** Indicates issues with the request format, such as invalid identifiers or missing required parameters.
  - **401 Unauthorised:** Occurs when authentication fails, typically due to missing or invalid tokens.
  - **404 Not Found:** The specified quote is not available, either due to a wrong identifier or premature polling.

Poll

---
layout: detail
title: Request for new deal
menu_key: "deal"
group: fx
hero_key: fx
---
---

The **Submit a New Quote** endpoint allows developers to request a new foreign exchange quote asynchronously. This operation is essential for initiating the RFQ (Request for Quote) process, which can be used to obtain competitive pricing for FX transactions. Upon submission, the system processes the request and returns a unique quote identifier, enabling further interactions such as polling for the quote's status or accepting the quote.

---

[Key points](#access) 

<h4 name="access" id="access"></h4>

#### Key Points:
- **Endpoint:** `POST /fx/v1.0/quotes/{country-code}`
- **Purpose:** To initiate a new quote request for a specified currency pair.

- **Asynchronous Process:** The quote request is processed asynchronously, allowing for efficient handling of large volumes of requests.

- **authorisation:** Requires a bearer token obtained via OAuth 2.0 to authorise the request.

---

[Request details](#details) 

<h4 name="details" id="details"></h4>

#### Request Details:
- **Headers:**
  - `authorisation: Bearer <access_token>` - Include the bearer token for authorisation.

  - `X-Correlation-Id` (Optional) - Used for tracing and logging purposes.

  - `X-Message-Id` (Required) - Ensures unique identification of each request to avoid duplicates.

---

- **Body Parameters:**
  - `customerExternalIdentifier` - A unique identifier for the customer, used for MIS purposes.

  - `channelTransactionIdentifier` - An identifier used by the channel to uniquely identify the quote request.

  - `currencyPair` - A valid currency pair, following market conventions and verified by the pricing engine.

  - Additional fields may include details about the parent deal and auxiliary types, depending on the specific use case.

---

[Example response](#receive) 

<h4 name="receive" id="receive"></h4>

#### Example Response:
On success, the service will acknowledge the quote request with a `202 Accepted` status, and a unique quote identifier will be issued for tracking.

```json
{
  "channelTransactionIdentifier": "0123456789",
  "quoteIdentifier": "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed",
  "status": "ACCEPTED"
}
```

---

[Usage notes](#expire) 

<h4 name="expire" id="expire"></h4>

### Usage Notes:

- **Tracking:** Use the `quoteIdentifier` from the response to track the status of the RFQ and for any further actions, such as polling for the response or accepting the quote.

- **Error Handling:** Ensure to handle common HTTP errors such as:
  - **400 Bad Request:** Malformed requests.
  - **401 Unauthorised:** Missing or invalid tokens.
  - **503 Service Unavailable:** If the service is down.

openapi: '3.0.0'
info:
  title: Submit a new Deal API Payload
  version: 1.3.0
servers:
  - url: https://api.fileactive.uat.anzgcis.com
    description: 'UAT (non-production) environment'
  - url: https://api.fileactive.anzgcis.com
    description: 'Production Environment'
paths:
  /fx/v1.0/deals/{quoteIdentifier}:
    post:
      summary: Submit an asynchronous request for new deal
      description: This endpoint is be used to submit a Deal request.
      tags:
        - FX RFQ Pricing Service
      operationId: submitDealRequest
      parameters:
        - $ref: '#/components/parameters/correlationID'
        - $ref: '#/components/parameters/messageID'
        - $ref: '#/components/parameters/quoteIdentifier'
      responses:
        202:
          description: Accepted the request for deal
          $ref: '#/components/responses/202'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401' 
        422:
          description: 'RFQ not accepted: Failed Business Rule'
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
        502:
          description: 'Request failure: Bad Gateway i.e, one or more of the downstream services is unavailable'
          $ref: '#/components/responses/502'
        503:
          $ref: '#/components/responses/503'
        default:
          description: Internal Server Error, Bad Request/Syntactically incorrect etc.,
          $ref: '#/components/responses/default'
      security:
        - bearerAuth: [GBL.INSTO.FX.RFQ]
          apiKeyAuth: []
    get:
      summary: Poll for the response corresponding to a submitted deal request
      description: >
        This endpoint is used to poll for the business outcome/result of
        a submitted deal request.
      tags:
        - FX RFQ Pricing Service
      operationId: pollDealResponse
      parameters:
        - $ref: '#/components/parameters/correlationID'
        - $ref: '#/components/parameters/messageID'
        - $ref: '#/components/parameters/quoteIdentifier'
      responses:
        200:
          description: The response polled for is available and the business outcome is affirmative i.e., deal was issued
          $ref: '#/components/responses/200Quote'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401' 
        404:
          description: The response polled for is not yet available.
          $ref: '#/components/responses/404'
        422:
          description: The response polled for is available and the business outcome is not affirmative or is unknown
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
        502:
          description: 'Request failure: Bad Gateway i.e, one or more of the downstream services is unavailable'
          $ref: '#/components/responses/502'
        503:
          $ref: '#/components/responses/503'
        default:
          description: Internal Server Error, Bad Request/Syntactically incorrect request etc.,
          $ref: '#/components/responses/default'
      security:
        - bearerAuth: [GBL.INSTO.FX.RFQ]
          apiKeyAuth: []
components:
  parameters:
    correlationID:  
      name: X-Correlation-Id
      in: header
      description: Optional correlation ID provided by the data consumer that should
        be reflected back in the response headers. Can be used for reporting and
        logging.
      schema:
        $ref: '#/components/schemas/UUID'
    messageID:
      name: X-Message-Id
      in: header
      description: Duplicate check using point to point reference, as assigned by
        the instructing party, and sent to the next party in the chain to unambiguously
        identify the message
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    quoteIdentifier:
      name: quoteIdentifier
      in: path
      description: A unique id provided by this service to identify a quote. MUST be
        provided in any further interactions (Polling, Acceptance, Declination, Cancellation)
      required: true
      schema:
        $ref: '#/components/schemas/QuoteIdentifier'
    requestKey:
      name: X-RequestKey
      in: header
      description: Internal End to End key used for support and reporting purposes
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275
  responses:
    200Deal:
      description: The response polled for is available and the business outcome is affirmative i.e., deal was completed
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/fx/v1.0/deals/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientDealResponse'
    200Quote:
      description: The response polled for is available and the business outcome is affirmative i.e., quote was issued
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/fx/v1.0/quotes/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientQuoteResponse'
    202:
      description: Accepted the request for quote ('RFQ') or request for deal
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/fx/v1.0/quotes/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    400:
        description: Bad Request, message format does not match expected schema
    401:
      description: Application is not unauthorised to perform a specific action
    404:
      description: The response polled for is not yet available.
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/payments/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    422:
      description: 'RFQ or Deal request not accepted: Failed Business Rule; or the response polled for is unknown'
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    500:
      description: Internal Server Error, contact support
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    502:
      description: 'Request failure: Bad Gateway i.e, one or more of the downstream
            services is unavailable'
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    503:
      description: Service Unavailable
    default:
      description: Internal Server Error, Bad Request/Syntactically incorrect
            etc.,
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ClientDealResponse:
      type: object
      required:
      - quoteIdentifier
      - dealIdentifier
      - status
      properties:
        quoteIdentifier:
          type: string
          description: Echoed from request
          example: "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed"
        status:
          type: string
          enum:
          - COMPLETED
        dealIdentifier:
          type: string
          description: Customers booking reference number for Markets deals. Identifier
            for reconciliation purposes in payments for Fx Deals.
          example: "1234567890"
        currencyPair:
          type: string
          example: AUD/USD
          pattern: ^[A-Z]{3}[/][A-Z]{3}$
        swapPoints:
          type: number
          format: int32
          example: "1.3"
        securityType:
          type: string
          description: Security that this Deal represents.
          example: HR_EXT
        responseLegs:
          type: array
          minItems: 1
          maxItems: 2
          items:
            $ref: '#/components/schemas/ResponseLeg'
    ClientQuoteResponse:
      type: object
      required:
      - channelTransactionIdentifier
      - quoteIdentifier
      - currencyPair
      - responseLegs
      - quoteExpiry
      - securityType
      properties:
        channelTransactionIdentifier:
          type: string
          description: Echoed from request
          example: "CRN123456789"
        quoteIdentifier:
          type: string
          description: A unique id generated by this service to identify a quote. This
            MUST be provided in any further interactions (Polling, Acceptance, Declination,
            Cancellation)
          example: "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed"
        currencyPair:
          type: string
          example: AUD/USD
          pattern: ^[A-Z]{3}[/][A-Z]{3}$
        swapPoints:
          type: number
          format: int32
          example: "1.3"
          description: Number of basis points between near and far leg. Signed and scaled.
        quoteExpiry:
          type: string
          format: date-time
          description: Timestamp in UTC.
          example: "2019-12-31T11:59:59Z"
        securityType:
          type: string
          description: Security that this Quote represents.
          example: HR_EXT
        responseLegs:
          type: array
          minItems: 1
          maxItems: 2
          items:
            $ref: '#/components/schemas/ResponseLeg'
    ErrorDetail:
      type: object
      properties:
        severity:
          type: string
          description: Severity of the error
          enum:
            - Fatal
            - Transient
          example: Fatal
        code:
          type: string
          description: |
            Error code (format: ECxxx_xxx)
          example: EC014_003
        text:
          type: string
          description: Human readable description of the error
          example: Internal Server Error, please contact support.
    ErrorResponse:
      type: object
      required:
      - status
      properties:
        status:
          type: object
          description: Summary of the error
          $ref: '#/components/schemas/ErrorDetail'
    QuoteIdentifier:
      description: A unique id provided by this service to identify a quote.
      type: string
      example: "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed"
    ResponseLeg:
      type: object
      required:
      - customerBuyAmount
      - customerBuyAmountDps
      - customerBuyCurrency
      - customerSellAmount
      - customerSellAmountDps
      - customerSellCurrency
      - valueDate
      - customerDealtCurrency
      - customerAllInRate
      - customerAllInRateDps
      properties:
        customerBuyAmount:
          type: number
          format: int32
          example: "1000.00"
        customerBuyAmountDps:
          type: integer
          format: int32
          example: "2"
        customerBuyCurrency:
          type: string
          example: USD
          pattern: ^[A-Z]{3}$
        customerSellAmount:
          type: number
          format: int32
          example: "1250.50"
        customerSellAmountDps:
          type: integer
          format: int32
          example: "2"
        customerSellCurrency:
          type: string
          example: AUD
          pattern: ^[A-Z]{3}$
        customerDealtCurrency:
          type: string
          example: USD
        valueDate:
          type: string
          format: date
          example: "2020-05-31"
        customerAllInRate:
          type: number
          format: int32
          example: "0.68712"
        customerAllInRateDps:
          type: integer
          format: int32
          example: "5"
        customerSpotPrice:
          type: number
          nullable: true
          format: int32
          example: "0.6871"
        customerSpotPriceDps:
          type: integer
          nullable: true
          format: int32
          example: "4"
        customerForwardPoints:
          type: number
          nullable: true
          format: int32
          example: "0.2"
          description: Signed adjustment to Spot Rate in basis (scaled) points.
        customerForwardPtDps:
          type: integer
          nullable: true
          format: int32
          example: "1"
        legType:
          type: string
          nullable: true
          enum:
            - NEAR-LEG
            - FAR-LEG
            - OFFSET
          description: The type that this leg represents.
    StatusUpdateResponse:
      type: object
      required:
      - status
      - text
      properties:
        channelTransactionIdentifier:
          type: string
          description: Echoed from request when available and if quoteIdentifier is
            not provided.
        quoteIdentifier:
          type: string
          description: Echoed from request when available
        status:
          type: string
          enum:
          - ACCEPTED
          - IN PROGRESS
          - CANCELLED
          - DECLINED
          - FAILED
          - REJECTED
          - EXPIRED
          - DEALER INTERVENTION
          - NOT PERMISSIONED
          - NOT IMPLEMENTED
          - NOT SUPPORTED
        text:
          type: string
          description: Additional text for elaborating on the status.
          example: Bad Gateway
    UUID:
        type: string
        example: '71d6fb19-7515-40dc-b045-e17550b67600'
        pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'

---
layout: code
title: Submit an asynchronous request for new deal
menu_key: "deal"
group: fx
hero_key: fx
payload_spec: "/fx/api/data/deal-submit-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
schema_tab: "false"
---

**Submitting a new deal** involves sending a request to create a financial deal based on a previously quoted foreign exchange rate. This operation allows the client to finalize and secure a transaction at the quoted rate.

[Example response](#receive) 

<h4 name="receive" id="receive"></h4>

#### Example Response:
On success, the service will acknowledge the deal request with a `202 Accepted` status, and a unique deal identifier will be issued for tracking.

```json
{
  "channelTransactionIdentifier": "0123456789",
  "dealIdentifier": "DLR-abcdef12-3456-7890-ghij-klmnopqrstuv",
  "status": "ACCEPTED"
}
```


---

[Usage notes](#expire) 

<h4 name="expire" id="expire"></h4>

#### Usage Notes:

- **Tracking:** Use the `dealIdentifier` from the response to track the status of the deal. This identifier can also be used for any further actions related to the deal, such as polling for the final response or managing deal status.

- **Error Handling:** Ensure to handle common HTTP errors such as:
  - **400 Bad Request:** Occurs when the request format is incorrect, such as missing required parameters or providing invalid data.
  - **401 Unauthorised:** Indicates authentication issues, typically due to missing or invalid tokens.
  - **503 Service Unavailable:** The service is down or temporarily unavailable; consider retrying the request after some time.

Submit a new deal

openapi: '3.0.0'
info:
  title: Poll a new Deal API Payload
  version: 1.3.0
servers:
  - url: https://api.fileactive.uat.anzgcis.com
    description: 'UAT (non-production) environment'
  - url: https://api.fileactive.anzgcis.com
    description: 'Production Environment'
paths:
  /fx/v1.0/deals/{quoteIdentifier}:
    get:
      summary: Poll for the response corresponding to a submitted deal request
      description: >
        This endpoint is used to poll for the business outcome/result of
        a submitted deal request.
      tags:
        - FX RFQ Pricing Service
      operationId: pollDealResponse
      parameters:
        - $ref: '#/components/parameters/correlationID'
        - $ref: '#/components/parameters/messageID'
        - $ref: '#/components/parameters/quoteIdentifier'
      responses:
        200:
          description: The response polled for is available and the business outcome is affirmative i.e., deal was issued
          $ref: '#/components/responses/200Quote'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401' 
        404:
          description: The response polled for is not yet available.
          $ref: '#/components/responses/404'
        422:
          description: The response polled for is available and the business outcome is not affirmative or is unknown
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
        502:
          description: 'Request failure: Bad Gateway i.e, one or more of the downstream services is unavailable'
          $ref: '#/components/responses/502'
        503:
          $ref: '#/components/responses/503'
        default:
          description: Internal Server Error, Bad Request/Syntactically incorrect request etc.,
          $ref: '#/components/responses/default'
      security:
        - bearerAuth: [GBL.INSTO.FX.RFQ]
          apiKeyAuth: []
components:
  parameters:
    correlationID:  
      name: X-Correlation-Id
      in: header
      description: Optional correlation ID provided by the data consumer that should
        be reflected back in the response headers. Can be used for reporting and
        logging.
      schema:
        $ref: '#/components/schemas/UUID'
    messageID:
      name: X-Message-Id
      in: header
      description: Duplicate check using point to point reference, as assigned by
        the instructing party, and sent to the next party in the chain to unambiguously
        identify the message
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    quoteIdentifier:
      name: quoteIdentifier
      in: path
      description: A unique id provided by this service to identify a quote. MUST be
        provided in any further interactions (Polling, Acceptance, Declination, Cancellation)
      required: true
      schema:
        $ref: '#/components/schemas/QuoteIdentifier'
    requestKey:
      name: X-RequestKey
      in: header
      description: Internal End to End key used for support and reporting purposes
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275
  responses:
    200Deal:
      description: The response polled for is available and the business outcome is affirmative i.e., deal was completed
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/fx/v1.0/deals/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientDealResponse'
    200Quote:
      description: The response polled for is available and the business outcome is affirmative i.e., quote was issued
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/fx/v1.0/quotes/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientQuoteResponse'
    202:
      description: Accepted the request for quote ('RFQ') or request for deal
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/fx/v1.0/quotes/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    400:
        description: Bad Request, message format does not match expected schema
    401:
      description: Application is not unauthorised to perform a specific action
    404:
      description: The response polled for is not yet available.
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/payments/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    422:
      description: 'RFQ or Deal request not accepted: Failed Business Rule; or the response polled for is unknown'
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    500:
      description: Internal Server Error, contact support
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    502:
      description: 'Request failure: Bad Gateway i.e, one or more of the downstream
            services is unavailable'
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    503:
      description: Service Unavailable
    default:
      description: Internal Server Error, Bad Request/Syntactically incorrect
            etc.,
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ClientDealResponse:
      type: object
      required:
      - quoteIdentifier
      - dealIdentifier
      - status
      properties:
        quoteIdentifier:
          type: string
          description: Echoed from request
          example: "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed"
        status:
          type: string
          enum:
          - COMPLETED
        dealIdentifier:
          type: string
          description: Customers booking reference number for Markets deals. Identifier
            for reconciliation purposes in payments for Fx Deals.
          example: "1234567890"
        currencyPair:
          type: string
          example: AUD/USD
          pattern: ^[A-Z]{3}[/][A-Z]{3}$
        swapPoints:
          type: number
          format: int32
          example: "1.3"
        securityType:
          type: string
          description: Security that this Deal represents.
          example: HR_EXT
        responseLegs:
          type: array
          minItems: 1
          maxItems: 2
          items:
            $ref: '#/components/schemas/ResponseLeg'
    ClientQuoteResponse:
      type: object
      required:
      - channelTransactionIdentifier
      - quoteIdentifier
      - currencyPair
      - responseLegs
      - quoteExpiry
      - securityType
      properties:
        channelTransactionIdentifier:
          type: string
          description: Echoed from request
          example: "CRN123456789"
        quoteIdentifier:
          type: string
          description: A unique id generated by this service to identify a quote. This
            MUST be provided in any further interactions (Polling, Acceptance, Declination,
            Cancellation)
          example: "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed"
        currencyPair:
          type: string
          example: AUD/USD
          pattern: ^[A-Z]{3}[/][A-Z]{3}$
        swapPoints:
          type: number
          format: int32
          example: "1.3"
          description: Number of basis points between near and far leg. Signed and scaled.
        quoteExpiry:
          type: string
          format: date-time
          description: Timestamp in UTC.
          example: "2019-12-31T11:59:59Z"
        securityType:
          type: string
          description: Security that this Quote represents.
          example: HR_EXT
        responseLegs:
          type: array
          minItems: 1
          maxItems: 2
          items:
            $ref: '#/components/schemas/ResponseLeg'
    ErrorDetail:
      type: object
      properties:
        severity:
          type: string
          description: Severity of the error
          enum:
            - Fatal
            - Transient
          example: Fatal
        code:
          type: string
          description: |
            Error code (format: ECxxx_xxx)
          example: EC014_003
        text:
          type: string
          description: Human readable description of the error
          example: Internal Server Error, please contact support.
    ErrorResponse:
      type: object
      required:
      - status
      properties:
        status:
          type: object
          description: Summary of the error
          $ref: '#/components/schemas/ErrorDetail'
    QuoteIdentifier:
      description: A unique id provided by this service to identify a quote.
      type: string
      example: "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed"
    ResponseLeg:
      type: object
      required:
      - customerBuyAmount
      - customerBuyAmountDps
      - customerBuyCurrency
      - customerSellAmount
      - customerSellAmountDps
      - customerSellCurrency
      - valueDate
      - customerDealtCurrency
      - customerAllInRate
      - customerAllInRateDps
      properties:
        customerBuyAmount:
          type: number
          format: int32
          example: "1000.00"
        customerBuyAmountDps:
          type: integer
          format: int32
          example: "2"
        customerBuyCurrency:
          type: string
          example: USD
          pattern: ^[A-Z]{3}$
        customerSellAmount:
          type: number
          format: int32
          example: "1250.50"
        customerSellAmountDps:
          type: integer
          format: int32
          example: "2"
        customerSellCurrency:
          type: string
          example: AUD
          pattern: ^[A-Z]{3}$
        customerDealtCurrency:
          type: string
          example: USD
        valueDate:
          type: string
          format: date
          example: "2020-05-31"
        customerAllInRate:
          type: number
          format: int32
          example: "0.68712"
        customerAllInRateDps:
          type: integer
          format: int32
          example: "5"
        customerSpotPrice:
          type: number
          nullable: true
          format: int32
          example: "0.6871"
        customerSpotPriceDps:
          type: integer
          nullable: true
          format: int32
          example: "4"
        customerForwardPoints:
          type: number
          nullable: true
          format: int32
          example: "0.2"
          description: Signed adjustment to Spot Rate in basis (scaled) points.
        customerForwardPtDps:
          type: integer
          nullable: true
          format: int32
          example: "1"
        legType:
          type: string
          nullable: true
          enum:
            - NEAR-LEG
            - FAR-LEG
            - OFFSET
          description: The type that this leg represents.
    StatusUpdateResponse:
      type: object
      required:
      - status
      - text
      properties:
        channelTransactionIdentifier:
          type: string
          description: Echoed from request when available and if quoteIdentifier is
            not provided.
        quoteIdentifier:
          type: string
          description: Echoed from request when available
        status:
          type: string
          enum:
          - ACCEPTED
          - IN PROGRESS
          - CANCELLED
          - DECLINED
          - FAILED
          - REJECTED
          - EXPIRED
          - DEALER INTERVENTION
          - NOT PERMISSIONED
          - NOT IMPLEMENTED
          - NOT SUPPORTED
        text:
          type: string
          description: Additional text for elaborating on the status.
          example: Bad Gateway
    UUID:
        type: string
        example: '71d6fb19-7515-40dc-b045-e17550b67600'
        pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'

---
layout: code
title: Poll for the response corresponding to a submitted deal request
menu_key: "deal"
group: fx
hero_key: fx
payload_spec: "/fx/api/data/deal-poll-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
schema_tab: "false"
---

The **Poll for Response** endpoint is used to check the status of a deal request that has been previously submitted. This allows your application to monitor the progress of the deal asynchronously without needing to maintain a constant connection to the service.

---

[Key features](#keyfeature) 

<h4 name="keyfeature" id="keyfeature"></h4>


#### Key Features:
- **Asynchronous Status Updates:** This endpoint enables you to periodically check the status of your submitted deal request, ensuring that your application can respond to the outcome promptly.

- **Status Tracking:** The response includes the current status of the deal, such as "Pending," "Completed," or "Failed," allowing for dynamic handling based on the latest information.

- **Resource Efficiency:** By polling at intervals, rather than maintaining a persistent connection, your application can reduce resource consumption and improve performance.

----

[How it works](#works) 

<h4 name="works" id="works"></h4>

#### How It Works:
1. **Submit the Initial Deal Request:** Begin by submitting your deal request through the appropriate endpoint and note the `dealIdentifier` received in the response.

2. **Poll Using `dealIdentifier`:** Use the `dealIdentifier` to poll the status endpoint at regular intervals.

3. **Handle the Response:** Based on the response status, proceed with additional actions such as confirmation, further requests, or error handling.

[Example request](#send) 

<h4 name="send" id="send"></h4>

#### Example Request:
```http
GET /fx/v1.0/deals/{dealIdentifier} HTTP/1.1
Host: api.fileactive.anzgcis.com
authorisation: Bearer <access_token>
```

---

[Example response](#receive) 

<h4 name="receive" id="receive"></h4>

#### Example Response:
On success, the service will return the current status of the deal request along with relevant details.

```json
{
  "dealIdentifier": "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed",
  "status": "COMPLETED",
  "currencyPair": "AUD/USD",
  "swapPoints": "1.3",
  "quoteExpiry": "2019-12-31T11:59:59Z",
  "securityType": "HR_EXT",
  "responseLegs": []
}
```

---

[Usage notes](#expire) 

<h4 name="expire" id="expire"></h4>

#### Usage Notes:

- **Tracking:** Use the `dealIdentifier` from the response to track the status of the deal. Poll the endpoint periodically until the status is updated to a final state, such as "COMPLETED" or "FAILED."

- **Error Handling:** Be prepared to handle common HTTP errors:
  - **400 Bad Request:** Indicates issues with the request format, such as invalid identifiers or missing required parameters.
  - **401 Unauthorised:** Occurs when authentication fails, typically due to missing or invalid tokens.
  - **404 Not Found:** The specified deal is not available, either due to a wrong identifier or polling before the deal is ready.
  - **503 Service Unavailable:** The service is down or temporarily unavailable; consider retrying the request after some time.

---

Poll for response

---
layout: code
title: Decline or cancel an issued quote
menu_key: "cancel"
group: fx
hero_key: fx
payload_spec: "/fx/api/data/cancel-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
schema_tab: "false"

---

---

The **Decline or Cancel a Quote** operation allows you to reject or cancel an issued quote that has been provided by the FX RFQ service. This action is crucial for managing quotes that are no longer needed or have been deemed unsuitable based on updated business requirements or market conditions.

---

[Capabilities](#capable) 

<h4 name="capable" id="capable"></h4>

#### Capabilities:

- **Decline a Quote:** Formally reject a quote that you do not wish to proceed with, ensuring that the quote is no longer available for acceptance.
- **Cancel a Quote:** Remove a previously issued quote, preventing any further actions or transactions based on it.

---
[Technical requirements](#require) 

<h4 name="require" id="require"></h4>

#### Technical Requirements:

- **Endpoint:** `/fx/v1.0/quotes/{quoteIdentifier}`
- **HTTP Method:** `PUT`
- **authorisation:** Requires a valid bearer token obtained via OAuth 2.0.
- **Request Headers:**
  - `X-Correlation-Id`: Optional header for tracking requests.
  - `X-Message-Id`: Required header for unique identification of the request.
- **Request Body:**
  - `quoteIdentifier`: The unique identifier of the quote to be declined or canceled.
  - `status`: The desired action, either "CANCEL" or "DECLINE".

---  

[Key features for developers](#develop) 

<h4 name="develop" id="develop"></h4>

#### Key Features for Developers:

- **Idempotent Operations:** The request is idempotent, meaning repeated requests will have the same effect and response as the first one, preventing unintended side effects.
- **Immediate Effect:** Upon a successful decline or cancellation, the quote is rendered inactive, and no further actions can be taken on it.
- **Error Handling:** Robust error responses guide developers in troubleshooting issues, such as handling cases where the quote cannot be found or is already inactive.

---

[Example request](#send) 

<h4 name="send" id="send"></h4>

#### Example Request:

```http
PUT /fx/v1.0/quotes/MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed HTTP/1.1
Host: api.fileactive.anzgcis.com
authorisation: Bearer <access_token>
Content-Type: application/json
X-Correlation-Id: 71d6fb19-7515-40dc-b045-e17550b67600
X-Message-Id: 71d6fb19-7515-40dc-b045-e17550b67600

{
  "quoteIdentifier": "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed",
  "status": "CANCEL"
}
```

---

[Example response](#receive) 

<h4 name="receive" id="receive"></h4>

#### Example Response:

On success, the service will confirm the decline or cancellation of the quote with the current status.

```json
{
  "status": "CANCELLED",
  "quoteIdentifier": "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed"
}
```

---

[Rate limits and throttling](#applied) 

<h4 name="applied" id="applied"></h4>

#### Rate limits and throttling:

By default the following rate limits are applied.

<table style="border-collapse: collapse; width: 100%;">
  <thead>
    <tr style="background-color: #f2f2f2; border: 1px solid #ddd;">
      <th style="border: 1px solid #ddd; padding: 8px;">Type</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPH (Transactions Per Hour)</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPM (Transactions Per Minute)</th>
      <th style="border: 1px solid #ddd; padding: 8px;">TPS (Transactions Per Second)</th>
    </tr>
  </thead>
  <tbody>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">Authorisation</td>
      <td style="border: 1px solid #ddd; padding: 8px;">10</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">2</td>
    </tr>
    <tr style="border: 1px solid #ddd;">
      <td style="border: 1px solid #ddd; padding: 8px;">FX RFQ</td>
      <td style="border: 1px solid #ddd; padding: 8px;">500</td>
      <td style="border: 1px solid #ddd; padding: 8px;">n/a</td>
      <td style="border: 1px solid #ddd; padding: 8px;">10</td>
    </tr>
  </tbody>
</table>

---

[Rate limiting algorithms](#algorithms) 

<h4 name="algorithms" id="algorithms"></h4>

#### Rate limiting algorithms:

For most use cases one of two algorithms is implemented for rate limiting.

**Fixed Window**
The system uses a window size of `n` seconds (typically using human-friendly values, such as 60 or 3600 seconds) to track the fixed window algorithm rate. Each incoming request increments the counter for the window. It discards the request if the counter exceeds a threshold. The current timestamp floor typically defines the windows, so 12:00:03, with a 60-second window length, would be in the 12:00:00 window.

**Sliding Window**
Sliding Window is a hybrid approach. Like the fixed window algorithm, we track a counter for each fixed window. Next, we account for a weighted value of the previous window’s request rate based on the current timestamp to smooth out bursts of traffic.

[Sliding window example](#example) 

<h4 name="example" id="example"></h4>

#### Sliding window example:

**Given a limit of 100 transactions per hour.**

- **Window 1 (13:00 - 14:00)**  
  Between 13:00 - 14:00, 80 requests are received. This is within the 100 tph limit, so all are allowed.

- **Window 2 (14:00 - 15:00)**  
  By 14:15, 20 requests are received. This is 25% (15 minutes) into window 2, so the weighted average would include 75% from the previous window.

  **Request rate**: 20 (all requests within window 2) + 60 (75% of requests from window 1) = 80 requests.  
  The request rate is still within the 100 tph maximum.

  By 14:30, 75 requests have been received. This is 50% (30 minutes) into window 2, so the weighted average would include 50% from the previous window.

  **Request rate**: 75 (all requests within window 2) + 40 (50% weighted average from previous window) = 115 requests.  
  This exceeds the 100 tph limit, so further requests would return an HTTP 429 (Too Many Requests) status code until the weighted request rate is below the agreed limit.

  By 14:45, no further requests have been made. This is 75% (45 minutes) through window 2.

  **Request rate**: 75 (current window) + 20 (25% weighted average from previous window) = 95 requests.  
  As this is below the 100 tph limit, further requests will be accepted.

openapi: '3.0.2'
info:
  title: Decline or Cancel an issued quote API Payload
  version: 1.3.0
servers:
  - url: https://api.fileactive.uat.anzgcis.com
    description: 'UAT (non-production) environment'
  - url: https://api.fileactive.anzgcis.com
    description: 'Production Environment'
paths:
  /fx/v1.0/quotes:
    put:
      summary: Submit
      description: This endpoint is used to decline or cancel a quote.
      operationId: abandonOrRejectQuote
      parameters:
        - $ref: '#/components/parameters/correlationID'
        - $ref: '#/components/parameters/messageID'
      requestBody:
        description: A request to decline or cancel a quote
        required: true
        content:
          application/json:
            schema: 
              $ref: '#/components/schemas/StatusUpdateRequest'
      responses:
        200:
          description: The requested update was completed successfully i.e., quote was cancelled/declined
          $ref: '#/components/responses/200Cancel'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401' 
        404:
          description: The response polled for is not yet available.
          $ref: '#/components/responses/404'
        422:
          description: 'The requested update rejected: Failed Business rule'
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
        502:
          description: 'Request failure: Bad Gateway i.e, one or more of the downstream services is unavailable'
          $ref: '#/components/responses/502'
        503:
          $ref: '#/components/responses/503'
        default:
          description: Internal Server Error, Bad Request/Syntactically incorrect request etc.,
          $ref: '#/components/responses/default'
      security:
        - bearerAuth: [GBL.INSTO.FX.RFQ]
          apiKeyAuth: []
components:
  parameters:
    correlationID:  
      name: X-Correlation-Id
      in: header
      description: Optional correlation ID provided by the data consumer that should
        be reflected back in the response headers. Can be used for reporting and
        logging.
      schema:
        $ref: '#/components/schemas/UUID'
    messageID:
      name: X-Message-Id
      in: header
      description: Duplicate check using point to point reference, as assigned by
        the instructing party, and sent to the next party in the chain to unambiguously
        identify the message
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    requestKey:
      name: X-RequestKey
      in: header
      description: Internal End to End key used for support and reporting purposes
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275
  responses:
    200Cancel:
      description: The requested update was completed successfully i.e. quote was cancelled/declined
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/fx/v1.0/deals/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    400:
        description: Bad Request, message format does not match expected schema
    401:
      description: Application is not unauthorised to perform a specific action
    404:
      description: The response polled for is not yet available.
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
        X-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
        Location:
            description: Location of the resource, used for enquiry
            schema:
              type: string
              example: 'https://api.fileactive.anzgcis.com/payments/64eb2fb9-57f8-4d80-bff5-86d666f92944'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    422:
      description: 'RFQ or Deal request not accepted: Failed Business Rule; or the response polled for is unknown'
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusUpdateResponse'
    500:
      description: Internal Server Error, contact support
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    502:
      description: 'Request failure: Bad Gateway i.e, one or more of the downstream
            services is unavailable'
      headers:
        X-Correlation-Id:
          schema:
            $ref: '#/components/schemas/UUID'
          description: GUID echo'd from customer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    503:
      description: Service Unavailable
    default:
      description: Internal Server Error, Bad Request/Syntactically incorrect
            etc.,
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorDetail:
      type: object
      properties:
        severity:
          type: string
          description: Severity of the error
          enum:
            - Fatal
            - Transient
          example: Fatal
        code:
          type: string
          description: |
            Error code (format: ECxxx_xxx)
          example: EC014_003
        text:
          type: string
          description: Human readable description of the error
          example: Internal Server Error, please contact support.
    ErrorResponse:
      type: object
      required:
      - status
      properties:
        status:
          type: object
          description: Summary of the error
          $ref: '#/components/schemas/ErrorDetail'
    StatusUpdateRequest:
      type: object
      required:
      - quoteIdentifier
      - status
      properties:
        quoteIdentifier:
          type: string
          description: A unique id provided by this service to identify a quote.
          example: "MKT-d75a03b5-2d7c-4db0-b30f-bcccc67a4fed"
        status:
          type: string
          enum:
          - CANCEL
          - DECLINE
          description: Requested status.
          example: CANCEL
    StatusUpdateResponse:
      type: object
      required:
      - status
      - text
      properties:
        channelTransactionIdentifier:
          type: string
          description: Echoed from request when available and if quoteIdentifier is
            not provided.
        quoteIdentifier:
          type: string
          description: Echoed from request when available
        status:
          type: string
          enum:
          - ACCEPTED
          - IN PROGRESS
          - CANCELLED
          - DECLINED
          - FAILED
          - REJECTED
          - EXPIRED
          - DEALER INTERVENTION
          - NOT PERMISSIONED
          - NOT IMPLEMENTED
          - NOT SUPPORTED
        text:
          type: string
          description: Additional text for elaborating on the status.
          example: Bad Gateway
    UUID:
        type: string
        example: '71d6fb19-7515-40dc-b045-e17550b67600'
        pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'

---
layout: code
title: Error responses
menu_key: "erro"
group: fx
hero_key: fx
payload_spec: "/fx/api/data/error-api-payload.yaml"
overview_tab: "false"
payload_tab: "true"   
schema_tab: "false"
---

Error Response payload

openapi: '3.0.2'
info:
  title: Error Response Payload
  version: 1.3.0
paths:
  /error-response:
    get:
      summary: Get Error Response
      description: Returns an error response containing error details.
      operationId: getErrorResponse
      tags:
        - ErrorResponse
      responses:
        '200':
          description: Successfully retrieved error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorDetail:
      type: object
      properties:
        severity:
          type: string
          description: Severity of the error
          enum:
            - Fatal
            - Transient
          example: Fatal
        code:
          type: string
          description: |
            Error code (format: ECxxx_xxx)
          example: EC014_003
        text:
          type: string
          description: Human-readable description of the error
          example: Internal Server Error, please contact support.
 
    ErrorResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: object
          description: Summary of the error
          $ref: '#/components/schemas/ErrorDetail'
 
tags:
  - name: ErrorResponse
    description: "ErrorResponse schema definition containing error details."
    x-displayName: ErrorResponse
 
              

---
layout: detail
title: Return codes
menu_key: "fx"
group: fx
hero_key: fx
---
[Default API event codes](#general) 

<h4 name="general" id="general"></h4>

### Default API Event Codes

| Event Code | Name                   | HTTP <BR> Response | Description                                    |
| :--------- | :--------------------- | :----------------: | :--------------------------------------------- |
| EC000_001  | Internal Server Error  |        500         | Internal Server Error, please contact support. |
| EC000_002  | Unauthorized           |        401         | The request is not authorized                  |
| EC000_003  | Validation Failure     |        400         | The request failed validation                  |
| EC000_004  | Resource Not Found     |        404         | The requested resource is not found            |
| EC000_005  | Method Not Allowed     |        405         | The requested HTTP method is not allowed       |
| EC000_006  | Unsupported Media Type |        405         | Content-Type provided is not supported         |
| EC000_007  | Invalid Content        |        400         | Invalid secured payload                        |

---

[Return to Top](#top)


[FX event codes](#markets) 

<h4 name="markets" id="markets"></h4>

### FX Event Codes

| Event Code | Name                | HTTP <br> Response | Description                                                                                                                                                                                   |
|:-----------|:--------------------|:------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| EC014_001  | Invalid Request     | 400                | Schema validation failed against the request payload schema error details [{0}]<br>{0} = error message from parser, schema check, missing or invalid headers etc. Enclosed in square brackets |
| EC014_002  | Duplicate Request   | 400                | Duplicate request received (supplied X-Message-Id value: [{0}]<br>{0} = Duplicate X-Message-Id value. Enclosed in square brackets                                                             |
| EC014_003  | Internal Error      | 500                | Internal Server Error, please contact support.                                                                                                                                                |
| EC014_004  | Service Unavailable | 503                | Service Unavailable                                                                                                                                                                           |


---

[Return to Top](#top)

---
layout: detail
title: FX RFQ pricing service code catalogue
menu_key: "fx"
group: fx
hero_key: fx
---

---

The FX RFQ (Request for Quote) Pricing Service provides a robust solution for developers to request and manage foreign exchange (FX) quotes and deals. This API enables seamless integration with ANZ's FX trading platform, allowing businesses to obtain real-time FX rates, execute trades, and manage the lifecycle of FX deals programmatically.

---
[Capabilities](#capable) 

<h4 name="capable" id="capable"></h4>

#### Capabilities:
- **Asynchronous Quote Requests:** Submit requests for FX quotes asynchronously, allowing for efficient handling of high-volume trading scenarios without blocking your application workflow.

- **Real-Time Quote Polling:** Poll the API to retrieve the status and details of submitted quotes, providing up-to-date information on FX rates and market conditions.

- **Deal Execution:** Convert accepted quotes into confirmed FX deals by submitting requests through the API, facilitating automated trading and transaction management.

- **Quote and Deal Management:** Use the API to decline or cancel issued quotes, providing flexibility in managing your FX trading strategy.

---
[Technical requirements](#require) 

<h4 name="require" id="require"></h4>

#### Technical Requirements:

- **Authentication:** Requires OAuth 2.0 authentication with a bearer token obtained via the Client Credential Grant flow. API requests must include this token in the `authorisation` header as `Bearer <access_token>`.

- **Endpoints:**

  - **Quote Submission:** `POST /fx/v1.0/quotes/{country-code}` - Submit a new FX quote request.
  - **Quote Polling:** `GET /fx/v1.0/quotes/{quoteIdentifier}` - Poll for the status of a submitted quote.

  - **Deal Submission:** `POST /fx/v1.0/deals/{quoteIdentifier}` - Submit a request to execute a deal based on an accepted quote.

  - **Quote Cancellation:** `PUT /fx/v1.0/quotes` - Cancel or decline a specific quote.

  - **Payloads and Responses:** API interactions use JSON payloads for requests and responses, supporting structured and consistent data exchange.

---

[Key features for developers](#devops) 

<h4 name="devops" id="devops"></h4>

#### Key Features for Developers:
- **Seamless Integration:** Easily integrate FX trading capabilities into your applications with RESTful APIs, enabling real-time FX rate retrieval and deal execution.

- **Flexibility:** Manage the complete FX trading lifecycle from quote requests to deal management, allowing for automated trading strategies and improved operational efficiency.

- **Error Handling:** Comprehensive error codes and detailed response messages help developers troubleshoot issues quickly and ensure reliable integration.

- **Security:** All API requests are secured using OAuth 2.0 and HTTPS, ensuring that sensitive financial transactions are protected.

---

[Example use cases](#usecase) 

<h4 name="usecase" id="usecase"></h4>

#### Example Use Cases:
- **Automated Trading Systems:** Incorporate FX RFQ and deal execution into your trading algorithms to automate FX transactions based on predefined strategies.

- **Real-Time Pricing Applications:** Use the service to fetch real-time FX rates, providing users with up-to-date pricing information for currency conversion or financial analysis.

- **Treasury Management:** Integrate the FX RFQ Pricing Service into treasury systems to streamline FX deal management, helping organizations manage their currency exposure and liquidity effectively.

---

[Example request](#send) 

<h4 name="send" id="send"></h4>

#### Example Request:
```http
POST /fx/v1.0/quotes/NZ HTTP/1.1
Host: api.fileactive.anzgcis.com
Content-Type: application/json
authorisation: Bearer <access_token>

{
  "customerExternalIdentifier": "CRN0000000001",
  "channelTransactionIdentifier": "0123456789",
  "currencyPair": "AUD/USD",
  "parentDealSourceSystem": "ABCDEF",
  "parentDealId": "123456789",
  "auxiliaryType": "HR_EXT",
  "requestLegs": [{}]
}
```
---

---
layout: detail  
title: ACMC graphQL intro  
menu_key: intro  
group: acmc  
hero_key: acmc  
permalink: /acmc/api/graphql-intro/
---
---

[GraphQL overview](#graphqloverview) 

<h4 name="graphqloverview" id="graphqloverview"></h4>

#### GraphQL Overview:

ANZ Cash Management Central (ACMC) leverages the power of GraphQL for its API interactions, providing developers with an efficient and flexible way to access, manipulate, and retrieve data. Unlike traditional REST APIs, GraphQL allows developers to specify exactly what data is needed, avoiding the inefficiencies of over-fetching or under-fetching data. This approach ensures optimised API performance and provides granular control over how data is requested and manipulated.

[Key features of graphQL in ACMC](#graphqlinacmc) 

<h4 name="graphqlinacmc" id="graphqlinacmc"></h4>

#### Key Features of GraphQL in ACMC:
- **Efficient Data Retrieval:** Developers can query precisely the data they require, even from deeply nested structures, in a single request. This leads to a significant reduction in the number of API calls and overall data payload.

- **Customisable Queries:** The flexible querying capabilities of GraphQL allow for tailored data retrieval based on the specific requirements of the operation. Whether you are reading, writing, or updating data, queries can be constructed to only return relevant fields.

- **Reduced Overhead:** With the ability to combine multiple nested queries into a single call, GraphQL helps reduce network overhead and latency, streamlining operations.

- **Scalable Performance:** GraphQL supports advanced operations such as pagination, filtering, and sorting, which are essential when dealing with large datasets.

**Before You Begin:**
If you are new to GraphQL, we encourage you to familiarise yourself with the core concepts of GraphQL before diving into the ACMC API. GraphQL offers a unique approach to querying APIs, and understanding its fundamentals will help you get the most out of ACMC’s API capabilities. Visit the official GraphQL documentation at [`graphql.org`](https://graphql.org/learn/) to explore tutorials and resources that will provide you with a solid foundation.


[Core graphQL operations in ACMC](#operationsinacmc) 

<h4 name="operationsinacmc" id="operationsinacmc"></h4>

#### Core GraphQL Operations in ACMC:

- **Queries:**
    Queries are the core operations for retrieving data in GraphQL. At the root level, the `Query` type defines the entry point for data access. This can include retrieving basic scalar values or more complex objects, supporting flexible data fetching at various levels of the data hierarchy.
    
- **Mutations:**
    Mutations handle data modification in ACMC. Whether creating new entities, updating existing records, or deleting data, mutations provide a structured way to alter the state of the system. Mutations also return data, allowing you to verify changes after an operation has been completed.


[GraphQL types](#graphqltypes) 

<h4 name="graphqltypes" id="graphqltypes"></h4>

#### GraphQL Types:

- **Object Types:**
    GraphQL schemas in ACMC are built around object types, which represent the primary entities in the system, such as `User`, `Account`, or `Transaction`. Each object type contains fields that can be queried, making it easy to retrieve related data through a single API request.
    
- **Enum Types:**
    Enum types define a set of predetermined values for fields. For instance, an enum like `AccountStatus` could have values such as `ACTIVE` or `CLOSED`. These types ensure data consistency and prevent invalid inputs.

- **Scalar Types:**
    Basic types such as `Int`, `Float`, `String`, `Boolean`, and `ID` form the foundation of the GraphQL type system. Scalar types represent simple values and are used throughout queries and mutations.

- **Input Types:**
    Input types enable structured data to be passed into mutations, allowing for complex objects to be created or updated with ease. This is particularly useful when dealing with detailed entities such as accounts or transactions that require multiple fields.

- **Interface Types:**
    Interfaces in GraphQL allow for different object types to share common fields. This is particularly useful in ACMC, where multiple types might share fields like `name` or `accountNumber` but still represent distinct entities.

[Validation and execution in graphQL](#validationandexecution) 

<h4 name="validationandexecution" id="validationandexecution"></h4>

#### Validation and Execution in GraphQL:

GraphQL follows a two-step process for handling queries and mutations: **Validation** and **Execution**.

- **Validation:**
    When a query is sent to the GraphQL API, it first undergoes a validation phase. During this step, the query is checked against the GraphQL schema to ensure that it is syntactically correct and adheres to the schema's rules. This process includes validating the types, arguments, and fields requested. If any issues are detected—such as requesting non-existent fields or providing incorrect arguments—the query will be rejected, and an error message will be returned.

- **Execution:**
    Once the query passes validation, it proceeds to the execution phase. In this phase, the GraphQL server resolves the query by fetching the requested data. The execution process follows the structure defined in the query, executing field by field, and resolving any nested fields as necessary. The final response is then compiled and returned to the client in the form of a JSON object, containing only the requested data.

The combination of validation and execution ensures that all queries are robust and that only valid requests reach the execution phase, reducing the risk of errors and optimizing the data retrieval process.

---
layout: code
title: ACMC authentication
menu_key: auth
group: acmc
hero_key: acmc
permalink: acmc/api/graphql-auth/
payload_spec: "/acmc/api/data/auth-api-payload.yaml"
overview_tab: "true"
payload_tab: "true"   
schema_tab: "false"
---

[ACMC authentication overview](#authenticationoverview) 

<h4 name="authenticationoverview" id="authenticationoverview"></h4>

#### ACMC Authentication Overview:

To interact with ACMC 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 authorising API requests.

[Key points](#keypoints) 

<h4 name="keypoints" id="keypoints"></h4>

#### Key points:

- **Endpoint:** All authentication requests should be sent to the `/v1.0/auth` endpoint.
- **Grant Type:** Use `client_credentials` as the grant type for obtaining tokens.
- **Token URL:** The token URL is `https://api.acmc.anzgcis.com/v1.0/auth`.
- **Scopes:** Specific scopes define for ACMC GraphQL API
  - GBL.INSTO.GRAPHQL.READ
  - GBL.INSTO.GRAPHQL.CREATE
- **Headers:** Include an API key in the header using `apikey` as the parameter name.

[Example request](#examplerequest) 

<h4 name="examplerequest" id="examplerequest"></h4>

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

```bash
POST /v1.0/auth HTTP/1.1
Host: api.acmc.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=GBL.INSTO.GRAPHQL.READ GBL.INSTO.GRAPHQL.CREATE
client_assertion=<your_client_assertion_here>
```

[Example response](#exampleresponse) 

<h4 name="exampleresponse" id="exampleresponse"></h4>

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

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


[Usage notes](#usagenotes) 

<h4 name="usagenotes" id="usagenotes"></h4>

#### 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](#importantnote) 

<h4 name="importantnote" id="importantnote"></h4>

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

openapi: 3.0.1
info:
    title: ACMC Authentication API
    version: 2.1.0
servers:
  - url: https://api.acmc.uat.anzgcis.com
    description: UAT Test environment
  - url: https://api.acmc.anzgcis.com
    description: Production Environment
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /v1.0/auth:
    post:
      security:
        - apiKeyAuth: []
          oAuth2: []
      summary: Auth Token Request
      description: >
        ANZ uses OAuth 1.0 to authenticate inbound token requests, a bearer token
        is returned as a response which is then used to authorise against ANZ
        resources.
      operationId: auth
      requestBody:
        description: 'Information and examples of Auth request body '
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/authTokenRequest'
      responses:
        '200':
          $ref: '#/components/responses/200OKAuth'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorised'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalError'
        '502':
          $ref: '#/components/responses/502BadGateway'
        '503':
          $ref: '#/components/responses/503Unavailable'
        '504':
          $ref: '#/components/responses/504Timeout'
        default:
          $ref: '#/components/responses/default'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: uuid
      description: Bearer token obtained during token exchange
    apiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: API key to authorise requests.
    oAuth2:
      type: oauth2
      description: OAuth2 flows for both Production and UAT environments
      flows:
        clientCredentials:
          tokenUrl: https://api.acmc.anzgcis.com/v1.0/auth
          scopes:
            GBL.INSTO.GRAPHQL.READ: Read access to ACMC GraphQL
            GBL.INSTO.GRAPHQL.CREATE: Create access to ACMC GraphQL
    apiKey:
          type: apiKey
          in: header
          name: apikey
          description: API key to authorise requests.
  responses:
    200OKAuth:
      description: Bearer token (Opaque Token) returned after a token request
      headers:
        x-RequestKey:
          schema:
            $ref: '#/components/parameters/requestKey'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/authTokenResponse'
    400BadRequest:
      description: Bad Request, message format does not match expected schema
      content: {}
    401Unauthorised:
      description: Application is not unauthorised to perform a specific action
      content: {}
    403Forbidden:
      description: Action is not authorised using current authentication credentils
      content: {}
    404NotFound:
      description: No record found
      content: {}
    429TooManyRequests:
      description: Action exceeds allocated limits
      content: {}
    500InternalError:
      description: Internal Server Error, contact support
      content: {}
    502BadGateway:
      description: Bad Gateway, contact support
      content: {}
    503Unavailable:
      description: Service Unavailable or down for maintainance
      content: {}
    504Timeout:
      description: Gateway Timeout, retry or contact support
      content: {}
    default:
      description: Unexpected error
      content: {}
  schemas:
    authTokenRequest:
      required:
        - grant_type
        - client_assertion_type
        - scope
        - client_assertion
      type: object
      properties:
        grant_type:
          description: Specify the type credential requested
          type: string
          example: client_credentials
        client_assertion_type:
          description: >-
            Describes the type of client assertion provided in the message
            request
          type: string
          example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
        scope:
          $ref: '#/components/securitySchemes/oAuth2/flows/clientCredentials/scopes'
        client_assertion:
          $ref: '#/components/schemas/ClientAssertion'
    authTokenResponse:
      type: object
      description: Response to report the status of an ACMC authentication request.
      additionalProperties: false
      properties:
        expires_in:
          description: Indication on how long a token is valid for
          type: integer
        token_type:
          description: Type of token returned
          type: string
        access_token:
          description: >-
            Opaque token returned as part of request, Fileactive does not provide the
            full access token
          type: string
      example:
        expires_in: 3600
        token_type: Bearer
        access_token: eaaa13ee-b596-a8cc-b9d4-f778f8bb9377
    ClientAssertion:
      required:
        - sub
        - exp
        - aud
      type: object
      properties:
        sub:
          type: string
          description: Customer Code as provided by ANZ onboarding
          example: CUSTOMERA
        exp:
          type: integer
          description: EPOCH date and time
          example: '1619658591'
          maxLength: 10
          minLength: 10
        aud:
          type: string
          description: Specify the intended audience of the token request
          example: https://api.acmc.anzgcis.com/auth
    UUID:
      type: string
      example: 71d6fb19-7515-40dc-b045-e17550b67600
      pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
  parameters:
    requestKey:
      name: X-REQUESTKEY
      in: header
      description: Internal End to End key used for support and reporting purposes
      schema:
        $ref: '#/components/schemas/UUID'
      example: 325ea624-ac19-47e2-94ef-a1ab4e487275

---
layout: detail
title: ACMC graphQL - payload encryption
menu_key: auth
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-auth/doencrypt
---
---
[Payload encryprion overview](#encryprionoverview) 

<h4 name="encryprionoverview" id="encryprionoverview"></h4>

#### Payload Encryprion Overview:

The `doEncrypt` operation is a crucial security feature for transmitting sensitive information to the server. It uses the server's public key to encrypt data, ensuring that only the server can decrypt it with its private key. This operation is particularly useful for protecting confidential data. The encrypted output can be used as input for other mutations that require secure data transmission. To maintain the highest level of security, always use HTTPS when communicating with the API, complementing the encryption provided by `doEncrypt`.


[Key points](#pointskey) 

<h4 name="pointskey" id="pointskey"></h4>


#### Key points

- **Input Type:** `EncryptInput`
- **Output:** Returns `encryptedData` as a string
- Used for encrypting sensitive information before sending it to the server
- Essential for operations that require secure data transmission, such as payments


[Encrypt data](#encryptdata) 

<h4 name="encryptdata" id="encryptdata"></h4>

#### Encrypt Data

##### Operation: doEncrypt

This mutation encrypts sensitive data using the server's public key.

```graphql
mutation ($input: EncryptInput!) {
  doEncrypt(input: $input) {
    encryptedData
  }
}
```
**Variables**

```json
{
    "input": {
        "encryptedPayload": {
            "action": "payment",
            "payment-method": "NPP",
            "recipient": {
                "account-number": "1347825467",
                "bank-code": "083054",
                "name": "Sachin Testing"
            },
            "sender": {
                "account": {
                    "id": "QWNjb3VudDo1OTNmYThlMGFiNzQ4NDRmNzU0Y2M0ZGQ4MTA2ZTc5ZTEzYjhjNjgzMzc1NDBmNGMyNzc2OTRmZjhkNWRmYjVh"
                }
            },
            "amount": {
                "value": "5.00",
                "currency": "AUD"
            },
            "value-date": "2024-10-07",
            "reference": "npp pay"
        }
    }
}
```

**Response**

```json 
{
    "data": {
        "doEncrypted": {
            "commandId": "Q29tbWFuZDo5MTAxY2YwNi1iZTU3LTRjMDEtYWJmNi0xYWQ5NTM2NzA4Yjg="
        }
    }
}
```

---

Payload encryption

---
layout: detail
title: ACMC graphQL queries and mutations
menu_key: acmcroot
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-root/
---
---

[Queries and mutations overview](#mutationsoverview) 

<h4 name="mutationsoverview" id="mutationsoverview"></h4>

#### Queries and Mutations Overview

In GraphQL, operations are divided into two primary types: **Queries** and **Mutations**. Queries are used to retrieve data from the API, while Mutations allow for creating, updating, or deleting data. Both types provide powerful capabilities for interacting with the ACMC API, enabling developers to manage financial data with precision and flexibility.

[Core capabilities](#corecapabilities) 

<h4 name="corecapabilities" id="corecapabilities"></h4>

#### Core Capabilities:

- **Queries:** Efficiently fetch data such as accounts, transactions, and other entities. GraphQL allows you to request only the specific data fields you need, reducing unnecessary data transfer.

- **Mutations:** Manage data by creating, updating, or deleting entities such as payments, account details, or transaction entries, ensuring real-time updates and accuracy.

[Queries](#queries) 

<h4 name="queries" id="queries"></h4>


#### Queries

Queries are the read operation of GraphQL. They allow you to retrieve data from the server without modifying it. In ACMC’s API, the `bank` and `node` fields offer access to essential financial data such as account balances, approvals, payments, and more. Each query starts at the root `Query` type and can fetch both simple scalar fields and complex, nested objects.

[Key features of queries](#featuresofqueries) 

<h4 name="featuresofqueries" id="featuresofqueries"></h4>

#### Key Features of Queries:

- **Field Selection:** Only request the fields you need, minimizing response size.

- **Nested Queries:** Retrieve related data, such as transactions related to an account, within a single request.

- **Pagination:** Handle large datasets by requesting results in smaller chunks using the `first`, `last`, `before`, and `after` arguments.

- **Filtering:** Refine the results of queries based on specific conditions, such as retrieving only active accounts or transactions within a certain date range.

**List of ACMC Queriable Objects**

<table>
    <thead>
        <tr>
            <th>Query</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>bank</code></td>
            <td>
                The <strong>bank</strong> field is the primary entry point for accessing a wide range of financial data. It includes connections that allow you to query for information on accounts, approvals, payments, and more. Each of these connections supports pagination, filtering, and ordering.
                <ul>
                    <li><strong>Accounts:</strong> Retrieve details of bank accounts with pagination and filtering options, such as account status, balance, or account type. You can also order the results.</li>
                    <li><strong>Customers:</strong> Retrieve detailed customer information using the customers field.</li>
                    <li><strong>Business Processes, Payments, Products:</strong> Query business processes, payments, and financial products with similar filtering, pagination, and ordering features to retrieve relevant financial data efficiently.</li>
                    <li><strong>Reports and Receipts:</strong> Access report and receipt data using pagination and filtering mechanisms to narrow down the results to specific business needs.</li>
                </ul>
            </td>
        </tr>
        <tr>
            <td><code>heartbeat</code></td>
            <td>
                The <strong>heartbeat</strong> field provides basic system health information. It is used to confirm the current operational status of the ACMC API. The response typically includes uptime or simple diagnostic information, useful for monitoring the APIs availability.
            </td>
        </tr>
        <tr>
            <td><code>node</code></td>
            <td>
                The <strong>node</strong> field provides a powerful way to query any entity by its unique identifier (<code>ID</code>). This field allows you to:
                <ul>
                    <li><strong>Fetch any object by its ID:</strong> Retrieve specific entities, such as accounts or transactions, based on their globally unique <code>ID</code>. This is useful when you know the exact entity you're looking for and want to retrieve it directly.</li>
                </ul>
                <strong>Arguments:</strong>
                <ul>
                    <li><code>id</code>: (ID!): The unique identifier for the entity you are querying. This is required to fetch the specific entity.</li>
                </ul>
            </td>
        </tr>
    
    </tbody>
</table>


[Mutations](#mutations) 

<h4 name="mutations" id="mutations"></h4>

#### Mutations

Mutations allow developers to modify data within the ACMC platform. This includes operations like creating new accounts, updating transaction statuses, or initiating payments. Unlike queries, which are read-only, mutations change the underlying data and can return the affected objects, enabling developers to confirm successful updates in real-time.

[Key features of mutations](#featuresofmutations) 

<h4 name="featuresofmutations" id="featuresofmutations"></h4>

#### Key Features of Mutations:
- **Create, Update, Delete:** Perform various operations on entities such as creating payments, updating client details, or deleting transactions.

- **Input Fields:** Mutations often require input data, such as account information or payment details, which are passed via input types.

- **Immediate Feedback:** Mutations return the updated or created data, allowing developers to verify the changes made in real-time.
  
For example, when initiating a new payment, a mutation allows you to specify the recipient, amount, and payment method. The mutation will return a confirmation with the payment details, including the transaction ID and status.

**List of ACMC Mutation Operations**

- **Allocate**: Allocates an unallocated transaction to a client account.
- **Approve Request**: Sends an approval for a command awaiting approval.
- **Close Account**: Closes a client account.
- **Create Party Company**: Creates a new company party.
- **Create Party Individual**: Creates a new individual party.
- **Delete Party**: Deletes a party from the system.
- **Do Encrypted**: Processes an encrypted payload, typically used for sensitive operations.
- **Execute Aggregate Payment**: Executes an aggregate payment consisting of multiple instructions.
- **Make Internal Transfer**: Executes an internal transfer between two accounts within the same pool.
- **Move Account**: Moves an account to a different product.
- **Move Unallocated To CLA**: Moves an unallocated payment or receipt to a Customer Linked Account.
- **Open Account**: Opens a new account for a customer.
- **Request Payment From Customer Linked Account**: Initiates a payment request from a customer linked account to a CCM account.
- **Request Withholding Tax Refund**: Requests a withholding tax refund for a single account.
- **Unallocate**: Unallocates a previously allocated transaction.
- **Update Account**: Updates the details of an existing account.
- **Update Account Restraint**: Updates the customer level account restraint.

[Usage considerations](#usageconsiderations) 

<h4 name="usageconsiderations" id="usageconsiderations"></h4>

#### Usage Considerations

- **Field Selection:** Whether you are performing a query or mutation, always request only the fields you need to optimise performance.

- **Error Handling:** Mutations provide real-time feedback. Make sure to handle errors appropriately by checking the mutation response for any issues, such as validation errors or failed operations. 

- **Security:** Queries and mutations both require OAuth 2.0 authentication. Ensure your tokens are valid and refreshed as needed to maintain continuous access to the ACMC API.

[Performance optimisation](#performanceoptimisation) 

<h4 name="performanceoptimisation" id="performanceoptimisation"></h4>

#### Performance Optimisation:

- **Queries:** Limit the depth and size of your queries to avoid large responses that may affect performance.

- **Mutations:** Use input types to pass structured data efficiently and avoid sending unnecessary fields.

- **Pagination:** Use pagination to handle large datasets, requesting results in smaller chunks using the `first`, `last`, `before`, and `after` arguments.

- **Filtering:** Refine the results of queries and mutations based on specific conditions, such as retrieving only active accounts or transactions within a certain date range.

---
layout: detail
title: ACMC graphQL queries
menu_key: acmcroot
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-root/query/
---
---

[Queries Overview](#queriesoverview) 

<h4 name="queriesoverview" id="queriesoverview"></h4>

#### Queries Overview:

This page provides examples of GraphQL queries available in the ANZ Cash Management Central (ACMC) system.

[Table of Contents](#Contentof) 

<h4 name="contentof" id="contentof"></h4>

#### Table of Contents

1. [Bank Query](#bank-query)
2. [Heartbeat Query](#heartbeat-query)
3. [Node Query](#node-query)

[Bank Query](#bankquery) 

<h4 name="bankquery" id="bankquery"></h4>

#### Bank Query

The `bank` query is the primary entry point for accessing financial data in ACMC. It provides access to various banking entities and operations.

**Available Types under `bank`**

| Type | Description |
|------|-------------|
| accounts | List of bank accounts |
| approvals | Approval-related information |
| businessProcesses | Business process details |
| calendars | Calendar-related information |
| commands | Available commands |
| customers | Customer information |
| deleted | Deleted items |
| fileUploads | File upload information |
| interestAccrued | Interest accrual details (CustomerProductAccrual) |
| matchedReversals | Matched reversal transactions |
| namedRates | Named interest rates |
| payments | Payment transactions |
| pools | Pool-related information |
| products | Banking products |
| receipts | Receipt information |
| reports | Various reports |
| scheduledReports | Scheduled report information |
| sources | Source information |
| unallocated | Unallocated items or funds |
| withholdingTax | Withholding tax configuration |

This table represents the fields available under the `bank` query in the ACMC GraphQL API. Each field likely returns a specific type or a connection for that type, allowing access to detailed information or lists of items.


```graphql
query BankQuery {
  bank {
    accounts(first: 10) {
      edges {
        node {
          id
          accountNumber
        }
      }
    }
    customers(first: 10) {
      edges {
        node {
          id
         
        }
      }
    }
    payments(first: 5) {
      edges {
        node {
          id
          status
        }
      }
    }
    products(first: 5) {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}
```

This query demonstrates the structure of the `bank` type, which includes various financial entities. Each of these fields returns a connection type, allowing for pagination. The `first` argument specifies the number of items to retrieve.

You can modify this query to include other fields available in each type or apply filters as needed for your specific use case.

[Heartbeat Query](#heartbeatquery) 

<h4 name="heartbeatquery" id="heartbeatquery"></h4>

#### Heartbeat Query

The `heartbeat` query provides basic system information.

```graphql
query HeartbeatQuery {
  heartbeat {
    timestamp
  }
}
```

This query returns a timestamp, which can be used to verify that the ACMC API is responsive.

[Node Query](#nodequery) 

<h4 name="nodequery" id="nodequery"></h4>

#### Node Query

The `node` query allows you to fetch any entity by its unique identifier. In this example, we'll demonstrate how to fetch account information using an account ID.

```graphql
query NodeQuery($id: ID!) {
  node(id: $id) {
    __typename
    ... on Account {
      id
      accountNumber
      currencies
    }
  }
}
```

**Variables**

```json
{
  "id": "AccountID"
}
```

This query demonstrates how to fetch account information using the Node query:

1. Replace `AccountID` in the variables with the actual ID of the account you want to retrieve.
2. The `node` query uses this ID to locate the specific account in the system.
3. The `__typename` field returns the type of the node, which in this case would be "Account".
4. The `... on Account` fragment specifies which fields to return if the node is an Account type.
5. The query will return the account's ID, account number, and currencies.

This approach allows you to fetch detailed account information using only the account's unique identifier, demonstrating the power and flexibility of the Node query in the ACMC GraphQL API.

---

These examples showcase the main query operations available in the ACMC GraphQL API. You can expand on these queries to access more specific data as needed for your application. For a full list of queries and mutations, please refer to the [full ACMC GraphQL schema documentation](/product/ACMC%20API/code?path=GraphQL%20schema) and [dedicated sample pages](/product/ACMC%20API/code?path=GraphQL%20API%20examples).



<style>
  ol {
    list-style-type: decimal; /* This ensures numbers appear in ordered list */
    padding-left: 20px;
  }

  ul {
    list-style-type: disc; /* This ensures bullet points appear in unordered list */
    padding-left: 20px;
  }

---
layout: detail
title: ACMC graphQL mutations
menu_key: acmcroot
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-root/mutation/
---
---

[Mutations overview](#mutationoverview) 

<h4 name="mutationoverview" id="mutationoverview"></h4>

#### Mutations Overview:

This page provides an overview of GraphQL mutations available in the ANZ Cash Management Central (ACMC) system.


[Allocate](#alocatet) 

<h4 name="alocatet" id="alocatet"></h4>

#### Allocate
Allocates an unallocated transaction to a client account.

| Field Name | Description |
|------------|-------------|
| accountId | ID of the account the transaction is to be allocated to. |
| unallocatedId | Unique ID of the Payment or Receipt to be allocated. |
| allocationComment | An optional comment to include with the allocation. |


[Approve request](#approverequest) 

<h4 name="approverequest" id="approverequest"></h4>

#### Approve Request
Sends an approval for a command awaiting approval.

| Field Name | Description |
|------------|-------------|
| id         | The ID of the approval process. This is not the command ID; please see the approvals list. |
| reason     | Reason for the response you are giving |
| tokenCode  | Optional generated one-time use token. This may be required for the overall approval as determined via the config. |

[Close account](#closeaccount) 


<h4 name="closeaccount" id="closeaccount"></h4>

#### Close Account
Closes a client account.

| Field Name | Description |
|------------|-------------|
| accountId | The unique id of the account to be closed. |
| fundsDestination | Destination for the funds, of type DERecipient. |


[Create party company](#partycompany) 

<h4 name="partycompany" id="partycompany"></h4>

#### Create Party Company
Creates a new company party.

| Field Name | Description |
|------------|-------------|
| alternateAddress | Alternate address |
| businessNumber | Australian Business Number issued by the Australian Tax Office |
| clientClassification | Client/Beneficiary classification |
| companyNumber | Australian Company Number provided by ASIC as part of the registration process |
| companyType | The subtype of the company which determines allowed fields downstream |
| controllingPersons | A list of individual party ids who have the role of controlling person |
| countryOfEffectiveManagement | Country of effective management |
| countryOfEstablishment | Country where the company was established |
| customerId | Customer the party will be created for |
| email | E-mail |
| fullName | Name of the company |
| giin | The Global Intermediary Identification Number |
| incorporationCountry | Country of Incorporation/Registration |
| incorporationDate | Date of Incorporation/Registration |
| noTaxResidency | Whether the company has no residency for tax purposes |
| reference | External party reference |
| registeredBodyNumber | Australian Registered Body Number provided by ASIC - 9 digits all numerical |
| registeredOfficeAddress | Registered Office Address. Cannot be a PO Box |
| roles | The roles this party can be on an account |
| selfCertified | Self-certification date |
| stockExchange | Name of Stock Exchange. Optional only to be used for public companies type |
| taxReportingType | Tax reporting type |
| taxResidencies | Tax residencies |
| tradingName | Could be different from the full legal name of the company on the registration certificate |
| workPhone | Work phone |

[Create party individual](#partyindividual) 


<h4 name="partyindividual" id="partyindividual"></h4>

#### Create Party Individual
Creates a new individual party.

| Field Name | Description |
|------------|-------------|
| alternateAddress | Alternate address for the individual. |
| customerId | The customer the individual is client of. |
| dateOfBirth | The individual's date of birth. Must be provided if the individual is being registered as 'self-certified'. |
| familyName | The individual's family (last) name. |
| gender | The individual's gender. |
| givenName | The individual's given (first) name. |
| otherGivenNames | List of names, other than given or family, for the individual. |
| reference | Customer provided reference for the individual. This must be unique over all individuals of the customer. |
| residentialAddress | The individual's main residential address. Must not be a PO Box or other restricted address for KYC compliance. |
| roles | List of roles the individual may perform on accounts or companies (Beneficiary, Trustee or Controlling Person). |
| selfCertified | Is the individual being registered as self certified for tax reporting purposes. |
| taxResidencies | List of all countries the individual has tax residency obligations in. |
| title | The individual's title. |


[Delete party](#deleteparty) 

<h4 name="deleteparty" id="deleteparty"></h4>

#### Delete Party
Deletes a party from the system.

| Field Name | Description |
|------------|-------------|
| partyId | The id of the individual to be deleted. |

[DoEncrypted](#doencrypted) 

<h4 name="do-encrypted" id="doencrypted"></h4>

#### DoEncrypted

Processes an encrypted payload, typically used for sensitive operations.

| Field Name | Description |
|------------|-------------|
| customerId | The customer to whom the encrypted payload relates. This value is optional and ignored for customer users, and required for bank users. |
| encryptedPayload | The encrypted data payload. |

[Execute aggregate payment](#aggregatepayment) 

<h4 name="aggregatepayment" id="aggregatepayment"></h4>

#### Execute Aggregate Payment
Executes an aggregate payment consisting of multiple instructions.

| Field Name | Description |
|------------|-------------|
| count | Total count of instructions |
| customerTransactionReference | An optional reference that can later be used to search for the AggregatePayment |
| externalAccount | Details of the external account for the aggregate payment |
| instructions | List of payment instructions |
| reference | Common reference to be associated with all transactions included in the aggregate payment |
| totalAmount | Sum of all instructions |

[Make internal transfer](#internaltransfer) 

<h4 name="internaltransfer" id="internaltransfer"></h4>

#### Make Internal Transfer
Executes an internal transfer between two accounts within the same pool.

| Field Name | Description |
|------------|-------------|
| creditingAccount | The account number of the account to be credited. |
| customerTransactionReference | A message about the transfer. The reference will be available to the recipient of the transfer. |
| debitingAccount | The account number of the account to be debited. |
| payeeReference | TBD |
| payerReference | TBD |
| pool | The pool the accounts are held under. |
| transferAmount | The value of the transfer. |
| valueDate | Value date to be applied to the transfers. |


[Move account](#moveaccount) 

<h4 name="moveaccount" id="moveaccount"></h4>

#### Move Account
Moves an account to a different product.

| Field Name | Description |
|------------|-------------|
| accountId | The ID of the account to be moved. |
| productId | The ID of the product to which the account will be moved. |

[Move unallocated to CLA](#unallocatedtocla) 

<h4 name="unallocatedtocla" id="unallocatedtocla"></h4>

#### Move Unallocated to CLA
Moves an unallocated payment or receipt to a Customer Linked Account.

| Field Name | Description |
|------------|-------------|
| allocatableId | Unique id of the Payment or Receipt to be moved. |
| customerLinkedAccountId | ID of the customer linked account for the destination of the money. |


[Open account](#openaccount) 

<h4 name="openaccount" id="openaccount"></h4>

#### Open Account
Opens a new account for a customer.

| Field Name | Description |
|------------|-------------|
| currency | Deprecated. Ignored if supplied. Currency is controlled by the product the account is opened with. |
| customerId | The customer that manages the account on behalf of a client. |
| name | The operating name of the account. |
| parties | List of one or more beneficiaries, trustees etc. associated with the account. |
| product | The product that controls the capabilities and restrictions the account follows. |
| reference | An optional reference for the account that may be used in auto allocation of transactions to the account. |
| secondaryReference | An additional optional reference for the account. |

[Request payment from customer linked account](#customerlinkedaccount) 

<h4 name="customerlinkedaccount" id="customerlinkedaccount"></h4>

#### Request Payment From Customer Linked Account
Initiates a payment request from a customer linked account to a CCM account.

| Field Name | Description |
|------------|-------------|
| customerLinkedAccountId | ID of the customer linked account the money is to be sent from |
| customerTransactionReference | An optional reference that can later be used to search for the PaymentRequest |
| paymentAmount | Value of the payment |
| reference | A message about the payment. The reference will be sent to the recipient of the payment |
| requesterAccountId | ID of the CCM account making the request |
| valueDate | Value date to be applied to the payment |

[Request withholding tax refund](#withholdingtaxrefund) 

<h4 name="withholdingtaxrefund" id="withholdingtaxrefund"></h4>

#### Request Withholding Tax Refund
Requests a withholding tax refund for a single account.

| Field Name | Description |
|------------|-------------|
| accountId | Account id for the account requesting refund |


[Update account](#updateaccount) 

<h4 name="updateaccount" id="updateaccount"></h4>

#### Update Account
Updates the details of an existing account.

| Field Name | Description |
|------------|-------------|
| accountId | The id of the account to be updated |
| name | The new operating name of the account |
| reference | The new reference for the account |
| secondaryReference | A new secondary reference for the account |

[Update client account restraint](#accountrestraint) 

<h4 name="accountrestraint" id="accountrestraint"></h4>


#### Update Client Account Restraint

Updates the customer level account restraint.

| Field Name | Description |
|------------|-------------|
| accountId | The id of the account to which the restraint will be applied |
| block | The type of block or restraint to be applied to the account |

---

This overview provides a summary of key mutation operations available in the ACMC GraphQL API, including their input fields and basic structure. For more comprehensive information, detailed usage examples, and the complete set of available operations, please refer to the [full ACMC GraphQL schema documentation](/product/ACMC%20API/code?path=GraphQL%20schema) and [dedicated sample pages](/product/ACMC%20API/code?path=GraphQL%20API%20examples).


<style>
  ol {
    list-style-type: decimal; /* This ensures numbers appear in ordered list */
    padding-left: 20px;
  }

  ul {
    list-style-type: disc; /* This ensures bullet points appear in unordered list */
    padding-left: 20px;
  }

Mutation

---
layout: detail
title: ACMC graphQL types
menu_key: types
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-types/
---
---

[ACMC graphQL types overview](#typesoverview) 

<h4 name="typesoverview" id="typesoverview"></h4>

#### ACMC GraphQL types Overview

The ANZ Cash Management Central (ACMC) GraphQL schema is built using a variety of core GraphQL types. These types structure the API, allowing flexible and efficient querying of data. Below is an overview of the main GraphQL types used in ACMC, along with important concepts regarding mandatory (non-nullable) and optional (nullable) fields.


[GraphQL types in ACMC](#typesinacmc) 

<h4 name="typesinacmc" id="typesinacmc"></h4>

#### GraphQL types in ACMC

- **Object Types:** Object types are the core entities in the ACMC schema, representing structured data such as `Account`, `PartyIndividual`, and `Payment`. These types define fields that can either reference scalar values (e.g., `String`, `Int`) or other object types, allowing complex and nested queries.

- **Enum Types:** Enum types provide a limited set of predefined values for specific fields. For instance, an `AccountStatus` enum might return `ACTIVE`, `INACTIVE`, or `CLOSED`. Enums ensure consistent responses and improve data integrity.

- **Scalar Types:** Scalars represent the simplest data types in GraphQL, and are used for the basic fields in object types and ensure concise, consistent data.
  - `Int` for integers
  - `Float` for decimals
  - `String` for text
  - `Boolean` for true/false
  - `ID` for unique identifiers

- **Input Types:** Input types are used in mutations to pass structured data to the API. For example, when creating an account, you might use an `OpenAccountInput` input type to provide fields like `accountType` and `name`. Input types ensure the correct data structure is passed during operations.

- **Interface Types:** Interfaces allow different object types to share common fields. For instance, `BusinessProcess` implement a shared interface that includes fields such as `transactions` and `id`. This ensures consistency across object types with common attributes.

[Nullability in graphQL](#graphql) 

<h4 name="graphql" id="graphql"></h4>

#### Nullability in GraphQL

In GraphQL, fields are **nullable by default**, meaning they can return `null` if data is unavailable or an error occurs. This design helps maintain partial results in the event of system failures or authorisation issues, ensuring the entire query doesn't fail.
  
- **Mandatory (Non-Nullable) Fields:** A non-nullable field guarantees a value will always be returned. Non-nullable fields are marked with an exclamation mark (`!`) in the schema, such as `String!`. If a non-nullable field cannot be resolved, the parent field will return `null` instead, propagating the error upward.
  
- **Optional (Nullable) Fields:** Fields that are nullable can return `null` if necessary. They are are indicated as `Type` without the exclamation mark. These fields are useful when data might not always be available, such as an optional `middleName` field in a `User` profile.

[Best practices for nullability](#fornullability) 

<h4 name="fornullability" id="fornullability"></h4>

#### Best Practices for Nullability:
- **Use nullable fields** for optional or non-critical information where failure or lack of data is acceptable.

- **Use non-nullable fields** for critical data that is required for the operation's success. Consider the impact of failure on query execution, and whether the entire query or just individual fields should fail.

- **Design for resilience** by leveraging nullable fields to handle network, database, or authorisation errors without halting the entire query response.

---
layout: detail
title: ACMC graphQL OBJECT types
menu_key: types
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-types/object/
---
---
Object types form the backbone of the ACMC schema, representing key entities and their relationships within the banking system. These types, such as `Account`, `PartyIndividual`, and `Payment`, encapsulate structured data and serve as the building blocks for complex queries and operations.

Each object type consists of fields that can be either scalar values (like `String` or `Int`) or references to other object types, enabling the creation of intricate, nested data structures. This design allows for flexible and powerful querying capabilities.

[Examples of how object types can be used](#beused) 

<h4 name="beused" id="beused"></h4>

Examples of how object types can be used:

1. `Account` type: 
- Retrieve account details: Get the balance, accountNumber, and associated information for a specific account.

2. `Customer` type: 
- Retrieve customer details: Get information about a customer, including associatedParty, designatedInterestAccount, and associated product details.

3. `PartyIndividual` type: 
- Retrive party details: Get information about individual beneficiaries, such as first name, last name, and residentialAddress

[OBJECT types examples](#objecttypexample) 

<h4 name="objecttypexample" id="objecttypexample"></h4>

**OBJECT TYPES EXAMPLES**

<table>
    <thead>
        <tr>
            <th>Name</th>
            <th>Description</th>
            <th>Mandatory Fields</th>
            <th>Non-Mandatory Fields</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Account</td>
            <td>Full details of a bank account. In addition to balance and transaction details Account
also provides information on parties associated with the account, capabilities of the account etc.</td>
            <td>
                - accountNumber<br>
                - accountProductMovements<br>
                - balances<br>
                - bankCode<br>
                - closeAccountProcesses<br>
                - closeTimestamp<br>
                - currencies<br>
                - customer<br>
            </td>
            <td>
                - interest<br>
                - secondaryReference
            </td>
        </tr>   
        <tr>
            <td>Address</td>
            <td>An address.</td>
            <td>countryCode</td>
            <td>city, line1, line2, postCode, state</td>
        </tr>
        <tr>
            <td>CommandError</td>
            <td>Detailed error information for a command in the case of a failure.</td>
            <td>
                - code<br>
                - path<br>
                - reason
            </td>
            <td>N/A</td>
        </tr>    
        <tr>
            <td>CommandResponse</td>
            <td>Processing of all mutations is asynchronous with a command id returned to acknowledge receipt of the
request and to enable tracking of it's progress. The command id can be subsequently queried
to determine if the request completed successfully. Basic schema validation is performed synchronously
on receipt of the request.</td>
            <td>commandId</td>
            <td>N/A</td>
        </tr>
        <tr>
            <td>Customer</td>
            <td>The Customer type represents a customer in the system and implements the Node interface. It provides a wide range of details about the customer, such as accounts, transaction history, approvals, and system-related details. The Customer type also supports various filters for querying connected data, such as business processes, accounts, and reports. It includes both essential identification and optional customer attributes, such as reporting status and KYC information.</td>
            <td>
                - accounts<br>
                - actionControlDateLimits<br>
                - autoSweepAvailable<br>
                - autoSweepEnabled<br>
                - blockDirectDebits<br>
                - displayName<br>
                - fullName<br>
                - id<br>
                - interest<br>
                - reporter<br>
                - reportingFinancialInstitution<br>
                - usFinancialInstitution
            </td>
            <td>
                - aggregateTransactions<br>
                - apcaDirectEntryCreditId<br>
                - apcaDirectEntryDebitId<br>
                - approvals<br>
                - associatedParty<br>
                - authLink<br>
                - autoSweepDetails<br>
                - billingId<br>
                - businessProcesses<br>
                - coreSystemDetails<br>
                - counterpartyType<br>
                - designatedInterestAccount<br>
                - giin<br>
                - knowYourCustomerId<br>
                - linkedAccounts<br>
                - namedRates<br>
                - parties<br>
                - pools<br>
                - products<br>
                - scheduledReports<br>
                - sourceAccountAliases<br>
                - sources
            </td>
        </tr>
        <tr>
            <td>CustomerOnboarded</td>
            <td>Update containing details of a newly onboarded customer.</td>
            <td>N/A</td>
            <td>customer</td>
        </tr>
        <tr>
            <td>FeatureGraph</td>
            <td>Use this to determine valid product specialisations.</td>
            <td>N/A</td>
            <td>features</td>
        </tr>  
        <tr>
            <td>GrantedProductToCustomer</td>
            <td>Product Subscriptions</td>
            <td>N/A</td>
            <td>customer</td>
        </tr>  
        <tr>
            <td>IndividualTaxResidency</td>
            <td>Details of an individuals tax residency.</td>
            <td>
                - countryCode<br>
                - tin<br>
                - tinMissingExplanation<br>
                - tinMissingReason
            </td>
            <td>N/A</td>
        </tr>
        <tr>
            <td>NonIndividualTaxResidency</td>
            <td>Details of a non-individuals tax residency.</td>
            <td>
                - countryCode<br>
                - tin<br>
                - tinMissingExplanation<br>
                - tinMissingReason
            </td>
            <td>N/A</td>
        </tr>
    </tbody>
</table>

---

These examples showcase the main object types available in the ACMC GraphQL API. You can expand on these object types to access more specific data as needed for your application. For a full list of object types, please refer to the [full ACMC GraphQL schema documentation](/product/ACMC%20API/code?path=GraphQL%20schema) and [dedicated sample pages](/product/ACMC%20API/code?path=GraphQL%20API%20examples).


<style>
 table {
  border-collapse: collapse;
  width: 100%;
  table-layout: fixed; /* Ensures equal column width */
  margin-bottom: 1em;
}

th, td {
  border: 1px solid #ddd;
  padding: 8px;
  vertical-align: top;
  word-wrap: break-word; /* Ensures text wraps properly */
  text-align: left;
}

th {
  background-color: #f2f2f2;
}

td {
  line-height: 1.4;
}

</style>

OBJECT

---
layout: detail
title: ACMC graphQL ENUM type
menu_key: types
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-types/enum/
---
---
ENUM types in the ACMC schema provide a way to define a fixed set of values for specific fields, ensuring data consistency and improving query efficiency. These types, such as `AccountOpenState`, `CommandState`, and `PartyType`, represent predefined sets of options that can be used across various parts of the schema.

[Examples of how ENUM types can be used in the ACMC schema](#enumtypes) 

<h4 name="enumtypes" id="enumtypes"></h4>

Examples of how ENUM types can be used in the ACMC schema:

1. `AccountOpenState`:
   - Possible values: OPEN, CLOSING, CLOSED
   - Use case: Indicating the current status of an account in its lifecycle.

2. `CommandState`:
   - Possible values: SUBMITTED, SUCCESSFUL, PARTIALLY_SUCCESSFUL, FAILED
   - Use case: Indicating the current state of a command in the system.

3. `PartyType`:
   - Possible values: INDIVIDUAL, COMPANY, TRUST, ASSOCIATION
   - Use case: Categorizing the types of parties in the system.

[ENUM types examples](#typesexamples) 

<h4 name="typesexamples" id="typesexamples"></h4>

**ENUM TYPES EXAMPLES**

<table>
        <thead>
            <tr>
                <th>Name</th>
                <th>Description</th>
                <th>Possible Values</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>AUWithholdingTaxDesignation</td>
                <td>Specifies the withholding tax status for Australian accounts</td>
                <td>EXEMPT, SELF_REPORTING, RESIDENT_WITHHOLDING_TAX, NON_RESIDENT_WITHHOLDING_TAX</td>
            </tr>
            <tr>
                <td>AccountOpenState</td>
                <td>Represents the current operational state of an account</td>
                <td>OPEN, CLOSING, CLOSED</td>
            </tr>
            <tr>
                <td>AccrualType</td>
                <td>Defines the types of accrual events for financial calculations</td>
                <td>SCHEDULED, CLOSURE, BALANCE_ADJUSTMENT, RATE_ADJUSTMENT, PRODUCT_MOVEMENT, ON_DEMAND</td>
            </tr>
            <tr>
                <td>AggregateInstructionState</td>
                <td>Indicates the processing status of aggregate instructions</td>
                <td>PROCESSING, SUCCEEDED, FAILED</td>
            </tr>
            <tr>
                <td>AggregatePaymentMethod</td>
                <td>Specifies the method used for aggregate payments</td>
                <td>DE, NPP, RTGS</td>
            </tr>
            <tr>
                <td>AggregatePaymentState</td>
                <td>Represents the current state of an aggregate payment</td>
                <td>PROCESSING, COMPLETE</td>
            </tr>
            <tr>
                <td>AggregatePaymentType</td>
                <td>Defines the types of aggregate payments</td>
                <td>DE, NPP, RTGS</td>
            </tr>
            <tr>
                <td>AllocationState</td>
                <td>Indicates the current state of an allocation process</td>
                <td>PENDING, ALLOCATED, UNALLOCATED, FAILED, MATCHED, MOVING_TO_CLA, MOVED_TO_CLA, DELETED, DELETION_REQUESTED, RESTORATION_REQUESTED, SPLITTING, SPLIT, DEFERRED</td>
            </tr>
            <tr>
                <td>ApprovalRole</td>
                <td>Defines the roles involved in an approval process</td>
                <td>APPROVER, INSTIGATOR, REJECTOR</td>
            </tr>
            <tr>
                <td>ApprovalState</td>
                <td>Represents the current state of an approval process</td>
                <td>PENDING, APPROVING, APPROVED, REJECTED</td>
            </tr>
            <tr>
                <td>BusinessProcessType</td>
                <td>N/A</td>
                <td>RECEIPT, PAYMENT, PAYMENT_REQUEST, INTERNAL_TRANSFER, INTEREST, MANUAL_INTEREST_ADJUSTMENT, WITHHOLDING_TAX_ACCOUNT_REFUND, AGGREGATE_PAYMENT</td>
            </tr>
            <tr>
                <td>CommandState</td>
                <td>The current processing state of a command.</td>
                <td>SUBMITTED, SUCCESSFUL, PARTIALLY_SUCCESSFUL, FAILED</td>
            </tr>
            <tr>
                <td>IncorporatedAssociationType</td>
                <td>N/A</td>
                <td>INCORPORATED</td>
            </tr>
            <tr>
                <td>IndividualTINMissingReason</td>
                <td>N/A</td>
                <td>NOT_ISSUED, NOT_REQUIRED, APPLIED_FOR, UNOBTAINABLE, NOT_PROVIDED, NO_TAX_RETURN_REQUIRED, NON_RESIDENT, PENSIONER, PENSION_OR_BENEFITS</td>
            </tr>
            <tr>
                <td>KYCStatus</td>
                <td>Indicates the status of Know Your Customer (KYC) verification</td>
                <td>COMPLETE, NEW, OBSOLETE, PARTIALLY_COMPLETE</td>
            </tr>
            <tr>
                <td>NonIndividualClientClassification</td>
                <td>Classifies non-individual clients into categories</td>
                <td>COMPANY, TRUST, FI, OTHER, SMSF</td>
            </tr>
            <tr>
                <td>NonIndividualTINMissingReason</td>
                <td>Specifies reasons for missing Tax Identification Numbers for non-individual entities</td>
                <td>NOT_ISSUED, NOT_REQUIRED, APPLIED_FOR, UNOBTAINABLE, NOT_PROVIDED, NO_TAX_RETURN_REQUIRED, NON_RESIDENT</td>
            </tr>
            <tr>
                <td>NonIndividualTaxReportingType</td>
                <td>Tax reporting types applicable for companies or trusts.</td>
                <td>EXEMPT_ENTITY, MANAGED_INVESTMENT_ENTITY_CRS_COUNTRY, FINANCIAL_INSTITUTION, ACTIVE_NON_FINANCIAL_ENTITY, MANAGED_INVESTMENT_ENTITY_NON_CRS_COUNTRY, PASSIVE_NON_FINANCIAL_ENTITY</td>
            </tr>
            <tr>
                <td>PartyTrustOffshoreUnregulatedTestamentaryType</td>
                <td>Defines the type for offshore unregulated testamentary trusts</td>
                <td>OFFSHORE_UNREGULATED_TESTAMENTARY</td>
            </tr>
            <tr>
                <td>PartyTrustOffshoreUnregulatedUnitType</td>
                <td>Specifies the type for offshore unregulated unit trusts</td>
                <td>OFFSHORE_UNREGULATED_UNIT</td>
            </tr>
            <tr>
                <td>PartyType</td>
                <td>Categorizes the types of parties in the system</td>
                <td>INDIVIDUAL, COMPANY, TRUST, ASSOCIATION, COOPERATIVE, PARTNERSHIP, GOVERNMENT_BODY</td>
            </tr>
            <tr>
                <td>PaymentRequestMethod</td>
                <td>Defines the methods available for payment requests</td>
                <td>DE, NPP</td>
            </tr>
            <tr>
                <td>PaymentRequestStatus</td>
                <td>Indicates the current status of a payment request</td>
                <td>SUBMITTED, RECEIVED, PROCESSING, PENDING, REJECTED, COMPLETED, COMPLETED_WITH_ERRORS</td>
            </tr>
            <tr>
                <td>PaymentState</td>
                <td>Represents the current state of a payment</td>
                <td>SUBMITTED, RECEIVED, PENDING, PROCESSING, COMPLETED, COMPLETED_WITH_ERRORS, REJECTED</td>
            </tr>
            <tr>
            <td>ReportingFinancialInstitution</td>
                <td>Indicates whether an entity is a reporting financial institution</td>
                <td>YES, NO</td>
            </tr>
            <tr>
                <td>Role</td>
                <td>Defines the roles associated with a party in the system</td>
                <td>BENEFICIARY, TRUSTEE, CONTROLLING_PERSON</td>
            </tr>
            <tr>
                <td>TinMissingReason</td>
                <td>Specifies reasons for missing Tax Identification Numbers</td>
                <td>APPLIED_FOR, FINANCE_PROVIDER, NO_TAX_RETURN_REQUIRED, NON_RESIDENT, NOT_ISSUED, NOT_PROVIDED, NOT_REQUIRED, PENSION_OR_BENEFITS, PENSIONER, UNDER_16, UNOBTAINABLE</td>
            </tr>
            <tr>
                <td>TransactionState</td>
                <td>Indicates the current state of a transaction</td>
                <td>PENDING, SUCCESSFUL, FAILED</td>
            </tr>
            <tr>
                <td>UnallocatedReasonCode</td>
                <td>Specifies reasons for unallocated funds or transactions</td>
                <td>MULTIPLE_DESTINATIONS, NO_DESTINATION, TRANSACT_FAILED, MANUAL_UNALLOCATION, REVERSAL, UNMATCHED, BLOCKED_DIRECT_DEBIT, PAYMENT_REJECTED, PAYMENT_REQUEST_REJECTED, DELETION_DENIED, RESTORED</td>
            </tr>
            <tr>
                <td>VerificationStatuses</td>
                <td>Represents the possible statuses of a verification process</td>
                <td>ESCALATE, NON_VERIFIED, NON_VERIFIED_MIGRATED, RE_VERIFICATION_REQUIRED, VERIFIED_MIGRATED</td>
            </tr>
        </tbody>
</table>

---

This overview provides a summary of key ENUM types available in the ACMC GraphQL API, including their possible values and basic use cases. For more comprehensive information, detailed usage examples, and the complete set of available ENUM types, please refer to the [full ACMC GraphQL schema documentation](/product/ACMC%20API/code?path=GraphQL%20schema) and [dedicated sample pages](/product/ACMC%20API/code?path=GraphQL%20API%20examples).

ENUM

---
layout: detail
title: ACMC graphQL SCALAR type
menu_key: types
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-types/scalar/
---
---
SCALAR types in the ACMC schema represent fundamental data types that serve as the building blocks for more complex structures. These types are used to define atomic values and cannot be subdivided further. SCALAR types are essential for representing basic information such as text, numbers, dates, and boolean values.

[Common SCALAR types in the ACMC schema include](#schemainclude) 

<h4 name="schemainclude" id="schemainclude"></h4>

Common SCALAR types in the ACMC schema include:

1. `String`: For text-based data (e.g., names, descriptions)
2. `Int`: For whole number values (e.g., counts, identifiers)
3. `Float`: For decimal number values (e.g., monetary amounts)
4. `Boolean`: For true/false values
5. `ID`: For unique identifiers
6. `Date` and `DateTime`: For date and time representations

Custom SCALAR types may also be defined to handle specific data formats or validation requirements unique to the ACMC system.

[Scalar types examples](#examples) 

<h4 name="examples" id="examples"></h4>

**SCALAR TYPES EXAMPLES**

<table>
    <thead>
        <tr>
            <th>Name</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>AccountNumber</code></td>
            <td>The account number of a bank account (maximum of 28 characters).</td>
        </tr>
        <tr>
            <td><code>BankCode</code></td>
            <td>The 6-digit bank code used to identify a specific bank.</td>
        </tr>
        <tr>
            <td><code>Boolean</code></td>
            <td>A true or false value.</td>
        </tr>
        <tr>
            <td><code>CountryShortCode</code></td>
            <td>Two-letter country code, typically following the ISO 3166 standard.</td>
        </tr>
        <tr>
            <td><code>CurrencyCode</code></td>
            <td>ISO 4217 three-letter currency code (e.g., USD, EUR).</td>
        </tr>
        <tr>
            <td><code>Date</code></td>
            <td>A date in the format YYYY-MM-DD.</td>
        </tr>
        <tr>
            <td><code>DateTime</code></td>
            <td>A date-time value in ISO 8601 format.</td>
        </tr>
        <tr>
            <td><code>ID</code></td>
            <td>A unique identifier, typically used for identifying entities.</td>
        </tr>
        <tr>
            <td><code>Int</code></td>
            <td>An integer value.</td>
        </tr>
        <tr>
            <td><code>String</code></td>
            <td>A UTF-8 string value.</td>
        </tr>
    </tbody>
</table>

---

This overview provides a summary of key SCALAR types available in the ACMC GraphQL API, including their descriptions and basic use cases. For more comprehensive information, detailed usage examples, and the complete set of available SCALAR types, please refer to the [full ACMC GraphQL schema documentation](/product/ACMC%20API/code?path=GraphQL%20schema) and [dedicated sample pages](/product/ACMC%20API/code?path=GraphQL%20API%20examples).

SCALAR

---
layout: detail
title: ACMC graphQL INPUT type
menu_key: types
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-types/input_type/
---

---

INPUT types in the ACMC schema provide a way to define the input parameters for queries and mutations. They are similar to object types but are specifically designed to carry data into the system. INPUT types are ideal for representing input parameters for queries and mutations, allowing for structured data input and validation.

[Examples of how INPUT types can be used in the ACMC schema](#inputtypes) 

<h4 name="inputtypes" id="inputtypes"></h4>

Examples of how INPUT types can be used in the ACMC schema:

1. `AccountFilter`:

   - Use case: Filtering accounts based on various criteria such as account number, name, bank code, and open states.
   - Example: `filter: {nameExact: "Account One", accountNumberContains: "1234"}`

2. `CreatePartyIndividualInput`:

   - Use case: Creating a new individual party in the system with personal details, addresses, and tax information.
   - Fields include: alternateAddress, customerId, dateOfBirth, familyName, gender, givenName, otherGivenNames, reference, residentialAddress, roles, selfCertified, taxResidencies, title

3. `AggregateInstructionOrdering`:
   - Use case: Specifying the ordering of aggregate instruction results.
   - Fields: direction (ascending or descending), sort (field to sort by)
   - Example: `ordering: {direction: ASC, sort: TIMESTAMP}`

[INPUT types examples](#typesexamples) 

<h4 name="typesexamples" id="typesexamples"></h4>

**INPUT TYPES EXAMPLES**

<table>
    <thead>
        <tr>
            <th>Name</th>
            <th>Description</th>
            <th>Fields</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>AccountFilter</td>
            <td>A filter for querying accounts. A simple use of this filter might look like:

`filter: {nameExact:"Account One"}`

A filter with a top level 'or' might look like:

`filter: {or: [{nameExact: "Account One"}, {accountNumberContains: "1234"}]}`
</td>
<td>accountNumberContains, accountNumberExact, accountReferenceContains, accountReferenceExact, and, bankCode, internal, nameContains, nameExact, openStates, or, showClasses</td>
</tr>
<tr>
<td>AccountInterestFilter</td>
<td>A filter for querying account interest. It allows filtering based on the exact currency of the interest.</td>
<td>currencyExact</td>
</tr>
<tr>
<td>AccountOrdering</td>
<td>Specifies the ordering of account results. It allows setting the direction (ascending or descending) and the field to sort by.</td>
<td>direction, sort</td>
</tr>
<tr>
<td>AccrualTimeInput</td>
<td>Input type for specifying accrual time details. It includes the currency, time, and timezone information for accurate accrual calculations.</td>
<td>currency, time, timeZone</td>
</tr>
<tr>
<td>ActionControlDateLimitInput</td>
<td>Input type for setting date limits on various actions. It allows specifying limits for allocation, matching, and unallocation processes.</td>
<td>allocation, matching, unallocation</td>
</tr>
<tr>
<td>AddressInput</td>
<td>An input type for entering address details. It includes fields for various components of a standard address, allowing for structured address data entry.</td>
<td>city, countryCode, line1, line2, postCode, state</td>
</tr>
<tr>
<td>AggregateInstructionFilter</td>
<td>A filter for querying aggregate instructions. A simple use of this filter might look like:

`filter: {narrativeExact:"Narrative One"}`

A filter with a top level 'or' might look like:

`filter: {or: [{narrativeExact:"Narrative One"}, {tracingIdContains: "Tracing ID Two"}]}`</td>
<td>and, narrativeContains, narrativeExact, or, state, tracingIdContains, tracingIdExact</td>
</tr>
<tr>
<td>AggregateInstructionOrdering</td>
<td>Specifies the ordering of aggregate instruction results. It allows setting the direction (ascending or descending) and the field to sort by.</td>
<td>direction, sort</td>
</tr>
<tr>
<td>AggregatePaymentExternalAccountInput</td>
<td>Input type for specifying external account details for aggregate payments. It includes fields for the account and CLA (Client Ledger Account) ID.</td>
<td>account, claId</td>
</tr>
<tr>
<td>AggregatePaymentFilter</td>
<td>A filter for querying aggregate payments. It allows filtering based on amount and reference details.</td>
<td>amount, referenceContains, referenceExact</td>
</tr>
<tr>
<td>AggregatePaymentOrdering</td>
<td>Defines the ordering for aggregate payment results. It allows specifying the direction and sort field for the results.</td>
<td>direction, sort</td>
</tr>
<tr>
<td>AllocatableFilter</td>
<td>A filter for querying allocatable items. It provides various fields to filter allocatable transactions based on type, state, amount, and narrative.</td>
<td>allocatableType, allocationState, amount, hold, narrativeContains, narrativeExact, reversal</td>
</tr>
<tr>
<td>AllocatableOrdering</td>
<td>Specifies the ordering of allocatable item results. It allows setting the direction and the field to sort by.</td>
<td>direction, sort</td>
</tr>
<tr>
<td>AllocateDeferredInput</td>
<td>Options for allocation of an unallocated/deferred interest payment or receipt to a client account. It includes fields for allocation comment and the ID of the deferred allocatable.</td>
<td>allocationComment, deferredAllocatableId</td>
</tr>
<tr>
<td>AllocateInput</td>
<td>Options for allocation of an unallocated payment or receipt to a client account. It includes fields for the account ID, allocation comment, and the ID of the unallocated item.</td>
<td>accountId, allocationComment, unallocatedId</td>
</tr>
<tr>
<td>AllocationDateLimitInput</td>
<td>Input type for setting date limits on allocation processes. It allows specifying limits for credit and debit allocations.</td>
<td>credit, debit</td>
</tr>
<tr>
<td>AmountFilter</td>
<td>A filter for querying amounts. It provides fields to filter based on credit/debit status, currencies, and value comparisons.</td>
<td>creditDebit, currencies, equalTo, greaterThan, lessThan</td>
</tr>
<tr>
<td>AmountMatchedInput</td>
<td>Input type for specifying matched amount details. It includes fields for currency and value.</td>
<td>currency, value</td>
</tr>
<tr>
<td>ApprovalFilter</td>
<td>A comprehensive filter for querying approvals. It provides numerous fields to filter based on various approval-related criteria.</td>
<td>action, actions, approvalLastStage, approvalRequiresToken, commandId, commandStates, hasParticipatedIn, operation, operations, rejectionLastStage, rejectionRequiresToken, startedFrom, startedUntil, state, states</td>
</tr>
<tr>
<td>ApproveRequestInput</td>
<td>Input type for approving a request. It includes fields for the request ID, reason for approval, and token code if required.</td>
<td>id, reason, tokenCode</td>
</tr>
<tr>
<td>AssociateCustomerPartyInput</td>
<td>Options for recording company details of a customer. It includes fields for the customer ID and party ID to establish the association.</td>
<td>customerId, partyId</td>
</tr>
<tr>
<td>AutoSweepDetailsInput</td>
<td>Input type for specifying auto-sweep details. It includes fields for the linked account ID, time, and timezone for the sweep operation.</td>
<td>customerLinkedAccountId, time, timezone</td>
</tr>
<tr>
<td>BankManualInterestAdjustmentInput</td>
<td>Input type for manual interest adjustments by the bank. It includes fields for account details, amounts, reason, and associated transaction ID.</td>
<td>accountId, claId, clientAmount, customerMargin, reason, webVoucherTxId</td>
</tr>
<tr>
<td>CloseAccountInput</td>
<td>Options for closing a client account. This input type allows specifying the account to be closed and the destination for any remaining funds. It's used in account closure operations to ensure proper handling of the account and its balance.</td>
<td>accountId, fundsDestination</td>
</tr>
<tr>
<td>CommandFilter</td>
<td>A comprehensive filter for querying commands in the system. It provides various fields to filter commands based on action, external ID, time range, operation type, states, and user information. This filter is useful for auditing, tracking, and managing system operations.</td>
<td>actionContains, actionExact, externalId, from, operation, states, until, user, userInfo</td>
</tr>
<tr>
<td>CreateCustomerLinkedAccountInput</td>
<td>Options for creating a customer linked account. This input type allows specifying details such as account holder, name, number, and bank code to establish a link between a customer and an external account.</td>
<td>accountHolder, accountName, accountNumber, bankCode, customerId, description</td>
</tr>
<tr>
<td>CreatePartyAssociationInput</td>
<td>Input type for creating a party association. It includes a comprehensive set of fields to define the relationship between parties, including business details, contact information, and roles.</td>
<td>alternateAddress, associationType, businessNumber, clientClassification, countryOfEstablishment, customerId, email, fullName, incorporationCountry, incorporationDate, reference, registeredBodyNumber, registeredOfficeAddress, roles, taxResidencies, workPhone</td>
</tr>
<tr>
<td>CreatePartyIndividualInput</td>
<td>Options for creation of an individual party. This input type includes fields for personal details, addresses, and tax-related information specific to individual customers.</td>
<td>alternateAddress, customerId, dateOfBirth, familyName, gender, givenName, otherGivenNames, reference, residentialAddress, roles, selfCertified, taxResidencies, title</td>
</tr>
<tr>
<td>CreatePartyTrustInput</td>
<td>Options for creation of a trust party. This input type includes fields specific to trusts, such as trust type, controlling persons, and tax reporting details.</td>
<td>alternateAddress, businessNumber, clientClassification, controllingPersons, countryOfEffectiveManagement, countryOfEstablishment, customerId, email, fullName, giin, noTaxResidency, reference, registeredOfficeAddress, registeredSchemeNumber, roles, selfCertified, taxReportingType, taxResidencies, trustType, workPhone</td>  
 </tr>  
 <tr>
<td>CustomerFilter</td>
<td>A filter for querying customers. A simple use of this filter might look like:

`filter: {fullNameExact:"Santa Claus"}`

A filter with a top level 'or' might look like:

`filter: {or: [{fullNameExact: "Santa Claus"}, {displayNameExact: "Father Christmas"}]}`</td>
<td>displayNameContains, displayNameExact, fullNameContains, fullNameExact, or</td>
</tr>
<tr>
<td>CustomerLinkedAccountFilter</td>
<td>A filter for querying customer linked accounts. It allows filtering based on the account name.</td>
<td>accountNameContains, accountNameExact</td>
</tr>
<tr>
<td>CustomerManualInterestAdjustmentInput</td>
<td>Input type for manual interest adjustments by the customer. It includes fields for account details, amount, and reason for the adjustment.</td>
<td>accountId, claId, clientAmount, reason</td>
</tr>
<tr>
<td>CustomerSourceFilter</td>
<td>A filter for querying customer sources. It allows filtering based on account number, bank code, and name.</td>
<td>accountNumber, bankCode, nameContains, nameExact</td>
</tr>
<tr>
<td>DateTimeFilter</td>
<td>A filter for querying based on date and time ranges. It allows specifying 'from' and 'until' date-times.</td>
<td>from, until</td>
</tr>  
 <tr>
<td>DeleteCustomerSourceAccountAliasInput</td>
<td>Input type for deleting a customer source account alias. It requires the ID of the source alias to be deleted.</td>
<td>sourceAliasId</td>
</tr>
<tr>
<td>EditCustomerInput</td>
<td>Options for updating details of a customer. It includes a wide range of fields for various customer attributes and settings.</td>
<td>actionControlDateLimits, apcaDirectEntryCreditId, apcaDirectEntryDebitId, autoSweepAvailable, billingId, blockDirectDebits, coreSystemDetails, counterpartyType, designatedInterestAccount, fullName, giin, id, interestCapitalisationOnDemand, knowYourCustomerId, reporter, reportingFinancialInstitution, usFinancialInstitution</td>
</tr>
<tr>
<td>EditExtAccountInput</td>
<td>Input type for editing an external account. It includes fields for account number, bank code, and name.</td>
<td>accountNumber, bankCode, name</td>
</tr>
<tr>
<td>EditPartyAssociationInput</td>
<td>Input type for editing a party association. It includes fields for various details of the association.</td>
<td>alternateAddress, associationType, businessNumber, clientClassification, countryOfEstablishment, email, fullName, id, incorporationCountry, incorporationDate, reference, registeredBodyNumber, registeredOfficeAddress, roles, taxResidencies, workPhone</td>
</tr>
<tr>
<td>EditPartyCompanyInput</td>
<td>Options for updating details of a party company. It includes a comprehensive set of fields for company information.</td>
<td>alternateAddress, businessNumber, clientClassification, companyNumber, companyType, controllingPersons, countryOfEffectiveManagement, countryOfEstablishment, email, fullName, giin, id, incorporationCountry, incorporationDate, noTaxResidency, reference, registeredBodyNumber, registeredOfficeAddress, roles, selfCertified, stockExchange, taxReportingType, taxResidencies, tradingName, workPhone</td>
</tr>
<tr>
<td>EditPartyIndividualInput</td>
<td>Options for updating details of an individual party. It includes fields for personal information and addresses.</td>
<td>alternateAddress, dateOfBirth, familyName, gender, givenName, id, otherGivenNames, reference, residentialAddress, roles, selfCertified, taxResidencies, title</td>
</tr>  
 <tr>
<td>EditPartyTrustInput</td>
<td>Options for updating details of a trust party. It includes fields specific to trusts, such as controlling persons and tax reporting details.</td>
<td>alternateAddress, businessNumber, clientClassification, controllingPersons, countryOfEffectiveManagement, countryOfEstablishment, email, fullName, giin, id, noTaxResidency, reference, registeredOfficeAddress, registeredSchemeNumber, roles, selfCertified, taxReportingType, taxResidencies, trustType, workPhone</td>
</tr>
<tr>
<td>EncryptedInput</td>
<td>Payload for an encrypted request. It includes fields for the customer ID and the encrypted payload.</td>
<td>customerId, encryptedPayload</td>
</tr>
<tr>
<td>ExecuteAggregatePaymentInput</td>
<td>Input type for executing an aggregate payment. It includes fields for payment details such as count, reference, and total amount.</td>
<td>count, customerTransactionReference, externalAccount, instructions, reference, totalAmount</td>
</tr>
<tr>
<td>ExternalAccountInput</td>
<td>Input type for specifying an external account. It includes fields for account details and payment type.</td>
<td>accountNumber, bankCode, name, paymentType</td>
</tr>
<tr>
<td>IndividualTaxResidencyInput</td>
<td>Input type for declaring an individual's tax residency. It includes fields for specifying the country code, Tax Identification Number (TIN), and explanations if the TIN is missing. This is crucial for compliance with international tax regulations and reporting requirements.</td>
<td>countryCode, tin, tinMissingExplanation, tinMissingReason</td>
</tr>
<tr>
<td>InstructionInput</td>
<td>Input type for creating a financial instruction. It includes fields for specifying the account ID, amount, narrative (description), and a tracing ID for tracking purposes. This is typically used when initiating transactions or setting up payment instructions within the system.</td>
<td>accountId, amount, narrative, tracingId</td>
</tr>
<tr>
<td>MakeInternalTransferInput</td>
<td>Input type for transferring funds between two client accounts within the same pool. This is used for internal transfers within the ACMC system. It includes fields for specifying the crediting and debiting accounts, references for both payer and payee, the pool, transfer amount, and value date. This allows for detailed tracking and recording of internal fund movements.</td>
<td>creditingAccount, customerTransactionReference, debitingAccount, payeeReference, payerReference, pool, transferAmount, valueDate</td>
</tr>
<tr>
<td>WithholdingTaxAUInput</td>
<td>Input type for specifying Australian withholding tax details. It includes fields for APCA ID, effective timestamp, financial year start, nominated account, non-resident rate, and resident tax information. This is used to configure withholding tax settings for Australian accounts.</td>
<td>apcaId, effectiveTimestamp, financialYearStart, nominatedAccount, nonResidentRate, resident</td>
</tr>
<tr>
<td>WithholdingTaxNominatedAccountInput</td>
<td>Input type for specifying a nominated account for withholding tax purposes. It includes fields for account number, bank code, and name. This is used to designate an account for tax payments or refunds.</td>
<td>accountNumber, bankCode, name</td>
</tr>
</tbody>

</table>

---

This overview provides a summary of key IN PUT types available in the ACMC GraphQL API, including their descriptions and basic use cases. For more comprehensive information, detailed usage examples, and the complete set of available INPUT types, please refer to the [full ACMC GraphQL schema documentation](/product/ACMC%20API/code?path=GraphQL%20schema) and [dedicated sample pages](/product/ACMC%20API/code?path=GraphQL%20API%20examples).

INPUT

---
layout: detail
title: ACMC graphQL INTERFACE type
menu_key: types
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-types/interface/
---
---
INTERFACE types in the ACMC schema provide a way to define a fixed set of values for specific fields, ensuring data consistency and improving query efficiency. These types, such as `Accrual`, `Allocatable`, and `BusinessProcess`, represent predefined sets of options that can be used across various parts of the schema. 

[Examples of how INTERFACE types can be used in the ACMC schema](#interfacetypes) 

<h4 name="interfacetypes" id="interfacetypes"></h4>

Examples of how INTERFACE types can be used in the ACMC schema:

1. `Accrual`:
   - Use case: Represents an accrual event in the system.
   - Include fields such as amounts, currency, customer and etc

2. `Allocatable`:
   - Use case: Represents an allocatable item in the system.
   - Include fields such as allocationState, instructions, valueDate and etc

3. `BusinessProcess`:
   - Use case: Represents a business process in the system.
   - Include fields such as createdTimestamp, valueDate and etc

[INTERFACE types examples](#typeexamples) 

<h4 name="typeexamples" id="typeexamples"></h4>

**INTERFACE TYPES EXAMPLES**

 <table>
        <thead>
            <tr>
                <th>Name</th>
                <th>Description</th>
                <th>Fields</th>
            </tr>
        </thead>
        <tbody>
        <tr>
            <td>Accrual</td>
            <td>Represents an accrual event in the system. This interface is used to track and manage accruals, which are accumulations of financial items over time.</td>
            <td>amounts, currency, customer, destination, endDate, id, pool, product, realisation, source, type, valueDate</td>
        </tr>
        <tr>
            <td>Allocatable</td>
            <td>Represents an allocatable item in the system. This interface is used for managing items that can be allocated to accounts, including their allocation state, history, and associated processes.</td>
            <td>accountAllocatedTo, allocation, allocationState, amount, businessProcess, createdTimestamp, deleteApprovalTimestamp, deleteApprovalUserId, deleteApprovalUserName, deleteMessage, deleteRequestTimestamp, deleteRequestUserId, deleteRequestUserName, directDebit, history, hold, holdHistory, id, instructions, pool, remainingUnallocated, restoreApprovalTimestamp, restoreApprovalUserId, restoreApprovalUserName, restoreMessage, restoreRequestTimestamp, restoreRequestUserId, restoreRequestUserName, reversal, split, unallocatable, unallocatedReason, unallocatedReasonCode, valueDate</td>
        </tr>
        <tr>
            <td>BusinessProcess</td>
            <td>Represents a business process in the system. This interface is used to track and manage various business processes, including their associated transactions and timelines.</td>
            <td>createdTimestamp, id, transactions, valueDate</td>
        </tr>
        <tr>
            <td>Command</td>
            <td>Detailed information on a previously executed command. This interface provides a comprehensive view of command execution, including approval status, input data, and execution state.</td>
            <td>approval, createdTimestamp, id, inputJson, invalid, operation, state, step, userInfo</td>
        </tr>
        <tr>
            <td>FeatureConfig</td>
            <td>Represents a feature configuration in the system. This interface is used to manage and track various system features and their configurations.</td>
            <td>id, name</td>
        </tr>
        <tr>
            <td>Instruction</td>
            <td>Represents an instruction within a business process. This interface is used to manage individual instructions that make up larger business processes.</td>
            <td>businessProcess, id</td>
        </tr>
        <tr>
            <td>NamedRate</td>
            <td>Represents a named rate in the system. This interface is used to manage and track various rates, including their history and current or next values.</td>
            <td>currentOrNext, history, id</td>
        </tr>
        <tr>
            <td>NamedRateEntry</td>
            <td>Represents an entry for a named rate. This interface provides detailed information about specific rate entries, including currency and start date.</td>
            <td>currency, id, name, namedRate, startDate</td>
        </tr>
        <tr>
            <td>Node</td>
            <td>Represents a basic node in the system. This interface is a fundamental building block for other more complex types that require a unique identifier.</td>
            <td>id</td>
        </tr>
        <tr>
            <td>Party</td>
            <td>Represents a party in the system. This interface is used to manage various types of parties, including individuals and organizations, with their associated details and relationships.</td>
            <td>customer, dateOfResidencyChange, id, kycInformation, linkedAccounts, previousDomesticTin, previousSelfCertified, reference, roles, selfCertified, shortId</td>
        </tr>
        <tr>
            <td>PartyCompanyInterface</td>
            <td>Represents a company party in the system. This interface extends the basic Party interface with additional fields specific to company entities.</td>
            <td>alternateAddress, businessNumber, clientClassification, controllingPersons, countryOfEffectiveManagement, customer, customerNode, email, fullName, giin, kycInformation, noTaxResidency, reference, registeredOfficeAddress, roles, selfCertified, taxReportingType, taxResidencies, tradingName, workPhone</td>
        </tr>
        <tr>
            <td>PartyTrustInterface</td>
            <td>Represents a trust party in the system. This interface extends the basic Party interface with additional fields specific to trust entities.</td>
            <td>alternateAddress, businessNumber, clientClassification, controllingPersons, countryOfEffectiveManagement, countryOfEstablishment, customer, customerNode, email, fullName, giin, kycInformation, noTaxResidency, reference, registeredOfficeAddress, roles, selfCertified, taxReportingType, taxResidencies, workPhone</td>
        </tr>
        <tr>
            <td>Pool</td>
            <td>Represents a pool of accounts or resources in the system. This interface is used to manage groups of related accounts or resources, including their allocation and reversal status.</td>
            <td>accounts, deleted, id, matchedReversals, movedToCLA, name, sourceType, unallocated</td>
        </tr>
        <tr>
            <td>Product</td>
            <td>Represents a product in the system. This interface is used to manage various financial products, including their features, associated accounts, and status.</td>
            <td>accounts, activeFeatures, availableFeatures, billingId, code, codeSuffix, costCentre, currencies, description, governmentGuaranteeApplies, grantedToCustomers, id, name, parent, retailLookThrough, rmSet, state</td>
        </tr>
        <tr>
            <td>Source</td>
            <td>Represents a source of funds or transactions in the system. This interface is used to manage various sources, including their balances and associated accounts.</td>
            <td>balances, bankCode, currency, id, internalAccounts, name, sourceType</td>
        </tr>
        <tr>
            <td>Transaction</td>
            <td>Represents a financial transaction in the system. This interface is used to manage individual transactions, including their associated entries, currency, and status.</td>
            <td>businessProcess, currency, entries, id, initiatedTimestamp, splitElement, state, transactionType, valueDate</td>
        </tr>
        <tr>
            <td>TransactionEntry</td>
            <td>Represents an entry within a transaction. This interface provides detailed information about individual entries that make up a transaction, including account, value, and status.</td>
            <td>account, balance, businessProcess, creditDebit, currency, id, initiatedTimestamp, instruction, state, transaction, transactionType, unallocatable, value</td>
        </tr>
        <tr>
            <td>UserWithScopes</td>
            <td>Description of a user, including their permissions (scopes). Both `name` and `displayName` are optional as not all users have them. In particular, API users will likely not have either.</td>
            <td>displayName, scopes, sub, username</td>
        </tr>
        <tr>
            <td>WithholdingTaxAUEntry</td>
            <td>Represents an entry for Australian withholding tax. This interface is used to manage withholding tax details specific to the Australian tax system.</td>
            <td>apcaId, effectiveTimestamp, financialYearStart, nominatedAccount, nonResidentRate, resident</td>
        </tr>
        </tbody>
    </table>

---

This overview provides a summary of key INTERFACE types available in the ACMC GraphQL API, including their descriptions and basic use cases. For more comprehensive information, detailed usage examples, and the complete set of available INTERFACE types, please refer to the [full ACMC GraphQL schema documentation](/product/ACMC%20API/code?path=GraphQL%20schema) and [dedicated sample pages](/product/ACMC%20API/code?path=GraphQL%20API%20examples).

INTERFACE

---
layout: detail
title: ACMC graphQL API examples
menu_key: sample
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-sample/
---
---
[API examples overview](#apiexamplesoverview) 

<h4 name="apiexamplesoverview" id="apiexamplesoverview"></h4>

#### API Examples Overview

This page showcases practical examples of using the ACMC (ANZ Cash Management Central) GraphQL API. These samples demonstrate how to interact with the platform's key features, including account management, payment processing, and transaction reporting. By exploring these examples, you'll gain insights into how to leverage the API for real-time client money management, potentially reducing manual intervention and operational costs in your applications.

[List of examples](#listofexamples) 

<h4 name="listofexamples" id="listofexamples"></h4>

#### List of Examples

<ol>
  <li><a href="code?path=GraphQL%20API%20examples/Party%20management">Party management</a></li>
  <li><a href="code?path=GraphQL%20API%20examples/Account%20management">Account management</a></li>
  <li><a href="code?path=GraphQL%20API%20examples/Time%20allocation">Transaction allocation</a></li>
  <li><a href="code?path=GraphQL%20API%20examples/Payments">Payments</a></li>
    <ul>
      <li><a href="code?path=GraphQL%20API%20examples/Payments/Client%20accounts%20outwards%20payments">Client accounts outwards payments</a></li>
      <li><a href="code?path=GraphQL%20API%20examples/Payments/Payments%20between%20CLI%20and%20CLA">Payments between CLI and CLA</a></li>
      <li><a href="code?path=GraphQL%20API%20examples/Payments/Aggregated%20payment%20(CLI%20to%20CLA)">Aggregated payment (CLI to CLA)</a></li>
      <li><a href="code?path=GraphQL%20API%20examples/Payments/Disaggregated%20payment%20(CLA%20to%20CLI)">Disaggregated payment (CLA to CLI)</a></li>
    </ul>
  </li>
</ol>



<style>
  ol {
    list-style-type: decimal; /* This ensures numbers appear in ordered list */
    padding-left: 20px;
  }

  ul {
    list-style-type: disc; /* This ensures bullet points appear in unordered list */
    padding-left: 20px;
  }

  /* Optional: if you want to

---
layout: detail
title: Party management
menu_key: sample
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-sample/party/
---
---

[Party management examples overview](#managementexamples) 

<h4 name="managementexamples" id="managementexamples"></h4>

#### Party Management Examples Overview:
This page provides comprehensive examples of GraphQL queries and mutations for managing parties (beneficiaries) in the ANZ Cash Management Central (ACMC) system. These operations cover various aspects of party management, including creating individual and non-individual clients, querying client creation status, and retrieving detailed client information. Each example is accompanied by explanations of input fields, sample requests, and response structures to help developers effectively integrate with the ACMC API for party-related operations.


[Create individual party](#createindividualparty) 

<h4 name="createindividualparty" id="createindividualparty"></h4>

#### Create Individual Party

**Mutation: CreateIndividualParty**

This mutation creates a new individual client in the ACMC system.

```graphql
mutation ($party: CreatePartyIndividualInput!) {
  createPartyIndividual(i: $party) {
    commandId
  }
}
```

**Variables:**

```json
{
    "party": {
        "customerId": "Q3VzdG9tZXI6MDVkM2VmZWQ2MTYyZDEzZTlkOGYyMTI1YTBhZTQwOGVmMmQ4MDQyMGU5MjA1N2YwNmViNGIxYjc2YTA2ZDMwZA==",
        "title": "Mr",
        "givenName": "Mark",
        "familyName": "Te",
        "gender": "M",
        "dateOfBirth": "1983-12-31",
        "residentialAddress": {
            "line1": "434 757 Bourke St",
            "line2": "Docklands",
            "city": "Melbourne",
            "countryCode": "AU",
            "postCode": "3000",
            "state": "VIC"
        },
        "roles": [
            "BENEFICIARY"
        ],
        "taxResidencies": [
            {
                "countryCode": "AU",
                "tin": null,
                "tinMissingReason": "PENSIONER"
            }
        ]
    }
}
```

**Input Fields**

| Field | Description |
|-------|-------------|
| customerId | Unique identifier for the customer |
| title | Title of the individual (e.g., Mr, Mrs, Ms) |
| givenName | First name of the individual |
| familyName | Last name of the individual |
| gender | Gender of the individual (e.g., M, F) |
| dateOfBirth | Date of birth of the individual |
| residentialAddress | Residential address of the individual |
| roles | Roles assigned to the individual |
| taxResidencies | Tax residency information |

**AddressInput Fields**

| Field | Description |
| ----- | ----------- |
| line1 | First line of the address |
| line2 | Second line of the address (optional) |
| city | City |
| state | State or province |
| countryCode | Country code (e.g., AU for Australia) |
| postCode | Postal or ZIP code |

**TaxResidencyInput Fields**

| Field | Description |
| ----- | ----------- |
| countryCode | Country code for tax residency |
| tin | Tax Identification Number (optional) |
| tinMissingReason | Reason for missing TIN (if applicable) |

[Create non-individual party](#nonindividualparty) 

<h4 name="nonindividualparty" id="nonindividualparty"></h4>

#### Create Non-Individual Party

**Mutation: CreatePartyTrust**

This mutation creates a new non-individual client (e.g., company, trust) in the ACMC system.

```graphql
mutation ($party: CreatePartyTrustInput!) {
  createPartyTrust(i: $party) {
    commandId
  }
}
```
**Variables:**

```json
{
    "party": {
        "customerId": "Q3VzdG9tZXI6MDVkM2VmZWQ2MTYyZDEzZTlkOGYyMTI1YTBhZTQwOGVmMmQ4MDQyMGU5MjA1N2YwNmViNGIxYjc2YTA2ZDMwZA==",
        "reference": "Mark_Trust",
        "fullName": "Mark Family Trust",
        "trustType": "UNREGULATED_DOMESTIC_FAMILY",
        "clientClassification": "TRUST",
        "countryOfEstablishment": "AU",
        "businessNumber": "75140734783",
        "registeredOfficeAddress": {
            "line1": "200 Collins Street",
            "city": "Melbourne",
            "state": "VIC",
            "countryCode": "AU",
            "postCode": "3000"
        },
        "email": "mark@test.com.au",
        "workPhone": "92319231",
        "taxResidencies": [
            {
                "countryCode": "AU",
                "tin": "467299997"
            }
        ],
        "roles": [
            "BENEFICIARY"
        ]
    }
}
```

**Input Fields**

| Field | Description |
|-------|-------------|
| customerId | Unique identifier for the customer |
| reference | Reference for the trust |
| fullName | Full name of the trust |
| trustType | Type of the trust |
| clientClassification | Classification of the client |
| countryOfEstablishment | Country where the trust was established |
| businessNumber | Business number of the trust |
| registeredOfficeAddress | Registered office address of the trust |
| email | Email address for the trust |
| workPhone | Work phone number for the trust |
| taxResidencies | Tax residency information |
| roles | Roles assigned to the trust |

[Query party creation status](#partycreationstatus) 

<h4 name="partycreationstatus" id="partycreationstatus"></h4>

#### Query Party Creation Status

**Query: PartyIndividualCreateCommand**

This query checks the status of a party creation request.

```graphql
query QueryCommand {
    node(id: "Q29tbWFuZDoyMDY0NWU3Yi02OGU2LTRlMTItYjA0YS1hZDdjZmFlZDYzYzY=") {
        __typename
        ... on GenericCommand {
            action
            state
            step
            invalid {
                field
                reason
            }
        }
        ... on PartyIndividualCreateCommand {
            action
            party {
                id
                roles
                reference
            }
            invalid {
                field
                reason
            }
            state
            step
        }
    }
}
```

**Response:**

```json
{
    "data": {
        "node": {
            "__typename": "PartyIndividualCreateCommand",
            "action": "PARTY-INDIVIDUAL-CREATE",
            "party": {
                "id": "UGFydHlJbmRpdmlkdWFsOmJkMWNjZjVmNTYzY2NmNGQwZGQzNmJmYjIzYTJkMjNhMDBiYWEwOTcwNzE2NzdiM2VkOWY5ZTVmNDI3ZGNlNDU=",
                "roles": [
                    "BENEFICIARY"
                ],
                "reference": "new account"
            },
            "invalid": [],
            "state": "SUCCESSFUL",
            "step": "END"
        }
    }
}
```

**Response Fields**

| Field | Description |
|-------|-------------|
| node.__typename | The type of the command |
| node.action | The action performed by the command |
| node.party.id | The ID of the created party |
| node.party.roles | The roles assigned to the party |
| node.party.reference | The reference of the party |
| node.invalid | List of validation errors including error code, error reason, duplicated partyId|
| node.state | The current state of the command |
| node.step | The current step of the command |

[Query individual party details](#queryindividual) 

<h4 name="queryindividual" id="queryindividual"></h4>

#### Query Individual Party Details

**Query: PartyIndividual**

This query retrieves detailed information about a client.

```graphql
query QueryCommand{
    node(
        id: "UGFydHlJbmRpdmlkdWFsOmJkMWNjZjVmNTYzY2NmNGQwZGQzNmJmYjIzYTJkMjNhMDBiYWEwOTcwNzE2NzdiM2VkOWY5ZTVmNDI3ZGNlNDU="
    ) {
        ... on PartyIndividual {
            customer {
                fullName
            }
            id
            shortId
            gender
            title
            givenName
            familyName
            otherGivenNames
            dateOfBirth
            dateOfDeath
            deceased
            residentialAddress {
                line1
                line2
                city
                state
                countryCode
                postCode
            }
            alternateAddress {
                line1
                line2
                city
                state
                countryCode
                postCode
            }
            reference
            roles
            selfCertified {
                certificationDate
            }
            taxReportingType
            taxResidencies {
                countryCode
                tin
                tinMissingExplanation
                tinMissingReason
            }
            title
            __typename
            customer {
                fullName
                id
            }
        }
    }
}
```

**Response:**

```json
{
    "data": {
        "node": {
            "customer": {
                "fullName": "Testing Trading Pty Ltd",
                "id": "Q3VzdG9tZXI6MDVkM2VmZWQ2MTYyZDEzZTlkOGYyMTI1YTBhZTQwOGVmMmQ4MDQyMGU5MjA1N2YwNmViNGIxYjc2YTA2ZDMwZA=="
            },
            "id": "UGFydHlJbmRpdmlkdWFsOmJkMWNjZjVmNTYzY2NmNGQwZGQzNmJmYjIzYTJkMjNhMDBiYWEwOTcwNzE2NzdiM2VkOWY5ZTVmNDI3ZGNlNDU=",
            "shortId": "9333346219",
            "gender": "M",
            "title": "Mr",
            "givenName": "Mark",
            "familyName": "Te",
            "otherGivenNames": [],
            "dateOfBirth": "1983-12-31",
            "dateOfDeath": null,
            "deceased": false,
            "residentialAddress": {
                "line1": "434 757 Bourke St",
                "line2": "Docklands",
                "city": "Melbourne",
                "state": "VIC",
                "countryCode": "AU",
                "postCode": "3000"
            },
            "alternateAddress": null,
            "reference": "new account",
            "roles": [
                "BENEFICIARY"
            ],
            "selfCertified": null,
            "taxReportingType": null,
            "taxResidencies": [
                {
                    "countryCode": "AU",
                    "tin": null,
                    "tinMissingExplanation": null,
                    "tinMissingReason": "PENSIONER"
                }
            ],
            "__typename": "PartyIndividual"
        }
    }
}
```

**Response Fields**

| Field | Description |
|-------|-------------|
| node.customer.fullName | The full name of the associated customer |
| node.customer.id | The ID of the associated customer |
| node.id | The ID of the party |
| node.shortId | A short identifier for the party |
| node.gender | The gender of the individual |
| node.title | The title of the individual |
| node.givenName | The given name of the individual |
| node.familyName | The family name of the individual |
| node.otherGivenNames | Any other given names of the individual |
| node.dateOfBirth | The date of birth of the individual |
| node.dateOfDeath | The date of death (if applicable) |
| node.deceased | Whether the individual is deceased |
| node.residentialAddress | The residential address of the individual |
| node.alternateAddress | An alternate address (if any) |
| node.reference | A reference for the party |
| node.roles | The roles assigned to the party |
| node.selfCertified | Self-certification information |
| node.taxReportingType | The type of tax reporting |
| node.taxResidencies | Tax residency information |
| node.__typename | The type of the node (e.g., "PartyIndividual") |


[Update individual party details](#partydetails) 

<h4 name="partydetails" id="partydetails"></h4>

#### Update Individual Party Details

**Mutation: EditPartyIndividual**

This mutation updates the details of an individual party.

```graphql
mutation ($editindividual: EditPartyIndividualInput!) {
  editPartyIndividual (i: $editindividual) {
    commandId
  }
}
```

**Variables:**

```json
{
    "editindividual": {
        "id": "UGFydHlJbmRpdmlkdWFsOmJkMWNjZjVmNTYzY2NmNGQwZGQzNmJmYjIzYTJkMjNhMDBiYWEwOTcwNzE2NzdiM2VkOWY5ZTVmNDI3ZGNlNDU=",
        "givenName": "Andy",
        "familyName": "Tran"
    }
}
```

**Input Fields**

| Field | Description |
|-------|-------------|
| id | The ID of the party to update |
| givenName | The new given name of the individual |
| familyName | The new family name of the individual |


---

This documentation provides a comprehensive overview of the party management operations available in the ACMC API. Each section includes a GraphQL query or mutation, input field tables, and example responses to demonstrate usage.



<style>
  ol {
    list-style-type: decimal; /* This ensures numbers appear in ordered list */
    padding-left: 20px;
  }

  ul {
    list-style-type: disc; /* This ensures bullet points appear in unordered list */
    padding-left: 20px;
  }
  </style>

Party management

---
layout: detail
title: Account management
menu_key: sample
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-sample/account/
---
---

[Account management examples overview](#management) 

<h4 name="management" id="management"></h4>

#### Account   Management Examples Overview:

This page provides comprehensive examples of GraphQL queries and mutations for managing client accounts in the ANZ Cash Management Central (ACMC) system. These operations cover various aspects of account management, including opening accounts, querying account status, retrieving account details, and closing accounts. Each example is accompanied by explanations of input fields, sample requests, and response structures to help developers effectively integrate with the ACMC API for account-related operations.


1. [Open a Client Account](#open-a-client-account)
2. [Query Account Open Status](#query-account-open-status)
3. [Query Account Details](#query-account-details)
4. [Query Account Transaction History](#query-account-transaction-history)
5. [Close Client Account](#close-client-account)

[Open a client account](#clientaccount) 

<h4 name="clientaccount" id="clientaccount"></h4>

#### Open a Client Account

**Mutation: OpenAccount**

This mutation creates a new client account in the ACMC system.

```graphql
mutation ($acct: OpenAccountInput!) {
  openAccount (i: $acct)
  {
    commandId
  }
}
```
**Variables:**

```json
{
    "acct": {
        "name": "Mark Account1",
        "customerId": "Q3VzdG9tZXI6MDVkM2VmZWQ2MTYyZDEzZTlkOGYyMTI1YTBhZTQwOGVmMmQ4MDQyMGU5MjA1N2YwNmViNGIxYjc2YTA2ZDMwZA==",
        "reference": "Mark acc 455",
        "product": "UHJvZHVjdDpkM2UzNmZhN2Q0ODIzZDllZjA2NWUyMjc1NWY1NWMzNDI3MjZjZmI0YzI5Zjc1NzRkNWE0YTA2MmQ2YmE4ZWUx",
        "parties": [
            {
                "partyId": "UGFydHlJbmRpdmlkdWFsOmJkMWNjZjVmNTYzY2NmNGQwZGQzNmJmYjIzYTJkMjNhMDBiYWEwOTcwNzE2NzdiM2VkOWY5ZTVmNDI3ZGNlNDU=",
                "roles": [
                    "BENEFICIARY"
                ]
            }
        ]
    }
}
```

**Input Fields**

| Field | Type | Description |
|-------|------|-------------|
| name | String! | Name of the account |
| customerId | ID! | Unique identifier for the customer |
| reference | String | Reference for the account |
| product | ID! | Identifier for the product associated with the account |
| parties | [AccountPartyInput!]! | List of parties associated with the account |

[Query account open status](#openstatus) 

<h4 name="openstatus" id="openstatus"></h4>

#### Query Account Open Status

**Query: AccountOpenStatus**

This query checks the status of an account opening request.

```graphql
query QueryCommand {
    node(id: "Q29tbWFuZDo3YWIzOGEyZi1kNTUxLTQwMTEtOTJlZC1lYzQwZWY1MTlmOTg=") {
        __typename
        ... on GenericCommand {
            action
            state
            step
            invalid {
                field
                reason
            }
        }
        ... on OpenAccountCommand {
            action
            account {
                accountNumber
                bankCode
                id
            }
            state
            invalid {
                field
                reason
            }
            action
            state
            id
            step
        }
    }
}
```

**Input Fields**

| Field | Type | Description |
|-------|------|-------------|
| id | ID! | The ID of the command to query |

[Query account details](#accountdetails) 

<h4 name="accountdetails" id="accountdetails"></h4>


#### Query Account Details

**Query: Account**

This query retrieves detailed information about a client account.

```graphql
query QueryCommand {
    node(
        id: "QWNjb3VudDoyN2ViNWEzZGZhY2Y1Y2FkN2I4OWVlNzk0MWYxNGRkYmQzMTk3MGI3ODJhNThhYTg4OWE3ZWRlODY2OWQ3ODBk"
    ) {
        ... on Account {
            customer {
                fullName
            }
            accountNumber
            name
            openState
            id
            product {
                name
                currencies
            }
            balances {
                current {
                    creditDebit
                    currency
                    value
                }
                available {
                    creditDebit
                    currency
                    value
                }
            }
            parties {
                party {
                    roles
                    ... on PartyIndividual {
                        givenName
                        familyName
                    }
                    id
                }
            }
        }
    }
}
```

**Response:**

```json
{
  "data": {
    "node": {
      "customer": {
        "fullName": "Test Trading Pty Ltd"
      },
      "accountNumber": "173360933",
      "name": "Mark Account1",
      "openState": "OPEN",
      "id": "QWNjb3VudDoyN2ViNWEzZGZhY2Y1Y2FkN2I4OWVlNzk0MWYxNGRkYmQzMTk3MGI3ODJhNThhYTg4OWE3ZWRlODY2OWQ3ODBk",
      "product": {
        "name": "Testing Trading – Non Retail Direct - Client",
        "currencies": [
          "AUD"
        ]
      },
      "balances": [
        {
          "current": {
            "creditDebit": "CREDIT",
            "currency": "AUD",
            "value": "0.00"
          },
          "available": {
            "creditDebit": "CREDIT",
            "currency": "AUD",
            "value": "0.00"
          }
        }
      ],
      "parties": [
        {
          "party": {
            "roles": [
              "TRUSTEE"
            ],
            "id": "UGFydHlDb21wYW55OjA3Y2RmNTgzNDRkYjQxZWFhOTZlZTA5YmI3MWQ1MmYyNWUzNjQ0MzQ1OWQ5NzA3MDNmZmY3ODJmMjAwMjE0ODk="
          }
        },
        {
          "party": {
            "roles": [
              "BENEFICIARY"
            ],
            "givenName": "Mark",
            "familyName": "Te",
            "id": "UGFydHlJbmRpdmlkdWFsOmJkMWNjZjVmNTYzY2NmNGQwZGQzNmJmYjIzYTJkMjNhMDBiYWEwOTcwNzE2NzdiM2VkOWY5ZTVmNDI3ZGNlNDU="
          }
        }
      ]
    }
  }
}
```
**Response Fields:**

| Field | Description |
|-------|-------------|
| customer.fullName | The full name of the customer associated with the account |
| accountNumber | The unique account number |
| name | The name given to the account |
| openState | The current state of the account (e.g., "OPEN") |
| id | The unique identifier for the account |
| product.name | The name of the product associated with the account |
| product.currencies | The currencies supported by the product (e.g., ["AUD"]) |
| balances | List of balance information for the account |
| balances[].current | The current balance of the account |
| balances[].available | The available balance of the account |
| balances[].current.creditDebit | Indicates whether the current balance is a credit or debit |
| balances[].current.currency | The currency of the current balance |
| balances[].current.value | The numerical value of the current balance |
| balances[].available.creditDebit | Indicates whether the available balance is a credit or debit |
| balances[].available.currency | The currency of the available balance |
| balances[].available.value | The numerical value of the available balance |
| parties | List of parties associated with the account |
| parties[].party.roles | The roles of the associated party (e.g., "TRUSTEE", "BENEFICIARY") |
| parties[].party.id | The unique identifier for the associated party |
| parties[].party.givenName | The given name of the individual party (if applicable) |
| parties[].party.familyName | The family name of the individual party (if applicable) |

[Query account transaction history](#transactionhistory) 

<h4 name="transactionhistory" id="transactionhistory"></h4>

#### Query Account Transaction History

**Query: getTransHistoryByDate**

This query fetches the transaction history for a client account.

```graphql
query getTransHistoryByDate($accno: AccountNumber, $from: DateTime, $when: DateTime) {
  bank {
    accounts(filter: { accountNumberExact: $accno }) {
      edges {
        node {
          name
          accountNumber
          balances {
            current {
              creditDebit
              currency
              value
            }
          }
          transactionEntries(
            filter: { from: $from, until: $when }
            first: 3
          ) {
            edges {
              node {
                transactionType
                initiatedTimestamp
                transaction {
                  valueDate
                }
              }
            }
          }
        }
      }
    }
  }
}
```

**Input Fields**

| Field | Description |
|-------|-------------|
| accno | The account number to query |
| from  | Start date for transaction history |
| when  | End date for transaction history |

**Response:**

```json
{
  "data": {
    "bank": {
      "accounts": {
        "edges": [
          {
            "node": {
              "name": "2909 Test Account",
              "accountNumber": "173355850",
              "balances": [
                {
                  "current": {
                    "creditDebit": "CREDIT",
                    "currency": "AUD",
                    "value": "25255.54"
                  }
                }
              ],
              "transactionEntries": {
                "edges": [
                  {
                    "node": {
                      "transactionType": "aggregate-payment",
                      "initiatedTimestamp": "2024-10-09T05:40:11.770Z",
                      "transaction": {
                        "valueDate": "2024-10-09"
                      }
                    }
                  },
                  {
                    "node": {
                      "transactionType": "aggregate-payment",
                      "initiatedTimestamp": "2024-10-09T05:34:23.928Z",
                      "transaction": {
                        "valueDate": "2024-10-09"
                      }
                    }
                  },
                  {
                    "node": {
                      "transactionType": "aggregate-payment",
                      "initiatedTimestamp": "2024-10-09T03:17:46.912Z",
                      "transaction": {
                        "valueDate": "2024-10-09"
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
}
```

**Response Fields:**

| Field | Description |
|-------|-------------|
| node.name | The name of the account |
| node.accountNumber | The unique account number associated with the account |
| node.balances.current.creditDebit | Indicates whether the current balance is a credit or debit (Enum: CREDIT or DEBIT) |
| node.balances.current.currency | The currency of the current balance (Enum: e.g., AUD, USD) |
| node.balances.current.value | The numerical value of the current balance as a string |
| node.transactionEntries.edges[].node.transactionType | The type of transaction (Enum: various transaction types) |
| node.transactionEntries.edges[].node.initiatedTimestamp | The timestamp when the transaction was initiated (DateTime) |
| node.transactionEntries.edges[].node.transaction.valueDate | The value date of the transaction (Date) |

Note: The `edges[]` and `node` notation in the transactionEntries field represents the GraphQL connection pattern used for pagination. The actual transaction data is contained within these `node` objects.


[Close client account](#closeclientaccount) 

<h4 name="closeclientaccount" id="closeclientaccount"></h4>

#### Close Client Account

**Mutation: CloseClientAccount**

This mutation closes a client account.

```graphql
mutation ($acct: CloseAccountInput!) {
  closeAccount (i: $acct)
   {
    commandId
  }
}
```

**Variables:**

```json
{
    "acct": {
        "accountId": "QWNjb3VudDozMzQ1ZTdiNzVlYjM4YjgxZTE1YmVmMTlhMTY0NzUxMTIzYTlmYzA0ZWIxOThiNWQ2NWZjNTBmYWNhZTNkOGI0",
        "fundsDestination": {
            "accountNumber": "841703632",
            "bankCode": "013056",
            "name": "Multi Test Corp Ltd"
        }
    }
}
```

**Input Fields**

| Field | Description |
|-------|-------------|
| accountId | The unique identifier of the account to be closed. It's typically a base64 encoded string that includes the account type and a unique identifier. |
| fundsDestination.accountNumber | The account number where remaining funds will be transferred upon closure of the account. |
| fundsDestination.bankCode | The bank code (often called BSB in Australia) of the destination account for remaining funds. |
| fundsDestination.name | The name associated with the destination account for remaining funds. |

Note: The `fundsDestination` object contains details about where any remaining funds in the account should be transferred upon closure. All fields shown in this example are required for the account closure process to ensure proper handling of any remaining funds in the account being closed.

---

This documentation provides a comprehensive overview of the account management operations available in the ACMC API. Each section includes a GraphQL query or mutation, input field tables, relevant enums, and example variables to demonstrate usage.

Account management

---
layout: detail
title: Transaction allocation
menu_key: sample
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-sample/allocation/
---
---

[Transaction allocation examples overview](#allocationexamples) 

<h4 name="allocationexamples" id="allocationexamples"></h4>

#### Transaction Allocation Examples Overview:

This page provides comprehensive examples of GraphQL queries and mutations for managing transaction allocations in the ANZ Cash Management Central (ACMC) system. These operations cover various aspects of allocation management, including querying unallocated transactions, initiating transaction allocations, un-allocating transactions, and retrieving allocation command details. Each example is accompanied by explanations of input fields, sample requests, and response structures to help developers effectively integrate with the ACMC API for allocation-related operations.

The ACMC system handles transaction allocations through both automatic and manual processes:

1. **Automatic Allocation**: 
   - Payments or receipts that match a Client Account number or Client Account reference are automatically allocated to the relevant CMM Client Account.

2. **Manual Allocation**:
   - Receipts not automatically allocated remain available in the Source Account for 10 Business Days.
   - During this period, these receipts can be manually allocated to a Client Account.
   - If allocation is completed within 10 Business Days of receipt, interest for the transaction will be backdated to the date of receipt.

3. **Unallocated Receipts**:
   - Receipts that remain unallocated for 10 Business Days are transferred to the Nominated Trust Account on the subsequent Business Day.
   - These receipts do not accrue interest for the period they remained unallocated within the Source Account.
   - Once transferred to the Nominated Trust Account, they will accrue interest at the rate applied to that account (if any).

The following GraphQL operations allow you to manage and query these manual allocation processes within the ACMC system.


[Query unallocated transactions (payments and receipts)](#paymentsandreceipts) 

<h4 name="paymentsandreceipts" id="paymentsandreceipts"></h4>

#### Query Unallocated Transactions (payments and receipts)

**Query: node: unallocated**

This query retrieves a list of unallocated payments and receipts.

```graphql
{
    bank {
        unallocated {
            edges {
                node {
                    ... on Payment {
                        __typename
                        id
                        entryReference
                        narrative
                        unallocatedReason
                        reversal
                        transactions {
                            edges {
                                node {
                                    currency
                                    transactionType
                                    valueDate
                                    initiatedTimestamp
                                    businessProcess {
                                        ... on Payment {
                                            amount {
                                                creditDebit
                                                value
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                    ... on Receipt {
                        __typename
                        id
                        entryReference
                        narrative
                        unallocatedReason
                        reversal
                        transactions {
                            edges {
                                node {
                                    currency
                                    transactionType
                                    valueDate
                                    initiatedTimestamp
                                    businessProcess {
                                        ... on Receipt {
                                            amount {
                                                creditDebit
                                                value
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
**Response:**

```json
{
	"data": {
		"bank": {
			"unallocated": {
				"edges": [
					{
						"node": {
							"__typename": "Payment",
							"id": "UmVjZWlwdDo5MDg0ZTQ5OTE2N2Q0ZDRhMjg2NjIzZTZmYWQyNDg2OWFiYWNjM2UzZjJkMTMwYjQyMWJkYmVmOTZjYzdkODk0",
							"entryReference": "173300000",
							"narrative": "173300000 Matching",
							"unallocatedReason": "Manually unallocated",
							"reversal": false,
							"transactions": {
								"edges": [
									{
									"node": {
										"currency": "AUD",
										"transactionType": "source-allocation",
										"valueDate": "2022-11-24",
										"initiatedTimestamp": "2022-11-24T00:46:58.404Z",
										"businessProcess": {
											"amount": {
													"creditDebit": "CREDIT",
													"value": "900.00"
												}
											}
										}
									}
								]
							}
						}
					}
				]
			}
		}
	}
}
```

**Response Fields:**

| Field | Description |
|-------|-------------|
| id | ID of the unallocated transaction |
| __typename | Type of the transaction, payment or receipt |
| entryReference | Reference of the transaction |
| narrative | Narrative of the transaction |
| unallocatedReason | Reason for unallocated transaction |
| reversal | Whether the transaction is a reversal |
| transactions | Transactions associated with the unallocated payments or receipts |

[Initiate transaction allocation](#initiatetransaction) 

<h4 name="initiatetransaction" id="initiatetransaction"></h4>

#### Initiate Transaction Allocation  

**Mutation: allocate**

This mutation allocates a transaction to a client account.

```graphql
mutation ($input: AllocateInput!) {
	allocate(i: $input) {
		commandId
	}
}
```


**Input Fields:**

| Field | Description |
|-------|-------------|
| accountId | ID of the client account to allocate to |
| allocationComment | Comment for the allocation |
| unallocatedId | ID of the unallocated transaction |

```json
{
	"input": {
		"accountId": "QWNjb3VudDoyN2ViNWEzZGZhY2Y1Y2FkN2I4OWVlNzk0MWYxNGRkYmQzMTk3MGI3ODJhNThhYTg4OWE3ZWRlODY2OWQ3ODBk",
		"allocationComment": null,
		"unallocatedId": "UmVjZWlwdDoyZWRkY2E5YTk2YTE1OWYzYjRiZDNiZjcyZjExZWIxNWUzYTcxMWI4MzljMGQ4YTA1NjE0ZTNmZDA2YWNjMTFl"
	}
}
```

[Query transaction allocation command](#querytransactionallocation) 

<h4 name="querytransactionallocation" id="querytransactionallocation"></h4>

#### Query Transaction Allocation Command

**Query: node: allocation**

This query retrieves the status of a transaction allocation command.

```graphql
query QueryCommand($commandId: ID!) {
    node(id: $commandId) {
        __typename
        ... on Command {
            action
            state
            step
            invalid {
                field
                reason
                __typename
            }
            createdTimestamp
        }
    }
}
```
**Variables:**

```json
{
	"commandId": "Q29tbWFuZDo3ZjIyMDM2Ny0wYTljLTRhZDEtOTY3Yi1hN2ZmZTNlYzZiZjA="
}
```

**Response:**

```json
{
	"data": {
		"node": {
			"__typename": "AllocatableAllocateCommand",
			"action": "ALLOCATABLE-ALLOCATE",
			"state": "SUCCESSFUL",
			"step": "END",
			"invalid": [],
			"createdTimestamp": "2024-10-16T03:00:13.564Z"
		}
	}
}
```

**Response Fields:**

| Field | Description |
|-------|-------------|
| action | Action performed by the command |
| state | Current state of the command |
| step | Current step of the command |
| invalid | List of validation errors (empty in this case) |
| createdTimestamp | Timestamp when the command was created |

[ Un-allocate a transaction](#unallocate) 

<h4 name="unallocate" id="unallocate"></h4>


#### Un-allocate a Transaction

**Mutation: unallocate**

This mutation removes the allocation of a transaction from client accounts.

```graphql
mutation {
  unallocate(i: {unallocatableId: "UmVjZWlwdDoyZWRkY2E5YTk2YTE1OWYzYjRiZDNiZjcyZjExZWIxNWUzYTcxMWI4MzljMGQ4YTA1NjE0ZTNmZDA2YWNjMTFl"}) {
    commandId
  }
}
```
**Input Fields:**

| Field | Description |
|-------|-------------|
| unallocatableId | Unique id of the Payment or Receipt to be unallocated |

[Query un-allocate transaction command](#transactioncommand) 

<h4 name="transactioncommand" id="transactioncommand"></h4>

#### Query Un-allocate Transaction Command

**Query: node: unallocate**

This query retrieves the status of an un-allocation command.

```graphql
query QueryCommand($commandId: ID!){
	node(id: $commandId){
		__typename...onCommand{
			actionstatestepinvalid{
				fieldreason__typename
			}createdTimestamp
		}
	}
}
```

**Variables:**

```json
{
	"commandId": "Q29tbWFuZDo2MTY1NjdlOC1mNTA3LTQ3NmEtOWE3ZC03YjRkNGQ4NDdjMmE="
}
```

**Response:**

```json
{
	"data": {
		"node": {
			"__typename": "UnallocateCommand",
			"action": "UNALLOCATE",
			"state": "SUCCESSFUL",
			"step": "END",
			"invalid": [],
			"createdTimestamp": "2024-10-16T03:10:39.939Z"
		}
	}
}
```

**Response Fields:**

| Field | Description |
|-------|-------------|
| action | Action performed by the command |
| state | Current state of the command |
| step | Current step of the command |
| invalid | List of validation errors (empty in this case) |
| createdTimestamp | Timestamp when the command was created |

Transaction allocation

---
layout: detail
title: ACMC payment overview
menu_key: sample
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-sample/payment/
---
---
[Payment examples overview](#paymentoverview) 

<h4 name="paymentoverview" id="paymentoverview"></h4>

#### Payment Examples Overview:

This page provides comprehensive examples of GraphQL queries and mutations for managing payments in the ANZ Cash Management Central (ACMC) system. These operations cover various aspects of payment management, including initiating payments, querying payment status, and handling payment-related errors. Each example is accompanied by explanations of input fields, sample requests, and response structures to help developers effectively integrate with the ACMC API for payment-related operations.

[Important security note](#securitynote) 

<h4 name="securitynote" id="securitynote"></h4>

#### Important Security Note

All payment mutations require payload encryption to ensure the security of sensitive information. Before making any payment, you must use the `doEncrypt` operation to encrypt the payment payload. For more information on how to use `doEncrypt`, please refer to the [Payload Encryption documentation](/acmc/api/graphql-auth/doencrypt/).



[Client accounts outwards payments](#accountsoutwardspayments) 

<h4 name="accountsoutwardspayments" id="accountsoutwardspayments"></h4>

#### Client Accounts Outwards Payments

Client Accounts Outwards Payments allow for initiating payments from client accounts to external accounts. These payments support various payment types such as Direct Entry (DE), OSKO, and Real-Time Gross Settlement (RTGS).

[View Client Accounts Outwards Payments Samples](/product/ACMC%20API/code?path=GraphQL%20API%20examples/Payments/Client%20accounts%20outwards%20payments)

**Key operations:**
- Initiate Payment
- Query Payment Status

[Payments between CLA and CLI](#claandcli) 

<h4 name="claandcli" id="claandcli"></h4>

#### Payments between CLA and CLI

This section covers payments between Client Accounts and Client Linked Accounts (CLAs) in both directions.

[View CLA to/from CLI Payment Samples](/product/ACMC%20API/code?path=GraphQL%20API%20examples/Payments/Payments%20between%20CLI%20and%20CLA)

**Key operations:**
- Initiate Payment from Client Account to CLA
- Initiate CLA Payment Request
- Query CLA Payment Status

[Aggregated payments](#aggregatedpayments) 

<h4 name="aggregatedpayments" id="aggregatedpayments"></h4>

#### Aggregated Payments

Aggregated Payments allow for debiting multiple Client Money Accounts (CLI) and crediting a single Customer Linked Account (CLA).

[View Aggregated Payment Samples](/product/ACMC%20API/code?path=GraphQL%20API%20examples/Payments/Aggregated%20payment%20(CLI%20to%20CLA))

**Key operations:**
- Create Aggregated Payment
- Query Aggregated Payment Creation Command Status

[Disaggregated payments](#disaggregatedpayments) 

<h4 name="disaggregatedpayments" id="disaggregatedpayments"></h4>

#### Disaggregated Payments

Disaggregated Payments allow for distributing a lump sum from a CLA to multiple Client Money Accounts (CLI).

[View Disaggregated Payment Samples](/product/ACMC%20API/code?path=GraphQL%20API%20examples/Payments/Disaggregated%20payment%20(CLA%20to%20CLI))

**Key operations:**
- Create Disaggregated Payment
- Query Disaggregated Payment Creation Command Status

[Payment cut-off times](#cutofftimes) 

<h4 name="cutofftimes" id="cutofftimes"></h4>

#### Payment Cut-Off Times

Depending on the payment method and the time a payment instruction is released for processing, ANZ will process transactions either by close of business the same day or the next Business Day. The payment cut-off times below are subject to change in accordance with Documents and Operations Processing times advised and agreed with ANZ.

| Payments from a Client Account (today*) via | Processing cut-off by ACMC |
|---------------------------------------------|-------------------------------|
| DE                                          | 07:30pm (AEST/AEDT)           |
| RTGS                                        | 4:30pm (AEST/AEDT)            |
| OSKO                                        | No cut-off                    |
| CLA payment                                 | No cut-off                    |

*If 'today' is a non-Business Day, the transaction will be treated as being made on the next Business Day and processed by ANZ CMM accordingly.

---

Each sample page provides detailed GraphQL queries or mutations, along with explanations of the parameters and expected responses. These samples demonstrate how to interact with the ACMC API for various payment operations. For more information on payment processing details, please refer to the individual sample pages or the ACMC API documentation.







<style>
  ol {
    list-style-type: decimal; /* This ensures numbers appear in ordered list */
    padding-left: 20px;
  }

  ul {
    list-style-type: disc; /* This ensures bullet points appear in unordered list */
    padding-left: 20px;
  }

---
layout: detail
title: Client accounts outwards payments
menu_key: sample
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-sample/payment/clioutwards/
---
---

[Client accounts outwards payments overview](#clientaccount) 

<h4 name="clientaccount" id="clientaccount"></h4>

#### Client Accounts Outwards Payments Overview:

This page provides examples of GraphQL queries and mutations for initiating payments from client accounts in the ANZ Cash Management Central (ACMC) system.

[Overview of client accounts outwards payments initiation](#overviewclient) 

<h4 name="overviewclient" id="overviewclient"></h4>

#### Overview of Client Accounts Outwards Payments Initiation

The ACMC system supports initiating domestic payments from Client Accounts using various payment types:

**Payment Types:**
   - Direct Entry (DE)
   - OSKO
   - Real-Time Gross Settlement (RTGS)

**Destination:**
   - Payments can be initiated to a specified destination account.

**Cut-off Times:**
   - Cut-off times are applicable based on the specified Payment Type.
   - Payments initiated after cut-off times:
     - Will remain part of the Client Account balance for interest calculation purposes.
     - Will be completed on the next available Business Day.

The following GraphQL operations allow you to initiate and manage payments within the ACMC system.

[Table of contents](#ofcontents) 

<h4 name="ofcontents" id="ofcontents"></h4>

#### Table of Contents

1. [Initiate payment](#initiate-payment)
2. [Query payment status](#query-payment-status)


[Initiate payment](#initiatepayment) 

<h4 name="initiatepayment" id="initiatepayment"></h4>

#### Initiate Payment

**Mutation: doEncrypted (action: payment, payment-method: NPP)**

This mutation initiates a payment from a client account using encrypted input.

```graphql
mutation ($input: EncryptedInput!) {
    doEncrypted(i: $input) {
        commandId
    }
}
```

**Variables:**

```json
{
    "input": {
        "encryptedPayload": {
            "action": "payment",
            "payment-method": "NPP",
            "recipient": {
                "account-number": "1347825467",
                "bank-code": "083054",
                "name": "Testing"
            },
            "sender": {
                "account": {
                    "id": "QWNjb3VudDo1OTNmYThlMGFiNzQ4NDRmNzU0Y2M0ZGQ4MTA2ZTc5ZTEzYjhjNjgzMzc1NDBmNGMyNzc2OTRmZjhkNWRmYjVh"
                }
            },
            "amount": {
                "value": "5.00",
                "currency": "AUD"
            },
            "value-date": "2024-10-07",
            "reference": "npp pay"
        }
    }
}
```

**Input Fields**

| Field | Description |
|-------|-------------|
| action | Type of action ("payment") |
| payment-method | Payment method (e.g., "NPP") |
| recipient | Details of the recipient account |
| sender | Details of the sender account |
| amount | Payment amount and currency |
| value-date | Date for the payment (YYYY-MM-DD) |
| reference | Payment reference |

**Recipient Fields**

| Field | Description |
|-------|-------------|
| account-number | Recipient's account number |
| bank-code | Recipient's bank code (BSB) |
| name | Recipient's name |

**Sender Fields**

| Field | Description |
|-------|-------------|
| account.id | ID of the sender's account |

**Amount Fields**

| Field | Description |
|-------|-------------|
| value | Payment amount |
| currency | Currency code (e.g., "AUD") |

[Query payment status](#querypaymentstatus) 

<h4 name="querypaymentstatus" id="querypaymentstatus"></h4>

#### Query Payment Status

**Query: node**

This query retrieves the status of a specific payment.

```graphql
query QueryCommand {
	node(id: "Q29tbWFuZDo5MTAxY2YwNi1iZTU3LTRjMDEtYWJmNi0xYWQ5NTM2NzA4Yjg=") {
		__typename
		... on GenericCommand {
			action
			state
			step
			invalid {
				field
				reason
			}
		}
		... on EncryptedCommand {
			id
			state
			invalid {
				field
				reason
			}

			unencryptedCommand {
				id
				createdTimestamp
			}
			unencryptedCommand {
				... on MakeNppPaymentCommand {
					action
					id
					payment {
						amount {
							creditDebit
							value
							currency
						}
						createdTimestamp
						recipient {
							accountNumber
							name
						}
						status
						reason
						paymentMethod
						transactions {
							edges {
								node {
									id
									state
									valueDate
								}
							}
						}
					}
					userInput {
						purpose
						transaction {
							id
						}
					}
					invalid {
						field
						reason
						code
					}
				}
			}
		}
	}
}
```

**Response:**

```json
{
    "data": {
        "node": {
            "__typename": "EncryptedCommand",
            "id": "Q29tbWFuZDo5MTAxY2YwNi1iZTU3LTRjMDEtYWJmNi0xYWQ5NTM2NzA4Yjg=",
            "state": "SUCCESSFUL",
            "invalid": [],
            "unencryptedCommand": {
                "id": "Q29tbWFuZDoxMzZlMjIwMTcwM2I4Y2U1OGU4ZWM0OWM4ZTM2OWZkODFkNTZhNzE5YjJkNzI0MWU3NjNlNzE1Nzc1Mjg2MGY4",
                "createdTimestamp": "2024-10-07T06:16:48.822Z",
                "action": "MAKE-NPP-PAYMENT",
                "payment": {
                    "amount": {
                        "creditDebit": "DEBIT",
                        "value": "5.00",
                        "currency": "AUD"
                    },
                    "createdTimestamp": "2024-10-07T06:16:52.839Z",
                    "recipient": {
                        "accountNumber": "1347825467",
                        "name": "Testing"
                    },
                    "status": "completed",
                    "reason": "",
                    "paymentMethod": "npp",
                    "transactions": {
                        "edges": [
                            {
                                "node": {
                                    "id": "VHJhbnNhY3Rpb246MzQ3MDhlZmNlZDMwYmFjNjdlZjViMWQwZmY1OTljYjRiODgzNzFlNDFkZGY4M2VlMjYzYWE4MWY4Y2NmMTdmZQ==",
                                    "state": "SUCCESSFUL",
                                    "valueDate": "2024-10-07"
                                }
                            }
                        ]
                    }
                },
                "invalid": []
            }
        }
    }
}
```


**Response Fields**

| Field | Type | Description |
|-------|------|-------------|
| data.node | INTERFACE | The root object representing the queried node |
| data.node.id | SCALAR! | Unique identifier for the encrypted command |
| data.node.state | ENUM! | Current state of the command (e.g., "SUCCESSFUL") |
| data.node.invalid | OBJECT! | List of validation errors (empty in this case) |
| unencryptedCommand | INTERFACE | Decrypted details of the command |
| unencryptedCommand.id | SCALAR! | Unique identifier for the unencrypted command |
| unencryptedCommand.createdTimestamp | SCALAR | Timestamp when the command was created |
| unencryptedCommand.action | SCALAR! | Type of action performed (e.g., "MAKE-NPP-PAYMENT") |
| payment | OBJECT | Details of the payment |
| payment.amount | OBJECT! | Amount details of the payment |
| payment.amount.creditDebit | ENUM! | Indicates if it's a credit or debit transaction |
| payment.amount.value | SCALAR! | The monetary value of the transaction |
| payment.amount.currency | SCALAR! | The currency code (e.g., "AUD") |
| payment.createdTimestamp | SCALAR! | Timestamp when the payment was created |
| payment.recipient | OBJECT | Details of the payment recipient |
| payment.recipient.accountNumber | SCALAR! | Account number of the recipient |
| payment.recipient.name | SCALAR | Name of the recipient |
| payment.status | SCALAR | Current status of the payment (e.g., "completed") |
| payment.reason | SCALAR | Reason for the payment status (empty in this case) |
| payment.paymentMethod | SCALAR | Method used for the payment (e.g., "npp") |
| payment.transactions | \[INTERFACE!]! | List of transactions associated with this payment |
| payment.transactions.edges[].node.id | SCALAR! | Unique identifier for the transaction |
| payment.transactions.edges[].node.state | ENUM! | Current state of the transaction |
| payment.transactions.edges[].node.valueDate | SCALAR! | The value date of the transaction |
| unencryptedCommand.invalid | \[OBJECT]! | List of validation errors for the unencrypted command (empty in this case) |


---

Client accounts outwards payments

---
layout: detail
title: Payments between CLA and CLI
menu_key: sample
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-sample/payment/clatofromcli/
---
---

[Payments between CLA and CLI overview](#paymentsbetween) 

<h4 name="paymentsbetween" id="paymentsbetween"></h4>

#### Payments between CLA and CLI Overview:

This page provides examples of GraphQL queries and mutations for initiating payments between Client Accounts and Client Linked Accounts (CLAs) in the ANZ Cash Management Central (ACMC) system.

[Overview of CLA payment initiation](#clapayment) 

<h4 name="clapayment" id="clapayment"></h4>

### Overview of CLA Payment Initiation

The ACMC system supports initiating payments between Client Accounts and CLAs in both directions:

**Payments from Client Account to CLA:**
   Can be initiated using two methods:
   - Using Payment Type 'CLA Payment'
   - Using any Payment Type and specifying BSB and account number of the CLA

**Payments from CLA to Client Account:**
   Can be initiated using two methods:
   - Using 'CLA Payment Request' function within ACMC
   - Accessing the CLA via an appropriate ANZ Electronic Banking Channel, selecting any Payment Type, and specifying the Client Account's BSB and account number

The following GraphQL operations allow you to initiate and manage these CLA-related payments within the ACMC system.


[Initiate payment from client account to CLA](#clientaccount) 

<h4 name="clientaccount" id="clientaccount"></h4>

#### Initiate Payment from Client Account to CLA

**Mutation: doEncrypted (action: payment)**

This mutation initiates a payment from a client account to a CLA.

```graphql
mutation ($input: EncryptedInput!) {
    doEncrypted(i: $input) {
        commandId
    }
}
```

Variables:

```json
{
    "input": {
        "encryptedPayload": {
            "action": "payment",
            "recipient": {
                "customer-linked-account": {
                    "id": "Q3VzdG9tZXJMaW5rZWRBY2NvdW50OmEwODQxNzcyN2E4ZjNkODEyYTViMDY4ZDRjZjU4YTRiMmY5NWE5ZTg1OGU4YThlOTNmMWQ3MDkyNThmZjMzZmI="
                }
            },
            "sender": {
                "account": {
                    "id": "QWNjb3VudDo1OTNmYThlMGFiNzQ4NDRmNzU0Y2M0ZGQ4MTA2ZTc5ZTEzYjhjNjgzMzc1NDBmNGMyNzc2OTRmZjhkNWRmYjVh"
                }
            },
            "amount": {
                "value": "5.00",
                "currency": "AUD"
            },
            "value-date": "2024-10-08",
            "reference": "Client Account to CLA"
        }
    }
}
```

[Initiate CLA payment request](#paymentrequest) 

<h4 name="paymentrequest" id="paymentrequest"></h4>

#### Initiate CLA Payment Request

**Mutation: doEncrypted (action: payment-request)**

This mutation initiates a payment request from a CLA to a client account.

```graphql
mutation ($input: EncryptedInput!) {
    doEncrypted(i: $input) {
        commandId
    }
}
```

Variables:

```json
{
    "input": {
        "encryptedPayload": {
            "action": "payment-request",
            "customer-linked-account": {
                "id": "Q3VzdG9tZXJMaW5rZWRBY2NvdW50OmEwODQxNzcyN2E4ZjNkODEyYTViMDY4ZDRjZjU4YTRiMmY5NWE5ZTg1OGU4YThlOTNmMWQ3MDkyNThmZjMzZmI="
            },
            "requester": {
                "account": {
                    "id": "QWNjb3VudDo1OTNmYThlMGFiNzQ4NDRmNzU0Y2M0ZGQ4MTA2ZTc5ZTEzYjhjNjgzMzc1NDBmNGMyNzc2OTRmZjhkNWRmYjVh"
                }
            },
            "amount": {
                "value": "5.25",
                "currency": "AUD"
            },
            "value-date": "2024-10-08",
            "reference": "CLA to Client Account"
        }
    }
}
```

[Query CLA payment status](#paymentstatus) 

<h4 name="paymentstatus" id="paymentstatus"></h4>

#### Query CLA Payment Status

**Query: node**

This query retrieves the status of a specific CLA payment or payment request.

```graphql
query QueryCommand($id: ID!) {
    node(id: $id) {
        __typename
        ... on EncryptedCommand {
            id
            state
            invalid {
                field
                reason
            }
            unencryptedCommand {
                id
                createdTimestamp
                ... on MakeNppPaymentCommand {
                    action
                    payment {
                        amount {
                            creditDebit
                            value
                            currency
                        }
                        createdTimestamp
                        recipient {
                            accountNumber
                            name
                        }
                        status
                        reason
                        paymentMethod
                        transactions {
                            edges {
                                node {
                                    id
                                    state
                                    valueDate
                                }
                            }
                        }
                    }
                    invalid {
                        field
                        reason
                        code
                    }
                }
            }
        }
    }
}
```

**Variables:**

```json
{
    "id": "Q29tbWFuZDplYzczNjljZC1lZTgxLTQ3MzMtODlmYS0xYTU0YzZjYjBhNzA="
}
```
**Response:**

```json
{
	"data": {
		"node": {
			"__typename": "EncryptedCommand",
			"id": "Q29tbWFuZDplYzczNjljZC1lZTgxLTQ3MzMtODlmYS0xYTU0YzZjYjBhNzA=",
			"state": "SUCCESSFUL",
			"invalid": [],
			"unencryptedCommand": {
				"id": "Q29tbWFuZDpiMDA5NTQ2ZjFhZjc1MGFjODNjZTgzZmE2OGYyZDMyNDdkMmIxMjdiZWExMWIzYzlmYjYzMzQ2NzUxNDIyYWQ5",
				"createdTimestamp": "2024-10-08T05:00:46.333Z",
				"action": "MAKE-NPP-PAYMENT",
				"payment": {
					"amount": {
						"creditDebit": "DEBIT",
						"value": "5.00",
						"currency": "AUD"
					},
					"createdTimestamp": "2024-10-08T05:00:51.300Z",
					"recipient": {
						"accountNumber": "189524201",
						"name": "Test CLA"
					},
					"status": "completed",
					"reason": "",
					"paymentMethod": "npp",
					"transactions": {
						"edges": [
							{
								"node": {
									"id": "VHJhbnNhY3Rpb246MjE3YzAzOWJhZDI0NGNhODQwOGIxNTE5N2EwZWNhY2M2MjU5Y2UxMmI4ZmRmYjY3NWM1YjQzNWQ2ZmYwMTc3ZQ==",
									"state": "SUCCESSFUL",
									"valueDate": "2024-10-08"
								}
							}
						]
					}
				},
				"invalid": []
			}
		}
	}
}
```

**Response Fields**

| Field | Type | Description |
|-------|------|-------------|
| data.node | INTERFACE | The root object representing the queried node |
| data.node.id | SCALAR! | Unique identifier for the encrypted command |
| data.node.state | ENUM! | Current state of the command (e.g., "SUCCESSFUL") |
| data.node.invalid | OBJECT! | List of validation errors (empty in this case) |
| unencryptedCommand | INTERFACE | Decrypted details of the command |
| unencryptedCommand.id | SCALAR! | Unique identifier for the unencrypted command |
| unencryptedCommand.createdTimestamp | SCALAR | Timestamp when the command was created |
| unencryptedCommand.action | SCALAR! | Type of action performed (e.g., "MAKE-NPP-PAYMENT") |
| payment | OBJECT | Details of the payment |
| payment.amount | OBJECT! | Amount details of the payment |
| payment.amount.creditDebit | ENUM! | Indicates if it's a credit or debit transaction |
| payment.amount.value | SCALAR! | The monetary value of the transaction |
| payment.amount.currency | SCALAR! | The currency code (e.g., "AUD") |
| payment.createdTimestamp | SCALAR! | Timestamp when the payment was created |
| payment.recipient | OBJECT | Details of the payment recipient |
| payment.recipient.accountNumber | SCALA! | Account number of the recipient |
| payment.recipient.name | SCALAR | Name of the recipient |
| payment.status | SCALAR | Current status of the payment (e.g., "completed") |
| payment.reason | SCALAR | Reason for the payment status (empty in this case) |
| payment.paymentMethod | SCALAR | Method used for the payment (e.g., "npp") |
| payment.transactions | \[INTERFACE!]! | List of transactions associated with this payment |
| payment.transactions.edges[].node.id | SCALAR! | Unique identifier for the transaction |
| payment.transactions.edges[].node.state | ENUM! | Current state of the transaction |
| payment.transactions.edges[].node.valueDate | SCALAR! | The value date of the transaction |
| unencryptedCommand.invalid | \[OBJECT]! | List of validation errors for the unencrypted command (empty in this case) |

---

Payments between CLI and CLA

---
layout: detail
title: ACMC aggregated payment (CLI to CLA)
menu_key: sample
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-sample/payment/aggregated-payment/
---
---

[Aggregated payment (CLI to CLA) overview](#aggregated) 

<h4 name="aggregated" id="aggregated"></h4>

#### Aggregated Payment (CLI to CLA) Overview:

When requesting an aggregated payment, please note the following guidelines and exceptions:

1. The target account must be a domestic AU account.
2. The customer must provide a unique reference that will be stored and can be accessed at both the client account level and source account level.
3. Once the customer instruction is successfully processed, client transactions and the aggregated payment should be settled near real-time on the applicable accounts (i.e., Client Accounts & Source Account).

[Exceptions and error handling](#exceptionanderrorhandling) 

<h4 name="exceptionanderrorhandling" id="exceptionanderrorhandling"></h4>

#### Exceptions and Error Handling

**Client Account Issues**
If the customer instruction contains details of a client account that:
- Does not exist
- Has insufficient funds
- Has an active restraint

Then:
- The associated client transaction amount will be excluded from the aggregated payment.
- The aggregated total amount will be revised/updated before being paid to the target account.
- The status of the aggregated payment will indicate the existence of exception(s). For example: "Aggregated payment made but there were exceptions" (Note: The actual message may vary).
- The exception account and details (client account, transaction amount, exception reason, aggregation reference) will be recorded and can be queried by the customer.

**Downstream Processing Failure**
In case of downstream processing failure (e.g., source account has insufficient funds):
- The exception will be reflected in the status of the aggregated payment.
- All associated client transaction amounts will be reverted back as available balance.

**General Validation Exceptions**
The request will not proceed and the exception will be made available to the customer in the following cases:
- Mandatory fields missing from request
- Invalid data (e.g., invalid payment method, account format, etc.)
- Duplicate aggregated payment reference (i.e., not unique)
- Incorrect total number of instructions
- Incorrect total value of instructions

[Create aggregated payment](#createAggregated) 

<h4 name="createAggregated" id="createAggregated"></h4>

#### Create Aggregated Payment

**Mutation: doEncrypted (action: aggregate-payment, creditDebit: DEBIT)**

This mutation creates a new aggregated payment in the system, taking into account the guidelines and exceptions mentioned above.

```graphql
mutation ($input: EncryptedInput!) {
    doEncrypted(i: $input) {
        commandId
    }
}
```

**Variables:**

```json
{
    "input": {
        "encryptedPayload": {
            "action": "aggregate-payment",
            "reference": "paying 25 ref1",
            "externalAccount": {
                "customer-linked-account": {
                    "id": "Q3VzdG9tZXJMaW5rZWRBY2NvdW50OmEwODQxNzcyN2E4ZjNkODEyYTViMDY4ZDRjZjU4YTRiMmY5NWE5ZTg1OGU4YThlOTNmMWQ3MDkyNThmZjMzZmI="
                }
            },
            "count": 2,
            "total-amount": {
                "value": "25.00",
                "currency": "AUD",
                "creditDebit": "DEBIT"
            },
            "instructions": [
                {
                    "tracing-id": "first pay 15",
                    "narrative": "pay 15",
                    "account": {
                        "id": "QWNjb3VudDo1OTNmYThlMGFiNzQ4NDRmNzU0Y2M0ZGQ4MTA2ZTc5ZTEzYjhjNjgzMzc1NDBmNGMyNzc2OTRmZjhkNWRmYjVh"
                    },
                    "amount": {
                        "value": "15.00",
                        "currency": "AUD",
                        "creditDebit": "DEBIT"
                    }
                },
                {
                    "tracing-id": "second pay 10",
                    "narrative": "pay 10",
                    "account": {
                        "id": "QWNjb3VudDpiMTFiYWQ3YzkzODFiZjA3MjMzOTE0YmM0OTljM2QwMTM2OGU3NTFhNTRkNjMxNzdhNDIxOTA5MjljMTQ0MDIz"
                    },
                    "amount": {
                        "value": "10.00",
                        "currency": "AUD",
                        "creditDebit": "DEBIT"
                    }
                }
            ]
        }
    }
}
```

**Input Fields**

The `EncryptedInput` contains an `encryptedPayload` with the following fields:

| Field | Type | Description |
|-------|------|-------------|
| action | SCALAR! | Action type, set to "aggregate-payment" for disaggregated payments |
| reference | SCALAR | Unique reference for the aggregated payment |
| externalAccount | UNION | Contains the customer-linked-account / destination account details |
| count | SCALAR | Number of instructions |
| total-amount | OBJECT | Total amount and currency of the aggregated payment |
| instructions | OBJECT! | List of payment instructions |

**Instruction Object**

| Field | Type | Description |
|-------|------|-------------|
| tracing-id | SCALAR | tracing identifier for the instruction |
| narrative | SCALAR | Description of the instruction |
| account | OBJECT | Contains the account identifier to credit |
| amount | OBJECT | Amount and currency for this instruction |

[Query aggregated payment creation command status](#queryaggregated) 

<h4 name="queryaggregated" id="queryaggregated"></h4>

#### Query Aggregated Payment Creation Command Status

**Query: node**

This query retrieves the status of a command, such as the aggregated payment creation command.

```graphql
query QueryCommand {
    node(id: "Q29tbWFuZDo1YWRhMTkzMy0zNDI4LTQzMDQtOGMyNC05NTFiNTY2M2E4NTM=") {
        ... on EncryptedCommand {
            action
            id
            state
            user
            unencryptedCommand {
                ... on AggregatePaymentExecuteCommand {
                    action
                    id
					state
                    invalid {
                        code
                        field
                        reason
                    }
                    aggregatePayment {
                        count
                        successfulCount
                        failedCount
                        totalAmount {
                            value
                        }
                        totalAmountSuccessful {
                            value
                        }
                        totalAmountFailed {
                            value
                        }
                        count
                        customerTransactionReference
                        paymentState
                        instructions {
                            edges {
                                node {
                                    account {
                                        accountNumber
                                    }
                                    amount {
                                        creditDebit
                                        currency
                                        value
                                    }
                                    state
                                    tracingId
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```

**Input Fields**

| Field | Type | Description |
|-------|------|-------------|
| id | SCALAR! | The ID of the command to query |

**CommandState**

The command `state` field in the response can have the following values. note that command state is different from the payment state.
- `SUBMITTED`
- `SUCCESSFUL`
- `PARTIALLY_SUCCESSFUL`
- `FAILED`

**PaymentState**

The payment `state` field in the response can have the following values.
- `SUBMITTED`
- `RECEIVED`
- `PENDING`
- `PROCESSING`
- `COMPLETED`
- `COMPLETED_WITH_ERRORS`
- `REJECTED`

**Response**

```json
{
	"data": {
		"node": {
			"action": "DO-ENCRYPTED-COMMAND",
			"id": "Q29tbWFuZDo1YWRhMTkzMy0zNDI4LTQzMDQtOGMyNC05NTFiNTY2M2E4NTM=",
			"state": "SUCCESSFUL",
			"user": "SJTRADING",
			"unencryptedCommand": {
				"action": "AGGREGATE-PAYMENT-EXECUTE",
				"id": "Q29tbWFuZDpiYWQxZjk2MmQ0MWQ1NTAzNDAzN2E5YWUzY2RkZDczOWM1MjE5YmFhNmIzYmYzYzhkYWYzNGE0YjRkZjRkYzZj",
				"state": "SUCCESSFUL",
				"invalid": [],
				"aggregatePayment": {
					"count": 2,
					"successfulCount": 2,
					"failedCount": 0,
					"totalAmount": {
						"value": "25.00"
					},
					"totalAmountSuccessful": {
						"value": "25.00"
					},
					"totalAmountFailed": {
						"value": "0.00"
					},
					"customerTransactionReference": null,
					"paymentState": "COMPLETED",
					"instructions": {
						"edges": [
							{
								"node": {
									"account": {
										"accountNumber": "173358181"
									},
									"amount": {
										"creditDebit": "DEBIT",
										"currency": "AUD",
										"value": "10.00"
									},
									"state": "SUCCEEDED",
									"tracingId": "second pay 10"
								}
							},
							{
								"node": {
									"account": {
										"accountNumber": "173355850"
									},
									"amount": {
										"creditDebit": "DEBIT",
										"currency": "AUD",
										"value": "15.00"
									},
									"state": "SUCCEEDED",
									"tracingId": "first pay 15"
								}
							}
						]
					}
				}
			}
		}
	}
}
```

**Response Fields**

The following table explains the structure and meaning of each field in the response:

| Field | Type | Description |
|-------|------|-------------|
| data.node | INTERFACE | The entity containing information about the command |
| data.node.action | SCALAR! | The operation type of the command, "DO-ENCRYPTED-COMMAND" |
| data.node.id | SCALAR!| The unique identifier of the command |
| data.node.state | ENUM! | The current state of the encryption command, "SUCCESSFUL" |
| data.node.user | SCALAR! | The user who initiated the command, "SJTRADING" |
| data.node.unencryptedCommand | INTERFACE | Contains nested command in the encrypted payload|
| unencryptedCommand.action | SCALAR! | The specific action of the unencrypted command, "AGGREGATE-PAYMENT-EXECUTE" |
| unencryptedCommand.id | SCALAR! | The unique identifier of the unencrypted command |
| unencryptedCommand.state | ENUM! | The current state of the aggregate command, "SUCCESSFUL" |
| unencryptedCommand.invalid | OBJECT! | List of any invalid fields or errors (empty in this case) |
| unencryptedCommand.aggregatePayment | OBJECT | Contains the business process node of the aggregated payment |
| aggregatePayment.count | SCALAR | The total number of instructions in the payment, 2 |
| aggregatePayment.state | ENUM | The current state of the aggregate payment, "COMPLETE" |
| aggregatePayment.successfulCount | SCALAR | The number of successful instructions, 2 |
| aggregatePayment.failedCount | SCALAR | The number of failed instructions, 0 |
| aggregatePayment.totalAmount.value | SCALAR! | The total amount of the aggregate payment, "25.00" |
| aggregatePayment.totalAmountSuccessful.value | SCALAR! | The total amount of successful transactions, "25.00" |
| aggregatePayment.totalAmountFailed.value | SCALAR! | The total amount of failed transactions, "0.00" |
| aggregatePayment.customerTransactionReference | SCALAR | Customer's reference for the transaction, null in this case |
| aggregatePayment.paymentState | ENUM | The overall state of the payment, "COMPLETED" |
| aggregatePayment.instructions | OBJECT! | Contains the list of individual payment instructions |
| instructions.edges[].node | INTERFACE | Individual instruction details |
| instructions.edges[].node.account.accountNumber | SCALAR | The account number for the instruction |
| instructions.edges[].node.amount.creditDebit | ENUM! | Indicates if it's a credit or debit, "DEBIT" |
| instructions.edges[].node.amount.currency | SCALAR! | The currency of the transaction, "AUD" |
| instructions.edges[].node.amount.value | SCALAR! | The amount of the individual instruction |
| instructions.edges[].node.state | ENUM | Current state of the instruction, "SUCCEEDED" |
| instructions.edges[].node.tracingId | SCALAR | Unique identifier for the instruction |

---

Aggregated payment (CLI to CLA)

---
layout: detail
title: ACMC disaggregated payment (CLA to CLI)
menu_key: sample
group: acmc
hero_key: acmc
permalink: /acmc/api/graphql-sample/payment/disaggregated-payment/
---
---

[Disaggregated payment (CLA to CLI) ovrview](#disaggregatedpayment) 

<h4 name="disaggregatedpayment" id="disaggregatedpayment"></h4>

#### Disaggregated Payment (CLA to CLI) Overview:

When requesting a disaggregated payment, please note the following guidelines and exceptions:

1. The funding account must be a CLA (Customer Linked Account).
2. The customer must provide a unique reference that will be stored and can be accessed at both the client account level and source account level.
3. Once the customer instruction is successfully processed, client receipts and the lump sum amount from CLA should be settled near real-time on the applicable accounts.


[Exceptions and error handling](#exceptionanderrorhandling) 

<h4 name="exceptionanderrorhandling" id="exceptionanderrorhandling"></h4>

#### Exceptions and Error Handling

**Client Account Issues**
If the customer instruction contains details of a client account that:
- Does not exist
- Has an active restraint

Then:
- The associated client transaction amount will not be distributed.
- The lump sum amount for disaggregation must be revised/updated (excluding the client transaction amount) before it is paid from the CLA.
- The status of the disaggregated transaction will indicate the existence of exception(s). For example: "Disaggregated transaction is processed with exceptions" (Note: The actual message may vary).
- The exception account and details (client account, transaction amount, exception reason, disaggregation reference) will be recorded and can be queried by the customer.

**CLA Payment Failure**
In case of failure of payment from CLA (e.g., insufficient funds):
- The exception will be reflected in the status of the disaggregated payment.
- All associated client receipts will not be processed.

**General Validation Exceptions**
The request will not proceed and the exception will be made available to the customer in the following cases:
- Mandatory fields missing from request
- Invalid data (e.g., CLA detail, account format, etc.)
- Duplicate disaggregated transaction reference (i.e., not unique)
- Incorrect total number of instructions
- Incorrect total value of instructions

[Create disaggregated payment](#createdisaggregated) 

<h4 name="createdisaggregated" id="createdisaggregated"></h4>

#### Create Disaggregated Payment

**Mutation: doEncrypted (action: aggregate-payment, creditDebit: CREDIT)**

This mutation creates a new disaggregated payment in the system, taking into account the guidelines and exceptions mentioned above.

```graphql
mutation ($input: EncryptedInput!) {
  doEncrypted(i: $input) {
    commandId
  }
}
```

**Variables:**

```json
{
    "input": {
        "encryptedPayload": {
            "action": "aggregate-payment",
            "reference": "DeAgg CLAtest 44",
            "customer-transaction-reference": "Deagg CLA 16062022",
            "externalAccount": {
                "customer-linked-account": {
                    "id": "Q3VzdG9tZXJMaW5rZWRBY2NvdW50OmEwODQxNzcyN2E4ZjNkODEyYTViMDY4ZDRjZjU4YTRiMmY5NWE5ZTg1OGU4YThlOTNmMWQ3MDkyNThmZjMzZmI="
                }
            },
            "count": 2,
            "total-amount": {
                "value": "44.00",
                "currency": "AUD",
                "creditDebit": "CREDIT"
            },
            "instructions": [
                {
                    "account": {
                        "id": "QWNjb3VudDo1OTNmYThlMGFiNzQ4NDRmNzU0Y2M0ZGQ4MTA2ZTc5ZTEzYjhjNjgzMzc1NDBmNGMyNzc2OTRmZjhkNWRmYjVh"
                    },
                    "amount": {
                        "value": "27.00",
                        "currency": "AUD",
                        "creditDebit": "CREDIT"
                    },
                    "tracing-id": "Trace ID ref 25",
                    "narrative": "ref 25"
                },
                {
                    "account": {
                        "id": "QWNjb3VudDpiMTFiYWQ3YzkzODFiZjA3MjMzOTE0YmM0OTljM2QwMTM2OGU3NTFhNTRkNjMxNzdhNDIxOTA5MjljMTQ0MDIz"
                    },
                    "amount": {
                        "value": "17.00",
                        "currency": "AUD",
                        "creditDebit": "CREDIT"
                    },
                    "tracing-id": "Trace ID ref 15",
                    "narrative": "ref 15"
                }
            ]
        }
    }
}
```

**Input Fields**

The `EncryptedInput` contains an `encryptedPayload` with the following fields:

| Field | Type | Description |
|-------|------|-------------|
| action | SCALAR! | Action type, set to "aggregate-payment" for disaggregated payments |
| reference | SCALAR | Unique reference for the disaggregated payment |
| customer-transaction-reference | SCALAR | Customer's reference for the transaction |
| externalAccount | UNION | Contains the customer-linked-account / destination account details |
| count | SCALAR | Number of instructions |
| total-amount | OBJECT | Total amount and currency of the disaggregated payment |
| instructions | OBJECT! | List of payment instructions |

**Instruction Object**

| Field | Type | Description |
|-------|------|-------------|
| tracing-id | SCALAR | tracing identifier for the instruction |
| narrative | SCALAR | Description of the instruction |
| account | OBJECT | Contains the account ID to debit |
| amount | OBJECT | Amount and currency for this instruction |

[Query sisaggregated payment creation command status](#querydisaggregated) 

<h4 name="querydisaggregated" id="querydisaggregated"></h4>

#### Query Disaggregated Payment Creation Command Status

**Query: node**

This query retrieves the status of a command, such as the disaggregated payment creation command.

```graphql
query QueryCommand {
  node(id: "Q29tbWFuZDo5NDNmMjAzMi0zY2QwLTQ4NGMtYWI0Zi0xY2FjOGQxYjY1ZjM=") {
    ... on EncryptedCommand {
      action
      id
      state
      user
      unencryptedCommand {
        ... on AggregatePaymentExecuteCommand {
          action
          id
          state
          invalid {
            code
            field
            reason
          }
          aggregatePayment {
            count
            successfulCount
            failedCount
            totalAmount {
              value
            }
            totalAmountSuccessful {
              value
            }
            totalAmountFailed {
              value
            }
            customerTransactionReference
            paymentRequestState
            instructions {
              edges {
                node {
                  narrative
                  account {
                    accountNumber
                    balances {
                      available {
                        value
                      }
                    }
                  }
                  amount {
                    creditDebit
                    currency
                    value
                  }
                  state
                  failure
                  tracingId
                }
              }
            }
          }
        }
      }
    }
  }
}
```

**Input Fields**

| Field | Type | Description |
|-------|------|-------------|
| id | SCALAR! | The ID of the command to query |

**CommandState**

The command `state` field in the response can have the following values. note that command state is different from the paymentRequestState state.
- `SUBMITTED`
- `SUCCESSFUL`
- `PARTIALLY_SUCCESSFUL`
- `FAILED`

**PaymentState**

The paymentRequestState `state` field in the response can have the following values.
- `SUBMITTED`
- `RECEIVED`
- `PENDING`
- `PROCESSING`
- `COMPLETED`
- `COMPLETED_WITH_ERRORS`
- `REJECTED`

**Response**

```json
{
	"data": {
		"node": {
			"action": "DO-ENCRYPTED-COMMAND",
			"id": "Q29tbWFuZDo5NDNmMjAzMi0zY2QwLTQ4NGMtYWI0Zi0xY2FjOGQxYjY1ZjM=",
			"state": "SUCCESSFUL",
			"user": "SJTRADING",
			"unencryptedCommand": {
				"action": "AGGREGATE-PAYMENT-EXECUTE",
				"id": "Q29tbWFuZDpmMzg2ZjFjMzU3N2IyZGY0OGYzNzc5ZGJhM2I5ZjBlZTVkOGQ2ZjgyYWJmNGU0ZDg3MjMzYjRjYTk2YWI3OWU3",
				"state": "SUCCESSFUL",
				"invalid": [],
				"aggregatePayment": {
					"count": 2,
					"successfulCount": 1,
					"failedCount": 1,
					"totalAmount": {
						"value": "49.00"
					},
					"totalAmountSuccessful": {
						"value": "20.00"
					},
					"totalAmountFailed": {
						"value": "29.00"
					},
					"customerTransactionReference": "ct ref closed 49",
					"paymentRequestState": "COMPLETED",
					"instructions": {
						"edges": [
							{
								"node": {
									"narrative": "ref ac 29",
									"account": {
										"accountNumber": "173361044",
										"balances": [
											{
												"available": {
													"value": "0.00"
												}
											}
										]
									},
									"amount": {
										"creditDebit": "CREDIT",
										"currency": "AUD",
										"value": "29.00"
									},
									"state": "FAILED",
									"failure": [
										"Account is closed"
									],
									"tracingId": "trace ac 29"
								}
							},
							{
								"node": {
									"narrative": "ref 20",
									"account": {
										"accountNumber": "173358181",
										"balances": [
											{
												"available": {
													"value": "47.01"
												}
											}
										]
									},
									"amount": {
										"creditDebit": "CREDIT",
										"currency": "AUD",
										"value": "20.00"
									},
									"state": "SUCCEEDED",
									"failure": null,
									"tracingId": "trace 20"
								}
							}
						]
					}
				}
			}
		}
	}
}
```

**Response Fields**

The following table explains the structure and meaning of each field in the response:

| Field | Type | Description |
|-------|------|-------------|
| data.node | INTERFACE | The entity containing information about the command |
| data.node.action | SCALAR! | The operation type of the command, "DO-ENCRYPTED-COMMAND" |
| data.node.id | SCALAR! | The unique identifier of the command |
| data.node.state | ENUM! | The current state of the encryption command, "SUCCESSFUL" |
| data.node.user | SCALAR! | The user who initiated the command, "SJTRADING" |
| data.node.unencryptedCommand | INTERFACE | Contains nested command in the encrypted payload|
| unencryptedCommand.action | SCALAR! | The specific action of the unencrypted command, "AGGREGATE-PAYMENT-EXECUTE" |
| unencryptedCommand.id | SCALAR! | The unique identifier of the unencrypted command |
| unencryptedCommand.state | ENUM! | The current state of the encryption command, "SUCCESSFUL" |
| unencryptedCommand.invalid | OBJECT! | List of any invalid fields or errors (empty in this case) |
| unencryptedCommand.aggregatePayment | OBJECT | Contains the business process node of the aggregated payment |
| aggregatePayment.count | SCALAR | The total number of instructions in the payment, 2 |
| aggregatePayment.successfulCount | SCALAR | The number of successful instructions, 1 |
| aggregatePayment.failedCount | SCALAR | The number of failed instructions, 1 |
| aggregatePayment.totalAmount.value | SCALAR! | The total amount of the aggregate payment, here "49.00" |
| aggregatePayment.totalAmountSuccessful.value | SCALAR! | The total amount of successful transactions, here "20.00" |
| aggregatePayment.totalAmountFailed.value | SCALAR! | The total amount of failed transactions, here "29.00" |
| aggregatePayment.customerTransactionReference | SCALAR | Customer's reference for the transaction, here "ct ref closed 49" |
| aggregatePayment.paymentRequestState | ENUM | The state of the payment request, here "COMPLETED" |
| aggregatePayment.instructions | OBJECT | Contains the list of individual payment instructions |
| instructions.edges[].node | INTERFACE | Individual instruction details |
| instructions.edges[].node.narrative | SCALAR | Description or reference for the instruction |
| instructions.edges[].node.account | OBJECT | Account details for the instruction |
| instructions.edges[].node.account.accountNumber | SCALAR | The account number for the instruction |
| instructions.edges[].node.account.balances | Array | List of balance information for the account |
| instructions.edges[].node.account.balances[].available.value | String | Available balance in the account |
| instructions.edges[].node.amount | OBJECT | Details of the instruction amount |
| instructions.edges[].node.amount.creditDebit | ENUM! | Indicates if it's a credit or debit, "CREDIT" |
| instructions.edges[].node.amount.currency | SCALAR! | The currency of the transaction, "AUD" |
| instructions.edges[].node.amount.value | SCALAR! | The amount of the individual instruction |
| instructions.edges[].node.state | ENUM | Current state of the instruction, "SUCCEEDED" |
| instructions.edges[].node.failure | SCALAR | Reason for failure if the instruction failed, null if succeeded |
| instructions.edges[].node.tracingId | SCALAR | Unique identifier for the instruction |


---

Disaggregated payment (CLA to CLI)

Payments

---
layout: detail
title: ANZ cash management central (ACMC) APIs
menu_key: acmc
group: acmc
hero_key: acmc
---

---

ANZ Cash Management Central (ACMC) is a comprehensive API platform designed to streamline cash management operations for businesses. It provides secure and efficient access to various financial services such as account management, payment initiation, and transaction monitoring, enabling businesses to automate and Optimise their cash flow processes.

[Capabilities](#capabilities) 

<h4 name="capabilities" id="capabilities"></h4>

#### Capabilities:

- **Account Management:** Retrieve and manage account details, including balance inquiries, transaction histories, and account updates.

- **Payment Initiation:** Support for various payment types including OSKO, DE and RTGS, allowing businesses to initiate payments directly through the API.

- **Real-time Data Insights:** Real-time tracking of transactions, including payment statuses and notifications, helping businesses maintain visibility and control over their financial operations.

- **Client and Party Management:** Manage clients and parties involved in transactions, ensuring smooth processing and compliance with regulatory requirements.

- **Allocation Process:** Allocate funds and manage allocations efficiently, ensuring optimal use of available resources.

[Technical requirements](#requirements) 

<h4 name="requirements" id="requirements"></h4>

#### Technical Requirements:

- **Authentication:** All API requests require OAuth 2.0 authentication using the Client Credential Grant flow. A bearer token must be obtained via the `/v2.0/auth` endpoint and included in the authorisation header of subsequent requests.

- **API Key:** Include an API key in the header of each request using the `apikey` parameter for additional authorisation.

- **Endpoints:** Direct all API calls to the `/graphql` endpoint for executing GraphQL queries and mutations. Utilize the appropriate endpoint for the environment:
  - UAT: `https://api.acmc.uat.anzgcis.com`
  - Production: `https://api.acmc.anzgcis.com`

[Key features for developers](#developers) 

<h4 name="developers" id="developers"></h4>

#### Key Features for Developers:

- **GraphQL API:** ACMC leverages GraphQL, allowing developers to request exactly the data they need, reducing payload size and improving efficiency.

- **Flexible Queries:** Easily query and manipulate data using GraphQL, supporting complex queries and mutations for various cash management operations.

- **Error Handling:** Comprehensive error handling with detailed HTTP status codes and error messages to guide troubleshooting and integration.

- **Secure Access:** Utilizes industry-standard OAuth 2.0 for secure authentication and authorisation, ensuring that sensitive financial data is protected.

- **Extensive Documentation:** Detailed API documentation with examples and best practices, helping developers quickly integrate and utilize the ACMC services.


By integrating with ACMC, developers can automate and enhance cash management processes, providing businesses with a powerful tool to manage their financial operations more effectively.

---

Real-time notification API