KYX Process

Overview

• All beneficiaries must be approved via our KYX process before they are able to use Caliza's services.
• Our KYX process uses the beneficiary information that you provided when creating the beneficiary combined with information provided directly by the beneficiary themselves in order to verify the identity of the beneficiary and ensure their suitability for our service.

KYC (For Individual Beneficiaries)

Acquiring Beneficiary ID and Selfie via Jumio

Upon the creation of a beneficiary, you will receive a BENEFICIARY_KYC webhook which will help with acquiring images (an ID and selfie) required for KYC via our partner Jumio. This process must be completed by each beneficiary. Once the beneficiary has completed the partner data acquisition step, we will receive the results and share them with you via webhook.

Using Jumio Website for Data Acquisition

You can share a link to the Jumio data acquisition website directly with your beneficiary. This link is found in the webhook at data.steps[].uploadLink.

Using Jumio SDK for Data Acquisition

You can use the Jumio SDK in order to conduct the data acquisition step directly within your mobile application. Here is a link to their SDKs: https://docs.jumio.com/production/Content/Integration/Integration%20Channels/Mobile%20SDKs.htm, and you will find the SDK token needed for each beneficiary at data.steps[].jumioSdk.token.

Regenerating Partner Tokens and Links

These partner links and tokens will last 24 hours and will be regenerated automatically 3 times and sent to you via webhook. After the 3rd expiration, if you would like an additional link or token, you can request one using the POST /v1/kyx-steps/{kyxStepId}/regenerate endpoint. The kyxStepId listed here can be seen in the webhook below at data.steps.id.

{
  "operation": "BENEFICIARY_KYC",
  "resourceId": "007192bc-f1fd-4c8a-bc3a-0c6a8e3336a8",
  "createdAt": "2023-06-06T23:48:11.946197",
  "integratorId": "646c19ee1f70865ec37a719a",
  "beneficiaryId": "647fc5ba11974c5d85ecce3e",
  "message": null,
  "success": null,
  "data": {
    "id": "007192bc-f1fd-4c8a-bc3a-0c6a8e3336a8",
    "beneficiaryId": "647fc5ba11974c5d85ecce3e",
    "status": null,
    "steps": [
      {
        "id": "c741cb5b-5215-474a-89fb-0dfb2dd3963f",
        "ownerIdentification": "123456789",
        "uploadLink": "https://caliza.web.amer-1.jumio.ai/web/v4/app?authorizationToken=eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XMsa1CMQyF4V1SYym5tuOYjpKWDWLHngDpPQmxO-FuQHf069N5lfi_Pcu1tD56VanapNdyKdP9vnbHVRU9DAxxAnFNUNcGPOoi88am7ctPbMs7og44cmy8-gJNdhAi9VSjprHxX8Yv3B-RW3eSdLbZmgo5r8HhHniK886DOCgZaHaEPSbYkQRyVBtLpIdgeX8AFjt8Z_IAAAA.FsJhtgXZarANwihnZPy5Yaf6hahm-vdN0RkNeMrEZ8YcjLHsloBz4T9OTUlvRbP4EFxk-a7oBk_oikkVxobA5Q&locale=en-US",
        "jumioSdk": {
        	"token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XMsa1CMQyF4V1SYym5tuOYjpKWDWLHngDpPQmxO-FuQHf069N5lfi_Pcu1tD56VanapNdyKdP9vnbHVRU9DAxxAnFNUNcGPOoi88am7ctPbMs7og44cmy8-gJNdhAi9VSjprHxX8Yv3B-RW3eSdLbZmgo5r8HhHniK886DOCgZaHaEPSbYkQRyVBtLpIdgeX8AFjt8Z_IAAAA.FsJhtgXZarANwihnZPy5Yaf6hahm-vdN0RkNeMrEZ8YcjLHsloBz4T9OTUlvRbP4EFxk-a7oBk_oikkVxobA5Q"
        },
        "acceptedDocs": null
      }
    ],
    "errors": []
  }
}

Approving KYC in Sandbox

In the sandbox, the data.steps[].uploadLink field is a publicly accessible link to our sandbox. Making a GET request to this URL, will approve the beneficiary in sandbox.

KYB (For Business Beneficiaries)

In order to approve a business, we need to validate the registration status of the business, along with the identities of the business's legal representative, as well as any beneficial owners (those who own >= 25% of the business).

In order to validate the business, we require three documents: the certificate of incorporation, the tax registration, and validation of a business bank account.

The example below is for uploading the incorporation certificate. For any other document, update the name and type fields as appropriate.

curl --request POST \
     --url 'https://sandbox.api.caliza.co/core-api/v1/beneficiaries/{id}/files' \
     --header 'Authorization: Bearer {{YOUR_TOKEN}}' \
     --form 'file=@"/path/to/file"' \
     --form 'name="INCORPORATION_CERTIFICATE"' \
     --form 'type="INCORPORATION_CERTIFICATE"' \
     --form 'documentOwner="BUSINESS"''

Legal Representative & Beneficial Owners

In order to verify the legal representatives or beneficial owners, we'll conduct the same process that we conduct for individual KYX. You'll see details above in the Relaying Partner Link to Beneficiary section. You'll need to do this for each legal representative & beneficial owner.

Clearing KYX

If everything works as expected (in sandbox as well), the beneficiary's status will update to CREATED and the KYX process will be finished. You will receive status updates via webhook as the beneficiary's KYC status changes. You can also check the status yourself using the GET /v1/beneficiaries/{id} endpoint.

Retrieving Documents and Images Submitted as Part of Successful KYX

After a KYX is completed, the documents and images submitted (front, back of document, and selfie) for each individual involved in the process can be retrieved at GET /v1/kyx/{beneficiaryId}/documents. It's return will be of the form:

[
  {
    personId: "documentId",
    files: [
      { 
        front: byte[],
        back: byte[],
        type: "ID_CARD|DRIVING_LICENSE|SELFIE",
        fileType: "jpg|png"
    	}
    ]
  }
]

Callback notification examples

{
	"operation": "BENEFICIARY_KYC",
  "resource": "beneficiaries",
  "resourceId": "6306548828912548710e667c",
  "createdAt": "2022-08-02T15:51:49.119+00:00",
  "integratorId": "6306548828912548710e665a",
  "beneficiaryId": "6306548828912548710e667a",
  "succeeded": true
}

{
	"operation": "BENEFICIARY_KYC",
  "resource": "beneficiaries",
  "resourceId": "6306548828912548710e667c",
  "createdAt": "2022-08-02T15:51:49.119+00:00",
  "integratorId": "6306548828912548710e665a",
  "beneficiaryId": "6306548828912548710e667a",
  "error": "Something went wrong",
  "succeeded": false
}