Mandates are the authorisation resource to allow a merchant to transact on a customers bank account. A mandate is associated to a contract internally when the customer chooses debit order as their payment method or when a transaction has been locked to the debit order service. A mandate is required to be provided to a customer who then submits it to AddPay via a redirect link. The mandate is then validated through AddPay's Account Verification Services before it is marked as approved which in turn marks a contract as ACTIVE, these events occur behind the scenes and no interaction with the mandates API is required, however when an event occurs such as a mandate going though the verification process or a result being returned, an Event object will be fired to the merchant's defined notify_url if it has been defined - for contracted recurring transactions, it is required that the notify_url is configured otherwise the merchant will never be notified of these events.


A mandate is automatically generated and associated to a contract object (See Contract Object) when the customer visits and completes the payment link in the first transaction of a contract, once this is done, the full mandate object will be provided as a sub object of the contract.


The Mandate Object

Attributes

id
string
Universally unique identifier (UUID) per of the mandate object.

abbreviation
string
An internal abbreviation configured by AddPay which is used in third-party Account Verification Services and Corporate Payment Services. This number in conjunction with the reference will be displayed on customers bank statements in the format ABBREVIATION|REFERENCE.
reference
string
The reference that is inherited from the contract to which the mandate is associated.
url
string
The URL of the uploaded mandate document that the customer has filled in. This is populated by AddPay when the customer is redirected to the hosted Mandate Form.
bank_account
object
An object containing information on the bank account associated with the mandate. Returns false if the bank account is undefined.
bank_account[holder_type]
string
The account holder type, can only be one of:
SID – South African identity number
SBR – South African business / company registration number
SPP – South African passport
FPP – Foreign passport
bank_account[holder_id]
string
The bank account holder identity value, usually Identity number, but could be a registration number based off the holder_type.
bank_account[account_holder]
string
The bank account holder's full name or business registration number depending on the holder_type.
bank_account[account_number]
string
The bank account number.
bank_account[account_type]
string
The bank account type, can only be one of SAVINGS or CHEQUE.
bank_account[account_branch]
string
The bank account branch number.
verified
boolean
Returns a boolean value indicating whether the mandate contents have been verified successfully via Account Verification Services.
ip
string
Returns the IP address of the customer at the time of filling in the hosted Mandate Form.
confirmed
boolean
Returns a boolean value indicating whether the customer has confirmed the mandate signature via email or SMS code.
confirmed_at
timestamp/boolean
The timestamp that the customer confirmed the mandate via email or SMS code. Returns false if the mandate has not been confirmed.
created_at
timestamp
The timestamp at which the mandate object was created.