The KYC Document object

The KYC Document Object is a container to store document pages in it. There is one KYC Document Object for one Type of document

The process to send a KYC document is divided into 3 parts.

• Step 1 : Creation of a KYC Document

• Step 2: Creation of KYC Pages within the document. A document can have several pages.

• Step 3: Submission of the KYC Document. You will have to edit the object Document and set the Status field to "VALIDATION_ASKED" (instead of "CREATED")

The documents will be validated by our compliance team. Please note that in the sandbox environment you will need to validate submitted KYC documents manually via the 'Sandbox operations' tab.

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

UserId
string

string:

Maximum length is 255 characters

The object owner's UserId

Status
DocumentStatus

DocumentStatus:

CREATED, VALIDATION_ASKED, VALIDATED, REFUSED, OUT_OF_DATE

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_FALSIFIED, UNDERAGE_PERSON, SPECIFIC_CASE

The type of refusal reason

The type of reason for refusal

ProcessedDate
timestamp

timestamp

The date when the document was processed by MANGOPAY

{
"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"
}
POST .../users//kyc/documents/ HTTP/1.1
Body Parameters :
{
"Tag": "",
"Type": ""
}

Create a KYC Page

  • Documents have to be in "CREATED" Status
  • You can create as many pages as needed
  • The API will return a 'Status : 204 No content' if the call is successful

Following formats are accepted for documents : .pdf, .jpeg, .jpg & .png. Note that minimum accepted size is 1KB for all documents except identity_proof only for which size must be above 32KB. For all documents, maximum size per page is about 7MB (or 10MB when base64 encoded).

Document Type Minimum size Maximum size (with base64 encoding) Reason
IDENTITY_PROOF 32KB 10MB In order to effectively assess whether documents are genuine or not we must receive good quality documents.

Guidelines for identity documents
ADDRESS_PROOF 1KB 10MB Such documents can be legit with a low size
REGISTRATION_PROOF 1KB 10MB Such documents can be legit with a low size
ARTICLES_OF_ASSOCIATION 1KB 10MB Such documents can be legit with a low size
SHAREHOLDER_DECLARATION 1KB 10MB Such documents can be legit with a low size
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:

base64 encoded file
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..." />

If you are using the SDK. Do not send an encoded file, you have to put a "raw" file and the SDK will encode it automatically.

  • View
  • Code
  • Run
  • View
  • Code
  • Run
POST .../users/:UserId/kyc/documents/:KYCDocumentId/pages/ HTTP/1.1
Body Parameters :
{
"File": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAADCwUlEQVR4nOy9d5hlV3Xm/Tvx5lQ5dKjOUR3U3co5ISRhG4FJ9hhsbPhsTJDBHnvGY489Y5MEtgFr7AFmDLbHYEACkbHAyrlbnUNVdVd3V75VdXM6+ftjn3u6OqolJEG77/s81aHq1r3n7LP32muv9a53SZ7nebTQQgsXJeSf9QW00EILPzu0DEALLVzEaBmAFlq4iNEyAC20cBG"
}
POST .../users//kyc/documents//pages/ HTTP/1.1
Body Parameters :
{
"File": ""
}

Submit a KYC Document

After submission, the object will be waiting to be VALIDATED.

Validation is on average completed within 24h at bank working days (Monday to Friday) by our legal compliance team.
If you wish to be notified in case of a change of status, you can setup hook notifications.

Remember to change Status to "VALIDATION_ASKED" to submit KYC documents.

PUT .../v2.01/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/kyc/documents/KYCDocumentId

Parameters

Status
DocumentStatus

DocumentStatus:

CREATED, VALIDATION_ASKED, VALIDATED, REFUSED, OUT_OF_DATE

The Status of the Document
required

The status of this KYC/Dispute document

  • View
  • Code
  • Run
    A demo is not available
  • View
  • Code
  • Run
    A demo is not available
PUT .../users/:UserId/kyc/documents/:KYCDocumentId HTTP/1.1
Body Parameters :
{
"Status": "VALIDATION_ASKED"
}

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
GET .../kyc/documents// HTTP/1.1

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

Status
DocumentStatus

DocumentStatus:

CREATED, VALIDATION_ASKED, VALIDATED, REFUSED, OUT_OF_DATE

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 :
{
"Status": "CREATED, SUCCEEDED"
}
GET .../users//kyc/documents/ HTTP/1.1
Get Parameters :
{
"Status": ""
}

List all KYC Documents

GET .../v2.01/ClientId

The ID of your client account

/kyc/documents/

Get parameters

Status
DocumentStatus

DocumentStatus:

CREATED, VALIDATION_ASKED, VALIDATED, REFUSED, OUT_OF_DATE

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 :
{
"Status": "CREATED, SUCCEEDED",
"Type": "IDENTITY_PROOF,ADDRESS_PROOF"
}
GET .../kyc/documents/ HTTP/1.1
Get Parameters :
{
"Status": "",
"Type": ""
}
Share feedback