Head Office User Guide

PURPOSE

This document is designed to offer advise on how to set up and advise Integrators on how to use Head Office level payers via API.

USAGE

Head Office Mode allows an integration to add payers to a Head Office account. These payers can then have transactions scheduled against them regardless of what Business the payer sits in.

The transaction is linked to a business but is processed under the Head Office business. This removes the requirement for a Payer to exist in both businesses, it can just be called from the Head Office.

A use case for this would be a Gym membership.

The Payer is a member of Gym A, the Scheduled monthly payment is transacting at Gym A.

But today is working out at Gym B, the Payer purchases a water bottle at Gym B.

As the Payer exists in the Head Office account, the purchase of the water bottle can be a saved card details transaction against the details saved at Head Office account level with the transaction registered against the Sub Business.

Login Auth

Head Office mode allows for use of a single set of API credentials to access multiple Sub Businesses. When authorising a request these must be used as below:

{{url-auth}}/login

{
"Username": "{{HO-Api Username}}",
"Password": "{{HO-Api User Key:}}"
}

Adding Payers and Payment Details

When calling the API call the integration must provide us the Head Office details for saving a Payer:
{{url}}/businesses/{{HO-business-id}}/payers

Payment details must also be added to the Payer at Head Office:
{{url}}/businesses/{{HO-business-id}}/payers/{{payer-reference}}/accounts/bank-account
{{url}}/businesses/{{HO-business-id}}/payers/{{payer-reference}}/accounts/card/token
{{url}}/businesses/{{HO-business-id}}/payers/{{payer-reference}}/accounts/card

Scheduling a Transaction

When Scheduling a transaction ScheduleSinglePayment must be used.

The integration must pass us the Head Office details and the Sub Business ID in the body of the request, as below:

{{url}}/businesses/{{HO-business-ID }}/payers/{{payer-reference}}/schedules/payments

{
     "Date": "2020-06-27",
     "Amount": 100.00,
     "Reference": "Scheduled-Payment-001",
     "Description": "This is the first scheduled payment",
     "SubBusinessId": {{Sub-business Id}},
     "Audit": {
     "Username": "Example-User",
     "UserIP": "127.0.0.1"
   }
}

Card Payments

When processing a real time card payment that needs to be linked to a Sub Business you can use Head Office details for the login, as previously mentioned, and provide the Sub Business ID in the URL of the request.

Note - you will need to use the Business Key of Sub Business to tokenise card

{{url}}/businesses/{{Sub Business-Id}}/transactions/card-payments

{
     "ProcessType": "COMPLETE",
     "Reference": "REAL-TIME-TXN-1001",
     "Description": "This is an example real-time transaction",
     "Amount": 100.25,
     "CurrencyCode": "AUD",
     "CardToken": "8854c380037544858cc6d56fee6983ec",
     "Payer": {
      "uniqueRefernce": "{{payer-reference}}"
     },
     "Audit": {
          "Username": "Example-User",
          "UserIP": "1.2.3.4"
   }
}

Saved Card Transaction

Processing a transaction using saved card details works in a similar was as Scheduling a single transaction. We use Head Office Business ID in the URL and the Sub Business ID in the body of the request, as below:

{{url}}//businesses/{{HO-business-ID }}/payers/{{payer-reference}}/transactions/card

{
     "ProcessType": "COMPLETE",
     "Reference": "Transaction-001",
     "Amount": 100.75,
     "SubBusinessId": {{Sub-business Id}},
     "Description": "This is a test transaction",
     "CurrencyCode": "AUD",
     "Audit": {
       "Username": "Example-User",
       "UserIP": "1.2.3.4"
   }
}