The KYC Document object

You need to create document in order to upload pages on this document.

  1. The KYC Document Object is a request to validate a required document. There is one request for one Type of document
  2. Upload a file through a Page. A document should get several pages
  3. Edit the object Document and set the Status field to "VALIDATION_ASKED" (instead of "CREATED")
  4. The demand is received by our team. The object is waiting for a "VALIDATED" status

Note that you are not allowed to store KYC documents on your side unless you have permission from the approriate authorities in your country

Parameters

Id
string

string:

Maximum length is 255 characters

The item's ID

CreationDate
timestamp

timestamp

When the item was created

Tag
string

string:

Maximum length is 255 characters

Custom data that you can add to this item

UserId
string

string:

Maximum length is 255 characters

The object owner's UserId

Status
DocumentStatus

DocumentStatus:

CREATED, VALIDATION_ASKED, VALIDATED, REFUSED

The Status of the Document

The status of this KYC/Dispute document

RefusedReasonMessage
string

string:

Maximum length is 255 characters

The message accompanying a refusal

RefusedReasonType
KYCDocRefusedReasonType

KYCDocRefusedReasonType:

DOCUMENT_UNREADABLE, DOCUMENT_NOT_ACCEPTED, DOCUMENT_HAS_EXPIRED, DOCUMENT_INCOMPLETE, DOCUMENT_MISSING, DOCUMENT_DO_NOT_MATCH_USER_DATA, DOCUMENT_DO_NOT_MATCH_ACCOUNT_DATA, SPECIFIC_CASE, DOCUMENT_FALSIFIED, UNDERAGE_PERSON, OTHER, TRIGGER_PEPS, TRIGGER_SANCTIONS_LISTS, TRIGGER_INTERPOL

The type of refusal reason

The type of reason for refusal

ProcessedDate
timestamp

timestamp

The date when the document was processed by MANGOPAY

{
"Id": "8494514",
"CreationDate": 12926321,
"Tag": "custom meta",
"UserId": "8494514",
"Status": "CREATED",
"RefusedReasonMessage": "The document was not readable :-(",
"RefusedReasonType": "DOCUMENT_UNREADABLE",
"ProcessedDate": 1501675794
}

Create a KYC Document

Note that if you are sending several infos for the same document (eg the front and back of a document), you must send one KYC document which contains several pages since each document is processed independantly

POST .../v2.01/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/kyc/documents/

Parameters

Tag
string

string:

Maximum length is 255 characters

optional

Custom data that you can add to this item

Type
KYCDocumentType

KYCDocumentType:

IDENTITY_PROOF, REGISTRATION_PROOF, ARTICLES_OF_ASSOCIATION, SHAREHOLDER_DECLARATION, ADDRESS_PROOF

The type of KYC Document

required

Gives the type of the KYC document

  • View
  • Code
  • Run
  • View
  • Code
  • Run
POST .../users/:UserId/kyc/documents/ HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"Type": "IDENTITY_PROOF"
}
require_once("mangopay.php");

try {

$UserId = 8494514;

$KycDocument = new \MangoPay\KycDocument();
$KycDocument->Tag = "custom meta";
$KycDocument->Type = "IDENTITY_PROOF";

$Result = $Api->Users->CreateKycDocument($UserId, $KycDocument);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
POST .../users//kyc/documents/ HTTP/1.1
Body Parameters :
{
"Tag": "",
"Type": ""
}

Submit a KYC Document

PUT .../v2.01/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/kyc/documents/KYCDocumentId

Parameters

Tag
string

string:

Maximum length is 255 characters

optional

Custom data that you can add to this item

Status
DocumentStatus

DocumentStatus:

CREATED, VALIDATION_ASKED, VALIDATED, REFUSED

The Status of the Document

required

The status of this KYC/Dispute document

  • View
  • Code
  • Run
  • View
  • Code
  • Run
PUT .../users/:UserId/kyc/documents/:KYCDocumentId HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"Status": "VALIDATION_ASKED"
}
require_once("mangopay.php");

try {

$KycDocument = new \MangoPay\KycDocument();
$KycDocument->Tag = "custom meta";
$KycDocument->Status = "VALIDATION_ASKED";
$KycDocument->Id = 8494514;
$KycDocument->Id = 12639185;

$Result = $Api->Users->UpdateKycDocument($KycDocument);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
PUT .../users//kyc/documents/ HTTP/1.1
Body Parameters :
{
"Tag": "",
"Status": ""
}

View a KYC Document

GET .../v2.01/ClientId

The ID of your client account

/kyc/documents/KYCDocumentId/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
GET .../kyc/documents/:KYCDocumentId/ HTTP/1.1
require_once("mangopay.php");

try {

$KYCDocumentId = 12639185;

$KycDocument = $Api->Users->GetKycDocument($KYCDocumentId);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
GET .../kyc/documents// HTTP/1.1

Create a KYC Page

  • Documents have to be in "CREATED" Status
  • You can create as many pages as needed
  • Remember to change Status to "VALIDATION_ASKED" to submit KYC documents

The maximum size per page is about 7Mb (or 10Mb when base64encoded). The following formats are accepted for the documents : .pdf, .jpeg, .jpg, .gif and .png. The minimum size is 1Kb.

POST .../v2.01/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/kyc/documents/KYCDocumentId/pages/

Parameters

File
string

string:

Maximum length is 255 characters

required

The base64 encoded file which needs to be uploaded

You need to fill in only the binary code. Do not send the first part that some converters add into the binary code which is <img src=" data:image/png;base64..." />

  • View
  • Code
  • Run
  • View
  • Code
  • Run
POST .../users/:UserId/kyc/documents/:KYCDocumentId/pages/ HTTP/1.1
Body Parameters :
{
"File": "/9j/4AAQSkZJRgABAQEBLAEsAAD/2wBDAAEBAQEBAQEBAQEBAQECAgMCAgICAgQDAwIDBQQFBQUE BAQFBgcGBQUHBgQEBgkGBwgICAgIBQYJCgkICgcICAj/2wBDAQEBAQICAgQCAgQIBQQFCAgICAgI CAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAj/wgARCAAyADIDAREA AhEBAxEB/8QAGwAAAgMBAQEA"
}
require_once("mangopay.php");

try {

$UserId = 8494514;
$KYCDocumentId = 12639185;

$KycPage = new \MangoPay\KycPage();
$KycPage->File = "/9j/4AAQSkZJRgABAQEBLAEsAAD/2wBDAAEBAQEBAQEBAQEBAQECAgMCAgICAgQDAwIDBQQFBQUE BAQFBgcGBQUHBgQEBgkGBwgICAgIBQYJCgkICgcICAj/2wBDAQEBAQICAgQCAgQIBQQFCAgICAgI CAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAj/wgARCAAyADIDAREA AhEBAxEB/8QAGwAAAgMBAQEA";

$Result = $Api->Users->CreateKycPageFromFile($UserId, $KYCDocumentId, $KycPage);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
POST .../users//kyc/documents//pages/ HTTP/1.1
Body Parameters :
{
"File": ""
}

List KYC Documents for a User

GET .../v2.01/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/kyc/documents/

Get parameters

Page
int

int

optional

The page number of results you wish to return

Per_Page
int

int

optional

The number of results to return per page

Sort
ColumnAndDirection

ColumnAndDirection:

The column to sort against and direction, separated by a :

optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

BeforeDate
timestamp

timestamp

optional

To return only resources that have CreationDate BEFORE this date

AfterDate
timestamp

timestamp

optional

To return only resources that have CreationDate AFTER this date

Status
DocumentStatus

DocumentStatus:

CREATED, VALIDATION_ASKED, VALIDATED, REFUSED

The Status of the Document

optional

The status of this KYC/Dispute document

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../users/:UserId/kyc/documents/ HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC",
"BeforeDate": 1463440221,
"AfterDate": 1431817821,
"Status": "CREATED, SUCCEEDED"
}
GET .../users//kyc/documents/ HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": "",
"BeforeDate": ,
"AfterDate": ,
"Status": ""
}

List all KYC Documents

GET .../v2.01/ClientId

The ID of your client account

/kyc/documents/

Get parameters

Page
int

int

optional

The page number of results you wish to return

Per_Page
int

int

optional

The number of results to return per page

Sort
ColumnAndDirection

ColumnAndDirection:

The column to sort against and direction, separated by a :

optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

BeforeDate
timestamp

timestamp

optional

To return only resources that have CreationDate BEFORE this date

AfterDate
timestamp

timestamp

optional

To return only resources that have CreationDate AFTER this date

Status
DocumentStatus

DocumentStatus:

CREATED, VALIDATION_ASKED, VALIDATED, REFUSED

The Status of the Document

optional

The status of this KYC/Dispute document

Type
KYCDocumentType

KYCDocumentType:

IDENTITY_PROOF, REGISTRATION_PROOF, ARTICLES_OF_ASSOCIATION, SHAREHOLDER_DECLARATION, ADDRESS_PROOF

The type of KYC Document

optional

The Type of a given KYC Document

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../kyc/documents/ HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC",
"BeforeDate": 1463440221,
"AfterDate": 1431817821,
"Status": "CREATED, SUCCEEDED",
"Type": "IDENTITY_PROOF,ADDRESS_PROOF"
}
GET .../kyc/documents/ HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": "",
"BeforeDate": ,
"AfterDate": ,
"Status": "",
"Type": ""
}