Overview
The Cloudcheck Credfin API service enables you to send a secure link to your customers, allowing them to self-verify using the details extracted from one or more of their bank accounts using Credfin.
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"
}
}