External Onboarding Services

Onboarding Server can call services exposed by the entity to extend the KYC process. These services need to be implemented by the client, so the documentation below describes API requirements, not existing services.

Authentication

Onboarding server optionally supports HTTP Basic Auth when calling external services.

Authorization: Basic <credentials>

If you choose to secure your API, credentials (username and password) have to be configured at onboarding server.

API URL

When calling API, endpoint URL is constructed from configured “base path” and fixed “resource uri”

$BASE_PATH/$RESOURCE_URI

• BASE_PATH cointains protocol, domain and optionally port or prefixes (like “api” or “version” etc.)
• RESOURCE_URI containes fixed endpoint URI (see respective endpoint description)

Example API URL:

https://my.great.api/api/v1/client/approval

For Onboarding Server configuration BASE_PATH value is needed.

HTTP Headers

Optional headers can be configured to different names.

Error Handling

Onboarding Server uses following format for error response body, accompanied by an appropriate HTTP status code. Besides the HTTP error codes that application server may return regardless of server application (such as 404 when resource is not found or 503 when server is down), following ERROR codes may be returned:

All error responses that are produced by the Onboarding Server have the following body:

{
  "errorCode": "ERROR_GENERIC",
  "message": "An error message"
}

API Endpoints

Optional RESTful API services called by Onboarding Server:

{
    "processId": "String",
    "userId": "String",
    "identityVerificationId": "String",
    "provider": "String",
    "result": Number,
    "biometryData": "String"
}

{
  "result": "String",
  "resultReason": null
}

{
    "processId": "String",
    "identification": Object # Dictionary/Hashmap
}

{
  "userId": "String",
  "consent": "String",
  "consentRequired": Boolean # Deprecated
}

{
    "processId": "String",
    "userId": "String",
    "identityVerificationId": "String",
    "provider": "String",
    "investigationId": "String", # verificationId - upstream, investigationId - downstream
    "verificationResult": Object, # TODO
    "extractedData": Object # TODO
}

{
  "result": "String",
  "resultReason": null
}

{
    "processId": "String",
    "userId": "String",
    "language": "String",
    "otpCode": "String",
    "otpType": "String",
    "resend": Boolean
}

{
  "otpSent": Boolean
}

{
    "processId": "String",
    "userId": "String",
    "consentType": "String",
    "approved": Boolean
}

{
    "processId": "String",
    "userId": "String",
    "consentType": "String",
    "language": "String"
}

{
  "consentText": "String"
}