Pay-To API Code Catalogue

Overview:

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:

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

PayTo Flow Diagram:

sequenceDiagram participant Customer participant API Gateway participant Fileactive participant Webhook %% Authentication Flow Customer->>API Gateway: POST /auth (OAuth) API Gateway->>Customer: 200 OK (Token) %% Agreement Management Customer->>API Gateway: Create/authorise/Amend Agreement API Gateway->>Fileactive: Forward Agreement Request Fileactive-->>API Gateway: Agreement Response API Gateway-->>Customer: Agreement Confirmation Fileactive-->>Webhook: Agreement Outcome %% Payment Initiation Customer->>API Gateway: Initiate Payment API Gateway->>Fileactive: Forward Payment Request Fileactive-->>API Gateway: Payment Confirmation API Gateway-->>Customer: Payment Confirmation Fileactive-->>Webhook: Payment Outcome %% Status Checks Customer->>API Gateway: Check Payment/Agreement Status API Gateway->>Fileactive: Get Status Fileactive-->>API Gateway: Status Details API Gateway-->>Customer: Status Response

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

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)

Regular Expression posted as a sample to preserve REGEX formatting

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?)$
ABN - AUSTRALIAN BUSINESS NUMBER ^((\d{9})|(\d{11}))$
ORGN - ORGANISATION ID ^[!-@[-~][ -@[-~]{0,254}[!-@[-~]$

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:

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