Cloudcheck Akahu API1.0

Initiate

Initiates an Akahu session. You can optionally pass a name and address to this API call and we will verify these details based on the information received back from Akahu. If no name and address are provided in the request we will simply return the details received from Akahu and it will be up to you to verify.

Request

The details to be verified must be supplied as a JSON object, included in the POST as the data parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.

{
   "reference": "Akahu reference 101",
   "name": {
      "given": "Jane",
      "middle": "Marie",
      "family": "Smith"
   },
   "address": {
      "street": "27 Indira Lane",
      "suburb": "Hillsborough",
      "city": "Christchurch",
      "postcode": "8022"
   },
   "callback": "https://www.mycompany.com/id-complete",
   "notificationUrl": "https://www.mycompany.com/id-notify?id=yourUniqueId",
   "webhookUrl": "https://www.mycompany.com/akahu-webhook",
   "verificationReference": "bac9d987-4007-4dd9-b5a6-cf547232836c"
}

The only mandatory field is the callback. This is the URL that you want to user to be redirected to once they have finished the Akahu process. You must include the protocol at the start of the URL (https:// or http://). 

We recommend that you also provide a unique reference and a notificationUrl.

A call will be made to the notificationUrl once the user completed the Akahu process, which can be used as a trigger in your code. This URL code should include a unique parameter that you can use to identify the request that it relates to. You must include the protocol at the start of the URL (https:// or http://). 

A call will be made to the webhookUrl whenever the Akahu request changes. The results API can then be called to fetch the current information for this request. You must include the protocol at the start of the URL (https:// or http://). We call this webhook using the POST method, passing a json payload that looks like this:

{
   "requestType": "AKAHU",
   "eventType": "STATUS_CHANGE",
   "reference": "<reference>"
}

where: <reference> is the reference or token used to fetch the results using an API call. Note that this webhook functionality may be extended in the future, e.g. different event types and fields may be added.

The name and address fields should be provided if you want us to verify these details. Without them, this API is simply a lookup service, returning the details of account holders and addresses associated with the bank account that the end user nominates.

Supply a verificationReference to link an existing verification to this Akahu request. A verification reference should be linked to a maximum of one Akahu request.

Response

The response JSON contains the outcome of the request.

{
   "result": "success",
   "link": "https://api.cloudcheck.co.nz/direct/akahu/punchout/?ref=bab9d987-4007-4dd9-b5a6-cf547232836c/",
   "token": "Dy0bG0ukM4d9bZKXP2l1HJEvfONPinV9jKRZKqFfjc3RQTQp"
}

If the call is successful you will receive a link that you redirect your end user to, in order for them to perform the Akahu process. A token is also returned, which is used by the other Cloudcheck Akahu APIs, to retrieve the results.

Once the Akahu process is completed, Cloudcheck will redirect the customer to the callback URL parameter provided in the request call above.

This call will include the following URL parameters:

Results

Using the token returned in the Akahu Initiate API, the reporting entity can retrieve the results of an Akahu request. Note that details entered by the customer can be retrieved for 7 days following a successful request. After this time, Cloudcheck disposes of all personal data, but the general process complete/pass/fail details remain available.

Response

{
   "status": "Pass",
   "validated": {
      "address": true,
      "name": true
   },
   "akahuReference": "zab9d987-4007-4dd9-b5a6-cf547232836c",
   "createdDate": "2021-03-06 12:02",
   "updatedDate": "2021-03-06 12:02",
   "verifiedDate": "2021-03-06 12:02",
   "ipAddress": "103.14.71.185",
   "message": "User declined to use this service",
   "details": {
      "reference": "Akahu reference 101",
      "callback": "https://www.mycompany.com/id-complete",
      "name": {
         "given": "Donald",
         "middle": "John",
         "family": "Trump"
      },
      "address": {
         "street": "123 Poplar Road",
         "suburb": "Anytown",
         "city": "Somewhereville",
         "postcode": "1234"
      }
   },
   "akahuDetails": {
      "bank": "Westpac",
      "accountNumber": "00-0000-00000-000",
      "holders": [
         {
            "given": "Donald",
            "family": "Trump",
            "full": "Donald Trump"
         }
      ],
      "addresses": [
         {
            "type": "RESIDENTIAL",
            "street": "123 Poplar Road",
            "suburb": "Anytown",
            "city": "Somewhereville",
            "postcode": "1234",
            "full": "123 Poplar Road, Anytown, Somewhereville 1234"
         }
      ]
   }
}

The status field can have the following values:

The validated field is returned when a name and/or address was passed to the Akahu Initiate API. It shows what was actually verified.

The details field contains the details that were passed in via the Akahu Initiate API request.

The akahuDetails field contains the details that were returned from Akahu.

Result PDF

Once the Akahu process is complete, you can optionally download a Cloudcheck generated PDF of the results.

Response

This method will either return a PDF file or a JSON object with an error message. You should check the response Content-Type to determine which you have received.

Review

Performs a review on an Akahu request.

When sending a review request to the Akahu API, you must include the following parameters as part of the call. Please note all these parameters must be included as form data, and not set into the POST body, which is not used. As such, the request should contain a Content-Type header of application/x-www-form-urlencoded.

Request

The decision and/or notes must be supplied as a JSON object, included in the POST as the data parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.

The akahuToken and reviewDecision are mandatory.

Response

The response JSON contains the akahuToken as well as a result element indicating whether the operation was successful.