KYC – Upload Documents

This web service enables you to upload KYC/KYB documents to a HiPay user account.

Sent KYC/KYB documents are automatically processed in real time if the documents provided are usable. Otherwise, a manual review is performed within 72 hours (working days). If a document is uploaded and sent by mistake, please wait until it is refused to re-submit the right document.

Please note that all the information collected will be kept confidential and will not be disclosed to third parties, except as provided by the law.

Document constraints  

      • Accepted formats: JPG, GIF, PDF, PNG
      • Maximum file size: 15 MB
      • A certified translation is required for documents in a non-Latin language

Service endpoints  

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

Stagehttps://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.

Types of KYC/KYB

Individual accounts  

Type

Label

Description

1

ID proof

A copy of front and back sides of a valid identification document

(ID card or passport) of the account holder (person)

2

Proof of address

Proof of address issued within the last 3 months

(e.g.: utility/phone bill, rent receipt)

 

Professional accounts (corporations)  

Type

Label

Description

1

ID proof

A copy of front and back sides of a valid identification document

(ID card or passport) of the legal representative

4

Company Registration

Certificate of incorporation (document certifying Company registration) issued within the last 3 months (Kbis extract or any equivalent document)

5

Distribution of power

Signed Articles of Association with the division of powers (featuring the address of the head office, the name of the company and the name of the legal representative)

Professional accounts (persons)  

Type

Label

Description

1

ID proof

A copy of front and back sides of a valid identification document

(ID card or passport) of the individual

8

Company Registration

Registration number with the Registry of Companies (SIREN number or its equivalent)

 

Association accounts  

Type

Label

Description

1

ID proof

A copy of front and back sides of a valid identification document

(ID card or passport) of the legal representative

11

President of association

Document certifying the function and the name of the legal representative of the association

12

Official Journal

Publication in the dedicated register (or equivalent) or a receipt of the registration of the association issued by public authorities

13

Association status

A copy of the association statutes

 

Please note: Professional (corporations) and association accounts also require a document entitled “Identification of Ultimate Beneficial Owners”, duly completed, signed and accompanied by supporting identification documents of beneficial owners (to be sent through https://professional.hipay.com/login: to access this platform, please contact your HiPay account manager).

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 upload the KYC/KYB documents

php-auth-subaccount-login

AN

255

C

Email login of the HiPay account for which to upload the KYC/KYB documents

 

Request parameters  

Field name

Format

Length

Req.

Description

type

N

12

M

Type of KYC/KYB document (please see here for a detailed description)

file

AN

255

M

KYC/KYB document to upload

– Accepted formats:

JPG, GIF, PDF, PNG

– Maximum file size: 15 MB

back

AN

255

C

Back side of the identification document to upload

– Accepted formats:

JPG, GIF, PDF, PNG

– Maximum file size: 15 MB

validity_date

D

10

C

Document expiry date

(YYYY-MM-DD format)

– Mandatory for identification documents (type 1) 

– Optional for other KYC/KYB documents

curl -v -X POST
https://professional.hipay.com/api/identification.json
-u "XX12xxab000b00ab0101010abcd0a0xx:abc0abcd1ee1ff6789abc2345fff0000"
-H "php-auth-subaccount-id: 543210"
-F "file=@/home/johndoe/Desktop/Projects/uploads/DSCF1131.jpg"
-F "type=1" 
-F "validity_date=2025-05-17"
define('API_ENDPOINT', 'https://professional.hipay.com/api/identification');
define('API_USERNAME', 'XX12xxab000b00ab0101010abcd0a0xx');
define('API_PASSWORD', 'abc0abcd1ee1ff6789abc2345fff0000');
$credentials = API_USERNAME . ':' . API_PASSWORD;
 
$resource = API_ENDPOINT;
 
// create a new cURL resource
$curl = curl_init();
 
// request headers
$header = array(
  'Accept: application/json',
  'php-auth-subaccount-id: 543210
);
// request parameters
$data = array(
  'type' => 1,
  'validity_date' => '2025-05-17',
  'file' => '@/home/johndoe/desktop/Projects/uploads/DSCF1131.jpg'
);
 
// 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 => true,
  CURLOPT_POSTFIELDS => $data
);
 
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 examples

Example of an ok response

When the document upload is successful:
{ 
   "code":0, 
   "message":"Document uploaded", 
   "user_space":012345, 
   "type":1 
}

When validation failed:
{ 
  "code": 400, 
  "message": "Validation Failed", 
  "errors": [ 
    { 
      "field": "type", 
      "message": "This value should not be blank." 
    }, 
    { 
      "field": "file", 
      "message": "This value should not be blank." 
    } 
  ] 
}

When the account is not allowed (identity theft):
{ 
  "code": 403, 
  "message": "This account is not allowed to use this webservice for the user space 012345" 
}

When the user space has already been identified:
{ 
  "code": 414, 
  "message": "User space 012345 already identified" 
}

When the document has already been validated or is pending validation:
{ 
  "code": 415, 
  "message": "A document of this type is already validated or waiting for validation. Please contact [email protected]."
}
<?xml version="1.0" encoding="UTF-8"?>
<result>
  <code>0</code>
  <message><![CDATA[Document uploaded]]></message>
  <user_space>012345</user_space>
  <type>1</type>
  <validity_date><![CDATA[2025-06-01]]></validity_date>
</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>

Example of a parameter error response

{
  "code":400,
  "message":"Validation Failed",
  "errors":[
    {
      "field":"validity_date",
      "message":"This value should not be blank"
    }
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<result>
  <code>400</code>
  <message><![CDATA[Validation Failed]]></message>
  <errors>
    <entry>
      <field><![CDATA[validity_date]]></field>
      <message><![CDATA[This value should not be blank]]></message>
    </entry>
  </errors>
</result>