KYC – Request Status

This web service enables you to request the list of sent KYC/KYB documents as well as their status.

Service endpoints  

There are two endpoints (base URLs) to which you can make your API calls.

Stage: https://test-professional.hipay.com/api/identification {format} (POST)

Production: https://professional.hipay.com/api/identification {format} (POST)

Format  

JSON | XML

The format is not mandatory, but you can choose the format of the received response. By default, the response is in JSON format.

Authentication  

This web service requires a basic HTTP authentication, with the HiPay technical account wsLogin and wsPassword.

Request header  

You may use the Account ID or the Account email login to select an account different from the authenticated one.

Field name

Format

Length

Req

Description

php-auth-subaccount-id

N

12

C

Account ID of the HiPay account for which to request the list of sent KYC/KYB documents and their status

php-auth-subaccount-login

AN

255

C

Email login of the HiPay account for which to request the list of sent KYC/KYB documents and their status

curl -v -X GET
https://professional.hipay.com/api/identification.json
-u "XX12xxab000b00ab0101010abcd0a0xx:abc0abcd1ee1ff6789abc2345fff0000"
-H "php-auth-subaccount-id: 543210"
define('API_ENDPOINT', 'https://professional.hipay.com/api/identification.json');
define('API_USERNAME', 'XX12xxab000b00ab0101010abcd0a0xx');
define('API_PASSWORD', 'abc0abcd1ee1ff6789abc2345fff0000');
$credentials = API_USERNAME . ':' . API_PASSWORD;
 
$reso
);urce = API_ENDPOINT;
 
// create a new cURL resource
$curl = curl_init();
 
// header parameters
$header = array(
  'Accept: application/json',
  'php-auth-subaccount-id: 543210
);
 
// set appropriate options
$options = array(
  CURLOPT_URL => $resource,
  CURLOPT_HTTPHEADER => $header,
  CURLOPT_USERPWD => $credentials,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_FAILONERROR => false,
  CURLOPT_HEADER => false,
  CURLOPT_POST => false,
 
foreach ($options as $option => $value) {
  curl_setopt($curl, $option, $value);
}
 
// execute the given cURL session
if (false === ($result = curl_exec($curl))) {
  throw new RuntimeException(curl_error($curl), curl_errno($curl));
}
 
$status = (int)curl_getinfo($curl, CURLINFO_HTTP_CODE);
$response = json_decode($result);
 
var_dump($response);
 
curl_close($curl);

Response fields  

Field name

Description

code

Indicates if the API call has been done without errors (0 = success)

message

Displays the message related to the code

user_space

ID of the user space being verified 

– Deprecated: will be removed soon

identification_status

User space identification status

– Unidentified: the user space is not identified, documents are missing

– Identified

– Identification in progress: a manual review is being performed to identify the user space

documents

All the required KYC/KYB documents for this user space:

– type: please see here for a detailed description

– label: please see here for a detailed description

– status_code: please see table 15 for a detailed description

– status_label: please see table 15 for a detailed description

Status codes and status labels  

status_code

status_label

Description

-1

NA

No document has been uploaded

1

Waiting

The document has been sent to HiPay

2

Validated

The document has been validated for identification

3

Refused

The document has been refused because it is falsified, expired or inconsistent

5

Waiting

The document is being reviewed

8

Refused

The document has been refused

Response examples  

Example of an ok response

{
  "code": 0,
  "message": "Identification documents list succeeded",
  "user_space": 012345,
  "identification_status": "Identified",
  "documents": [
    {
      "type": 1,
      "label": "ID proof",
      "status_code": 2,
      "status_label": "Validated"
    },
    {
      "type": 4,
      "label": "Company Registration",
      "status_code": 2,
      "status_label": "Validated"
    },
    {
      "type": 5,
      "label": "Distribution of power",
      "status_code": 2,
      "status_label": "Validated"
    },
  ]
}
<?xml version="1.0" encoding="UTF-8" ?>
<result>
  <code>0</code>
  <message><!--[CDATA[Identification documents list succeeded]]--></message>
  <user_space>012345</user_space>
  <identification_status><!--[CDATA[Unidentified]]--></identification_status>
  <documents>
    <entry>
      <type>1</type>
      <label><!--[CDATA[Identity card]]--></label>
      <status_code>9</status_code>
      <status_label><!--[CDATA[Waiting]]--></status_label>
    </entry>
    <entry>
      <type>2</type>
      <label><!--[CDATA[Proof of address]]--></label>
      <status_code>9</status_code>
      <status_label><!--[CDATA[Waiting]]--></status_label>
    </entry>
  </documents>
</result>

<!-- If an error occurs, the API returns status code 4xx or 5xx, with a descriptive message. -->

Example of an authentication error response

{
  "code": 401,
  "message": "Authentication Failed."
}
<?xml version="1.0" encoding="UTF-8"?>
<result><code>401</code>
<message>Authentication Failed.</message>
</result>