Know Your Customer (KYC) Webhooks

Overview

Prime Trust provides Know Your Customer (KYC) validation for Contacts associated with individual Accounts. This guide provides information on using webhooks and the API to:

  • receive notifications for status change on:
    • Customer Identification Procedures (CIP),
    • Anti-Money Laundering (AML),
    • Document Check
  • retrieve status for CIP, AML, and Document Check using the API
  • retrieve information for next steps required to complete validation on submitted KYC requests

Key terms

Webhook - a webhook is a mechanism that sends event notifications (in this case from Prime Trust) in the form of a payload to a given resource provided by a subscriber (the integrator).

Status checks and webhooks

KYC webhooks will notify you on updates to CIP, AML, and Document Check status. After a change in status, the webhook sends a payload with a status update notification. The changesarray will list one value, “status”, to indicate a status change.

Example CIP status payload:

{
"type": "webhooks",
"id": "d1cff606-15c0-457f-a808-836ea099bd47",
"attributes": {
"action": "create",
"created-at": "2021-05-26T13:17:59Z",
"data": {
"changes": [
"status"
]
},
"failures": 0,
"last-request-at": null,
"last-response-code": null,
"resource-id": "e02b4f3b-aae9-4a2b-8ac3-695a9bc4062b",
"resource-type": "cip_checks",
"success": false
}
}

Example Document Check status payload:

{
"type": "webhooks",
"id": "30d80087-6f8c-48ad-9810-ba708caccd71",
"attributes": {
"action": "update",
"created-at": "2021-05-26T13:26:32Z",
"data": {
"changes": [
"status"
]
},
"failures": 0,
"last-request-at": null,
"last-response-code": null,
"resource-id": "a8036745-818f-4439-83bb-48bd37e9b510",
"resource-type": "kyc_document_checks",
"success": false
}
}

After receiving a status change webhook payload, you can then call the following endpoints to retrieve status information.

GET v2/cip-checks

Example response:

{
"type": "cip-checks",
"id": "f124d92c-3f1b-4c22-9772-ad01450f8cee",
"attributes": {
"created-at": "2021-05-14T15:32:24Z",
"exceptions": [
],
"exception-details": null,
"status": "NOTE: can be approved, pending, or denied",
"updated-at": "2021-05-14T16:38:16Z",
"submit-for-review": false
}
}

GET v2/aml-checks

Example response:

{
"type": "aml_checks",
"id": "f124d92c-3f1b-4c22-9772-ad01450f8cee",
"attributes": {
"created-at": "2021-05-14T15:32:24Z",
"exceptions": [
],
"exception-details": null,
"status": "NOTE: can be approved, pending, or denied",
"updated-at": "2021-05-14T16:38:16Z",
"submit-for-review": false
}
}

GET /kyc_document_checks

Example response:

{
"type": "kyc_document_checks",
"id": "f124d92c-3f1b-4c22-9772-ad01450f8cee",
"attributes": {
"created-at": "2021-05-14T15:32:24Z",
"exceptions": [
],
"exception-details": null,
"status": "approved", --- Can be pending / denied
"updated-at": "2021-05-14T16:38:16Z",
"submit-for-review": false
}
}

After encountering a KYC validation issue or the acceptance of KYC validation upon the creation or updating of a Contact, the webhook sends a payload with a code that indicates the required actions for an incomplete KYC validation.

Example payload with KYC required actions:

{
"type": "webhooks",
"id": "85f996c1-365f-40cb-bf36-ad83e189d519",
"attributes": {
"action": "update",
"created-at": "2021-05-10T13:27:04Z",
"data": {
"kyc-required-actions:": {
"N01": "Please verify the individual’s name for accuracy, confirming it reflects the legal name as it reads on the identity document. If the identity document does not reflect the legal name change, provide a legal document that authorizes a name change such as Marriage Certificate, divorce decree, or name change affidavit.",
"N10": "Please provide a valid Government issued ID, Driver's License or Passport for validation, there may have been an error with the document provided please make sure that it is not expired, the image of the ID is clear, there is no glare or flash, and all four corners are visible."
}
},
"failures": 0,
"last-request-at": null,
"last-response-code": null,
"resource-id": "f62f3f91-89e6-4522-be1e-d9b1db2fd4ec",
"resource-type": "contact",
"success": false
}
}

In the payload, the kyc-required-actions array contains a list of codes with required actions information.

Example success payload:

{
"type": "webhooks",
"id": "b85d6405-e27e-4c22-97e8-edcb8c538e9d",
"attributes": {
"action": "update",
"created-at": "2021-04-12T07:03:39Z",
"data": {
"changes": [
"cip-cleared",
"aml-cleared",
"identity-confirmed"
]
},
"failures": 0,
"last-request-at": null,
"last-response-code": null,
"resource-id": "9dfcfa15-0773-47b0-a064-ba944e378b74",
"resource-type": "contacts",
"success": false
}
}

In this example, the changes array returns the following values indicating success:

  • cip-cleared
  • aml-cleared
  • identity-confirmed

Error code / required actions reference

CodeRequired Actions
N01Please verify the individual’s name for accuracy, confirming it reflects the legal name as it reads on the identity document. If the identity document does not reflect the legal name change, provide a legal document that authorizes a name change such as Marriage Certificate, divorce decree, or name change affidavit.
N02Please verify the legal entity name for accuracy, confirming it matches the information with the Secretary of State and contains the company type i.e., LLC, Inc., LLP, etc.
N03Please review the Date of Birth for accuracy, confirming the date is entered in the standard format: MM/DD/YYYY and matches the date on the individual's identity document.
N04Please review the SSN/TIN for accuracy, confirming it is a valid number associated with the individual. If applicable, update the SSN/TIN and provide a copy of the social security card or SS4 Form.
N05Please review the EIN, GIIN, or Company Number for accuracy, confirming it is a valid number associated with the entity. If applicable, provide an SS-4, W-8BEN-E etc.
N06Please review the address for accuracy, confirming the street, city, state, and/or ZIP code are associated with the individual's residential address. PO Box and mail receiving agencies are not accepted; Army Post Office boxes (APO) or Fleet Post Office (FPO) are the exception. If applicable, please provide proof of address (mail item) dated within the last 90 days (e.g., Monthly Bill Statement, Bank/Credit Card Account Statement, Rental Lease Agreement, Vehicle Registration, Copy of Real Estate Property Title or Property Tax Bill).
N07Please review the company address for accuracy, confirming it is the physical, principal place of business either reflected within the company formation documents or Secretary of State. Mailbox addresses, PO Boxes, and registered agent addresses are not allowed. If applicable, provide proof of address (mail item) dated within the last 90 days (e.g., Monthly Bill Statement, Bank/Credit Card Account Statement, Rental Lease Agreement, Vehicle Registration, Copy of Real Estate Property Title or Property Tax Bill).
N08Please provide the Company’s official formation or organizational documentation evidencing the entity's existence (e.g., Certificate of Good Standing).
N09Please provide proof of Beneficial Ownership. Evidence of Beneficial Ownership may be reflected in a company's Operating Agreement, Bylaws, Articles of Incorporation, or Share Registry clearly reflecting ownership percentage or share capital.
N10Please provide a valid Government issued ID, Driver's License or Passport for validation, there may have been an error with the document provided please make sure that it is not expired, the image of the ID is clear, there is no glare or flash, and all four corners are visible.
Last updated on