PayTo Agreement / Mandate
Create PayTo Agreement
The client is responsible for enabling their customers to create PayTo agreements as the Initiating Party.
Clients may implement features to support the creation of PayTo agreements by the Initiating Party in mobile or online applications, and/or via non-digital channels (such as a form).
- The Initiating Party provides the details for a new PayTo agreement to Shaype
- Shaype validates the agreement: the service checks that the Debtor bank is NPP reachable, and supports the PayTo scheme
- Shaype’s response to the client includes whether the agreement is valid, plus
- it includes other “enrichment” data such as resolving the PayID (if one is used).
- Shaype then generates and sends a Mandate Creation Request message to the NPP PayTo Mandate Management Service (MMS).
- Mandate Creation Request messages: must have a priority (attended or unattended), must have a frequency (ad-hoc, annual, monthly etc), must have an agreement type (Fixed, Variable, Usage, Balloon, Usage+, Variable+, Fixed+), may have a business expiry date/time (an expiry date/time is not mandatory).
- The MMS creates a PayTo agreement record, and sends a notification to the Debtor Account Servicer.
- The Debtor Account Servicer receives notification that a PayTo agreement has been created where their customer’s account (or PayID) is named as the Debtor, and authorisation is required.
Sometime later...
-
The Debtor customer can view the agreement terms, and authorise (or decline) the agreement.
-
The Debtor Account Servicer sends the Debtor authorisation response to the MMS.
-
The MMS updates their PayTo agreement record with the Debtor’s response.
-
Shaype receives notification from the MMS that the agreement has been authorised (or not).
-
Shaype forwards the PayTo agreement authorisation response notification to the client.
What the customer sees - example PayTo Agreement flow as displayed in Payer Servicer end application (end customer banking app view)
Core flow for PayTo mandate creation and agreement
Key PayTo Agreement Data Fields
NPPA has defined the PayTo agreement data fields as follows:
| Agreement Data Fields | Usage | Guidance |
|---|---|---|
| Mandate ID | Mandatory | The MMS allocates each PayTo agreement a unique ID. |
| Mandate Status | Mandatory | CREATED: Created ACTIVE: Active SUSPENDED: Suspended CANCELLED: Cancelled (Archived) |
| Mandate Description or Mandate Short Description | Conditional | Either the Mandate Description or Short Description must be provided. |
| Mandate Type | Mandatory | DDTP = Authorised Payment or Migrated DDR |
| Purpose | Mandatory | May be used for screening purposes.
MORTGAGE: Mortgage payments. UTILITY: Utility payments. LOAN: Loan payments. DEPENDANT: Dependant support payments. GAMBLING: Gambling payments. RETAIL: Retail payments. SALARY: Salary payments. PERSONAL: Personal payments. GOVERNMENT: Government payments. PENSION: Pension payments. TAX: Tax payments. OTHER: Other service payments. NOTE: The GOVERNMENT and TAX values are restricted to MPS Users that service government agencies. |
| Mandate Establishment Scheme | Mandatory | AUPM = Authorised Payment Mandate MGPIR = Migrated DDR Mandate |
| [Mandate Terms] | Mandatory | Fields include: Mandate Validity Start Date Mandate Validity End Date (optional) Automatic extension |
| Additional Information | Conditional | If BECS User ID in here, do not override. Append |
| [Initiating Party Details] | Mandatory | Fields include: Sponsor BIC Type Party ID Legal name = Trading name as would be recognised by the Debtor |
| [Payer Customer Details] | Varies, Conditional | Fields include: Debtor Party type (ORGANISATION or PERSON) Debtor Party ID Type Code Debtor Party ID Code Debtor Account or PayID (not both) Debtor Name Ultimate Debtor Name Account Servicer BIC, etc A Debtor PayID cannot be used when creating a Migrated DDR Mandate (NOTE: Migrated DDR Mandate not currently supported by Shaype) |
| [Creditor Details] | Varies, Conditional | Fields include: Creditor Party type (ORGANISATION or PERSON) Creditor Party ID Type Code Creditor Party ID Code Creditor Account or PayID (not both) Creditor Name Ultimate Creditor Name Account Servicer BIC, etc A Creditor PayID cannot be used when creating a Migrated DDR Mandate. (NOTE: Migrated DDR Mandate not currently supported by Shaype) |
| Priority | Mandatory | Priority (attended NORM / unattended UNAT) to be included in any generated notification. This value does not affect the priority for processing within the MMS. It may, depending on topic configuration, influence which topic any generated notification is sent to. NORM: Normal: Requires a real-time response UNAT: Unattended: Does not require a real-time response |
PayTo Agreement Payment Terms
NPPA has defined the PayTo agreement payment terms fields as:
| Mandate Data Fields | Usage | Guidance |
|---|---|---|
| Frequency | Mandatory | Expected frequency: ADHOC: Event takes place on request or as necessary. DAILY: Event takes place every day. FORTNIGHTLY: Event takes place every two weeks. INTRA_DAY: Event takes place several times a day. SEMI_ANNUAL: Event takes place every six months or two times a year. MONTHLY: Event takes place every month or once a month. QUARTERLY: Event takes place every three months or four times a year. WEEKLY: Event takes place once a week. ANNUAL: Event takes place every year or once a year. |
| Execute Not Before Time | Optional | Time of day after which payments may be initiated e.g. 2022-07-30 |
| Count per period, or Point in Time | Conditional | Only one of Count Per Period or Point In Time can be specified |
| Payment Amount Type | Mandatory | BALLOON: Payment amount is fixed with large final payment amount. FIXED: Payment amount is fixed. USAGE_BASED: Payment amount is based on usage. VARIABLE: Payment amount is variable. |
| Payment Amount | Conditional | Either actual amount or minimum amount |
| First Payment Amount | Optional | e.g. establishment fee |
| Last Payment Amount | Optional | e.g. pay-out amount |
| Maximum Payment Amount | Optional | Recommended for usage or variable types |
| First Payment Date | Optional | First date to expect payment request |
| Last Payment Date | Optional | Date to expect for final payment request |
Payment Amount Type = VARIABLE and USAGE_BASED are currently only available with Frequency = ADHOC
Types of PayTo Agreements
NPPA has defined PayTo Agreement types as:
| Agreement Type | Example usage scenarios |
|---|---|
| Fixed | Gym membership |
| Balloon | Car loan repayment |
| Variable | Online shopping account , utility bill |
| Usage+ | Corporate payroll (with multiple signatory authorisation) |
| Variable+ | Corporate supplier payment (with multiple signatory authorisation) |
| Fixed+ | Corporate one-off purchase (with multiple signatory authorisation) |
Recommended Way to Create Mandate
- Check if BSB supports PayTo?
- Before creating a mandate please check, if a target Payer supports PayTo?
API Reference: Check if BSB supports PayTo
- Before creating a mandate please check, if a target Payer supports PayTo?
- Create Mandate (POST/v1/payto/initiator/mandates)
- Create a mandate and send via MMS to Payer for authorisation.
API Reference: Create Mandate
- Create a mandate and send via MMS to Payer for authorisation.
- Receive notification:
- Platform will send webhook notification on mandate creation result. e.g
MandateCreateConfirmed
MandateCreateDeclined
- Platform will send webhook notification on mandate creation result. e.g
View details of a PayTo Agreement
The client is responsible for ensuring that the Initiating Party is able to view their PayTo agreements.
- NPPA does not prescribe how PayTo agreement details are presented to the Initiating Party.
- The Initiating Party could view their PayTo agreements in the client’s mobile or online app, and/or via non-digital channels (e.g. for non-digitally enabled customers).
- The Initiating Party must be able to view all their PayTo agreements.
- At any time, the Payment Initiator (client) systems must be able to request the latest details from the MMS for the Initiating Party’s agreements (by sending a query to Shaype).
- Shaype provides the client with the latest PayTo agreement records and pending requests from the MMS.
Modifying a PayTo Agreement
Mandate Status Change
Shaype provides the ability to change the status of a Mandate by forwarding a change made by the Initiating Party to the MMS.
- Cancel
- Suspend
- Release (un-suspend)
The Initiating Party can only release an agreement if they were the one that suspended the agreement.
Amend Mandate
Shaype provides clients with a Mandate Amendment API which must be used to send amendments made by the Initiating Party to the MMS. Shaype forwards the amendment to the MMS.
The change message must contain either unilateral changes or bilateral changes (not both)
- Bilateral change: Changing the payment terms is a bilateral change (requiring Debtor authorisation). If the change is declined by the Debtor (or it expires) the current agreement terms remain active and the change is archived.
- Unilateral change: Changing the Initiating Party name, agreement description and/or Creditor account/PayID are unilateral changes.
See table below for the types of operations possible as amends:
| Unilateral Amendment | Bilateral Amendment | Not Allowed |
|---|---|---|
| Creditor's name | Payment frequency | Payer Customer's Name and ID |
| Creditor's identifying details (e.g. ABN) Bank account details (including Alias) | The type of payment (Fixed, Variable) | Payer Customer Account Details Mandate Purpose |
| Creditor Reference | Maximum (capped) amount permitted | |
| Mandate description | Fixed amount | |
| The Mandate's end date |
Character Set Encoding - To comply with industry standard it is required to use Unicode character set
encoded with UTF-8. Any messages containing non-compliant characters will result in a reject mandate.
Recall a pending Mandate Amendment Request
The Initiating Party can recall a pending Mandate Amendment Authorisation Request (i.e. if the amendment is bilateral). Shaype sends the recall request to the MMS.
Migrating a PayTo Agreement
The PayTo MMS from NPP supports the ability to migrate a Direct Debit agreement to a PayTo agreement. Currently Shaype does not support this out-of-the-box, instead we recommend cancelling the Direct Debit and creating a new PayTo agreement with the same terms. This also allows a customer the opportunity to review the terms, given the faster processing of payments with PayTo, and ensure the agreement still fits their needs.
Updated about 9 hours ago