Cloudcheck Credfin API

Initiate

Path	/credfin/initiate/	Method	POST

Initiates a Credfin 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 Credfin. If no name and address are provided in the request we will simply return the details received from Credfin and it will be up to you to verify.

Parameter	Required	Description
`key`	true	Your API Key.
`signature`	true	An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature.
`nonce`	true	A single-use key generated for this request. Note that each nonce may only be used once for each access key.
`timestamp`	true	The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected.
`data`	true	A JSON string containing the details to be verified.

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.

Example

{
   "reference": "Credfin reference 101",
   "name": {
      "given": "Jane",
      "middle": "Marie",
      "family": "Smith"
   },
   "address": {
      "street": "27 Indira Lane",
      "city": "Redfern",
      "state": "NSW",
      "postcode": "2022"
   },
   "callback": "https://www.mycompany.com/id-complete",
   "notificationUrl": "https://www.mycompany.com/id-notify?id=yourUniqueId",
   "webhookUrl": "https://www.mycompany.com/credfin-webhook"
   "verificationReference": "dac9d987-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 Credfin 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 Credfin 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 Credfin 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": "CREDFIN",
"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(s) that the end user nominates.

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

Response

The response JSON contains the outcome of the request.

Example

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

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

Once the Credfin 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:

Parameter	Required	Description
`token`	Yes	A token used to retrieve results of the Credfin request.
`credfinReference`	Yes	A unique reference used to identify the request.

Results

Path	/credfin/result/	Method	GET

Using the token returned in the Credfin Initiate API, the reporting entity can retrieve the results of an Credfin 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.

Parameter	Required	Description
`key`	true	Your API Key.
`signature`	true	An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature.
`nonce`	true	A single-use key generated for this request. Note that each nonce may only be used once for each access key.
`timestamp`	true	The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected.
`token`	true	The token returned in the response to the Credfin Initiate API.

Response

Example

{
"status": "Pass",
"validated": {
"address": true,
"name": true
},
"credfinReference": "zab9d987-4007-4dd9-b5a6-xf547232836c",
"createdDate": "2021-03-06 12:02",
"updatedDate": "2021-03-06 12:02",
"verifiedDate": "2021-03-06 12:02",
"ipAddress": "103.14.71.185",
"details": {
"reference": "Credfin reference 101",
"callback": "https://www.mycompany.com/id-complete",
"notificationUrl": "https://www.mycompany.com/id-notify?id=yourUniqueId",
"name": {
"given": "Donald",
"middle": "John",
"family": "Trump"
},
"address": {
"street": "123 Poplar Road",
"city": "Somewhereville",
"state": "QLD",
"postcode": "1234"
}
},
"credfinDetails": {
"bank": "Westpac",
"accounts": [
{
"bsb": "064123",
"accountNumber": "00000001",
"owners": [
{
"fullName": "Donald John Trump"
}
],
"addresses": [
{
"streetNumber": "123",
"streetName": "Poplar Road",
"townSuburb": "Somewhereville",
"state": "QLD",
"postcode": "1234",
"country": "Australia",
"full": "123 Poplar Road, Somewhereville, QLD 1234"
}
]
}
]
}
}

The status field can have the following values:

Status	Description
Pending	The end user has not completed the Credfin process.
Complete	The end user has completed the Credfin process. Name and address information were not provided in the Credfin Initiate request, therefore no verification was performed.
Pass	We successfully verified the end users name and/or address.
Fail	We failed to verify the end users name and/or address.
Review	We received a review status from Credfin .
Timed out	We timed out when retreiving the account details from Credfin .
Error	An error occurred in the Credfin process.
Declined	The end user declined to use the Credfin process.
Expired	The end user did not complete the Credfin process within 20 minutes.

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

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

The credfinDetails field contains the details that were returned from Credfin .

Result PDF

Path	/credfin/pdf/	Method	GET

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

Parameter	Required	Description
`key`	true	Your API Key.
`signature`	true	An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature.
`nonce`	true	A single-use key generated for this request. Note that each nonce may only be used once for each access key.
`timestamp`	true	The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected.
`token`	true	The token returned in the response to the Credfin Initiate API.

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

Path	/credfin/review/	Method	POST

Performs a review on a Credfin request.

When sending a review request to the Credfin 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.

Parameter	Required	Description
`key`	true	Your API Key.
`signature`	true	An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature.
`nonce`	true	A single-use key generated for this request. Note that each nonce may only be used once for each access key.
`timestamp`	true	The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected.
`data`	true	A JSON string containing the details to be verified.

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 credfinToken and reviewDecision are mandatory.

Example

{
"credfinToken": "By0bG0ukM4d1bZK1P2l1HJEvfONPinV9jKRZKqFfjc3RQTQp",
"reviewDecision": "ACCEPT",
"reviewNotes": "The address is formatted differently but is the same."
}

Response

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

Example

{
"credfin": {
"credfinToken": "fab9d287-4007-4dd9-b5a6-cf547232836c",
"result": "success"
}
}

Cloudcheck Credfin API1.0

Core

APIs

Overview

Initiate

Request

Example

Response

Example

Results

Response

Example

Result PDF

Response

Review

Request

Example

Response

Example

Solutions

Industries

About

Contact