Attestation Agency SDK
Installation
This package is hosted on npm and can be installed with:
npm install attestation-agency-sdk
Background
An Attestation is the evidence of mutual agreement of the specific value of an attribute. In other words, a user makes a claim of an attribute having a specific PII value (Personally Identifiable Information) and a 3d party confirms (or attests) that PII value being true. Here is an example of an attestation: A user X claimed that their "First_name" = "John" and an agency Y verified this claim to be true on 2019-01-01.
A verification at globaliD is the process of attesting a group of claims bound together by specific context. For example, a verification of a passport document is a collection of attestations about each attribute found in a passport.
This Attestation SDK and the corresponding attestation service enables any developer to create and service any verification of identity.
ONGOING verifications are also possible where the same claims are verified periodically.
Setup
Import
import attestationAgencySdk {
// Other interfaces if implementing using typescript
SDK,
Modules,
Config,
EncryptedData,
PiiData
} from 'attestation-agency-sdk'
Configuration
let config: Config = {
// client credentials
clientId: 'test-clientId', // globalid api client id
clientSecret: 'test-clientSecret', // globalid api client secret
// signing and encryption key setup
privateSigningKey: '', // private signing key or a path to the key file
privateEncryptKey: '', // private encryption key or a path to the key file
signingPassphrase: '', // passphrase for private signing key (optional, recommended)
encryptPassphrase: '', // passphrase for private encryption key (optional, recommended)
sandbox: true, // [default = false], if connecting to globaliD sandbox backend
}
Initialization
// Make a new SDK Instance
const sdk = SDK.Module
// Init the SDK instance: this will call globaliD API to get the configuration
// for the agency identified by the set clientId and then configure itself correctly.
try {
sdk = await attestationAgencySdk.init(config)
console.log('SDK initialized and can be used')
} catch (err) {
console.error('SDK initialization failed', err)
}
Usage
Processing of a new verification
Client will first make a request to the globaliD attestation service identifying
which agency should be used for the verification process.
Using this call, a trackingId
for the new verification will be returned to the client.
It will then call agency's route defined to process the verification, for example:
PUT /confirm/:trackingId
Decrypting of the payload sent by the client
Depending on the verification flow defined by the agency, client might then need to collect additional data and send it as a payload to the above route. The payload will be encrypted using agency's public encryption key:
- client will generate a random password and use AES to encrypt the JSON string representing the payload
- it will then encrypt the password using the agency's public encryption key.
To obtain the raw data, verifyAndDecryptData
should be called:
// if using typescript
let encryptedData: EncryptedData = {
enc_password: request.body.enc_password // password with which data is encrypted
enc_data: request.body.enc_data // encrypted data
}
// else
let encryptedData = request.body
try {
const plainData: object = await sdk.verifyAndDecryptData(
request.params.trackingId,
encryptedData
)
console.log('decrypted data:', plainData)
// process the request..
} catch (err) {
console.error('decryption and verification failed', err)
}
Confirming the verification on success (simple)
After PII values are obtained from the payload, your verification process must be performed.
This is where you check your internal processes to verify user's claims.
Afterwards, if successfully verified, this verification request must be marked as successfully processed.
This should be done using confirmAttestationRequest
method. Only predefined attestation types for the agency must
be used: for example (as in the example below) legal_first_name, legal_last_name, date_of_birth and photo_file_front:
// using typescript
let PII: PiiData = {
legal_first_name: 'John',
legal_last_name: 'Rain',
date_of_birth: '1973-01-01',
photo_file_front: fs.createReadStream('document_image.png')
}
try {
await sdk.confirmAttestationRequest(
trackingId,
PII
)
// verification successfully confirmed, it's now user's turn to
// either accept or deny it
} catch (err) {
console.error('error processing the verification confirmation', err)
}
Marking verification as failed
If the verification request can not be processed by the agency, it should be marked as failed, using failAttestationRequestWithCode
(SEE AVAILABLE FAILURE REASON CODES HERE):
try {
await sdk.failAttestationRequestWithCode(
trackingId,
'400-1'
)
} catch (err) {
console.error('error marking the verification as failed, this is a globaliD issue', err)
}
Alternatively, if you do not find an appropriate failure reason code, you can send
your own text to the user using failAttestationRequest
(keep in mind the message will not be localized for the user):
try {
await sdk.failAttestationRequest(
trackingId,
'Reason explaining the problem to the requesting user'
)
} catch (err) {
console.error('error marking the verification as failed, this is a globaliD issue', err)
}
If you want to fail all expired requests directed to your service prior to a certain datetime,
you should call failExpiredAttestationRequests
method with the datetime in ISO format.
The service will find all verification requests submitted to your service which
are currently in progress (and were created before teh specifeid date) and fail them with 600-5 code.
try {
await sdk.failExpiredAttestationRequests(new Date().toISOString())
} catch (err) {
console.error('Failing all verification requests submited before this date and still not completed.', err)
}
Forwarding the user back to globaliD
In certain cases, when the user arrives to your service outside of the globaliD app (or web client) you may want to forward the user to a landing page with a message to get back to globaliD
You can use this link on success:
https://api.global.id/v1/verification/success/{tracking_id}
Otherwise use this link:
https://api.global.id/v1/verification/failed/{tracking_id}
Use the original {tracking_id} of the verification request.
Revoking issued verifications
You can revoke the verifications you issued with the revokeAttestationRequest
method.
// UUID of the verification request you are trying to revoke
const trackingId: string = 'cd27a133-0193-4508-9cbf-61c91de602b1'
try {
await sdk.revokeAttestationRequest(
trackingId, // uuid of the verification request
'reason'
)
} catch (err) {
console.error('error: request you are trying to revoke might not be possible to revoke', err)
}
Updating ongoing status
This is an example how you can update ongoing status for all your issued verifications. Only the agency application/service that supports ongoing verifications can use this method.
const appId: string = '82fece9b-2963-48c1-9807-60e87b5766ed' // Agency app uuid
const logRequestId: string = uuid() //uuid sent by agency to track their update
try {
await sdk.updateOngoingAttestationStatus(
appId,
logRequestId
)
} catch (err) {
console.error('error, agency application might not support ongoing verifications', err)
}
Also you can revoke multiple verification requests with this method if you pass a 3rd parameter in the method like this:
const appId: string = '82fece9b-2963-48c1-9807-60e87b5766ed' // Agency app uuid
const logRequestId: string = uuid() //uuid sent by agency to track their update
const revokeObjects: RevokeInterface[] = [
{
attestation_request_uuid: '704e13c5-a0a6-4b65-a05b-61bced577560',
reason: 'Verification has expired',
},
{
attestation_request_uuid: '4401f35c-1bd6-44df-8246-024508d98f62',
reason: 'Related verifications are not longer valid',
}
]
try {
await sdk.updateOngoingAttestationStatus(
appId,
logRequestId,
revokeObjects
)
} catch (err) {
console.error('error, agency application might not support ongoing verifications', err)
}
Confirming a verification on success (advanced)
Grouped attestations
In case agency obtains multiple attestations which should be logically grouped as sets, the related attestations should be marked as grouped.
For example, your agency can verify for attestee's name plus multiple addresses:
- photo_file_front (file)
- legal_first_name
- legal_last_name
- addresses, each containing
- address_city
- address_country
- address_zip_code
- address
To properly mark such verification as successful, a processAttestationRequest
should be used, which returns an attestation response builder (see below for more details):
try {
const builder: Module.AttestationBuilder = await sdk.processAttestationRequest(
trackingId
)
// adding file attestation
await builder.addFile('photo_file_front', fs.readFileSync('document_image.png'))
// add first and last names as simple attestations
await builder.add('legal_first_name', 'John')
await builder.add('legal_last_name', 'Rain')
// now add attestations for each address set.
// Let's say they will be grouped by the `address` attestation
// and that `addresses` variable already contains properly grouped
// address objects:
for (let address of addresses) {
// `builder.add()` returns `uuid` representing the prepared
// attestation. This can be used by other attestations to
// indicate attestation relations
let group = await builder.add('address', address.address)
// add other attestations for this address and
// pass `group` as the third argument to indicate the relation:
let options: AttestationOptions = {
relatedAttestations: group
}
await builder.add('address_city', address.city, options)
await builder.add('address_country', address.country, options)
await builder.add('address_zip_code', address.zip, options)
}
// after all attestation PII are added to the builder,
// `builder.submit()` must be called:
await builder.submit()
} catch (err) {
console.error('error processing the attestation', err)
}
Partial updates - keeping the verification request in process until all of the data is collected
In some cases, agency can perform additional verifications based on the PII data. To avoid saving of raw PII values on agency side, you can use a partial update feature, where it stores partial PII on the globaliD side and keep the verification in process (meaning it is not yet ready for the user's action).
Example would be that agency can attest for:
-
photo_file_front
- legal_first_name
- legal_last_name
-
phone_number and using phone number it can then also obtain the
- address_country // based on phone number code
// here is a first set of PII data: we obtained the
// legal_first_name, legal_last_name, and phone_number
try {
const builder: Module.AttestationBuilder = await sdk.processAttestationRequest(
trackingId,
true // indicate that this is a partial update
)
// adding file attestation with related attestation
const fileId: string = await builder.addFile('photo_file_front', fs.readFileSync('document_image.png'))
await builder.add('legal_first_name', 'John', {
relatedAttestations: fileId
})
await builder.add('legal_last_name', 'Rain', {
relatedAttestations: fileId
})
// we'll relate the `address_country` as related to this phone
// number attestation, so we need to remember it's attestation uuid
const phoneRelated: string = await builder.add('phone_number', '+123456789')
// save partial attestation data:
await builder.submit()
// now try and get the `address_country` from the phone number
doGetAddressCountryFromThePhoneNumber(
trackingId,
'+123456789',
phoneRelated
)
} catch (err) {
console.error('error processing the attestation', err)
}
async function doGetAddressCountryFromThePhoneNumber(
trackingId: string,
phoneNumber: string,
relatedAttestation: string | string[]
) {
let country = somehowObtainTheCountryFromThePhoneNumber(phone_number)
// again, get the builder, add a new attestation and now mark the verification request
// as processed
try {
const builder: Modules.AttestationBuilder = await sdk.processAttestationRequest(
trackingId
// partialUpdate = false by default
)
await builder.add('address_country', country, {
relatedAttestations: relatedAttestation
})
await builder.submit()
} catch (err) {
console.error('error processing this verification request', err)
}
}
Partial update - remove a previous attestation
It is also possible to remove the previous attestation from a partially verification. An example would be that agency attests for the
- legal_full_name
-
phone_number
- and then checks if the obtained phone number actually is valid or not
// NOTE:error handling is skipped for the sake of shorter examples
// submit a partial verification
let builder: Modules.AttestationBuilder = await sdk.processAttestationRequest(
trackingId,
true // indicate that this is a partial update
)
await builder.add('legal_full_name', 'John Rain')
const phoneRelated: string = await builder.add('phone_number', '+123456789')
await builder.submit()
// validate the phone number: a longer process where user receives an sms
// or a phone call, etc..
let valid: boolean = await validatePhoneNnumber('+123456789')
// finalize the verification, keep phone attestation based on whether it is valid or not
builder = await sdk.processAttestationRequest(trackingId)
if (!valid) {
builder.remove(phoneRelated)
}
await builder.submit()
Partial update - update previous verification
Partially stored PII on globaliD side can also be updated, using the related attestation(s) uuid(s). Example could be when attesting for legal_full_name
where
- in first step
Mr. John Rain
would be obtained - which would then be passed to another validation / normalization which would return
John Rain
// NOTE:error handling is skipped for the sake of shorter examples
let obtainedName = 'Mr. John Rain'
// submit a partial verification result
let builder: Modules.AttestationBuilder = await sdk.processAttestationRequest(
trackingId,
true // indicate that this is a partial update
)
const nameAttestation: string = builder.add('legal_full_name', obtainedName)
await builder.submit()
// do additional lookup on that name (and possible other obtained data) and get updated name
let normalizedName: string = await lookupThisName(obtainedName)
// update the legal_full_name
builder = await sdk.processAttestationRequest(trackingId)
if (normalizedName !== obtainedName) {
await builder.update(
nameAttestation,
normalizedName
)
}
await builder.submit()
Creating attestations with public data field
In case when agency would like to add public data and public attestor note to the attestations or create attestations without PII value.
try {
// prepare builder
const builder: Modules.AttestationBuilder = await sdk.processAttestationRequest(
trackingId
)
// creating attestation with PII value and public data
await builder.add('date_of_birth', '1986-04-01', {
publicData: '24+'
})
// creating file attestation with public data and attestor note
await builder.addFile('photo_file_front', fs.readFileSync('document_image.png'), {
publicData: 'Passport',
publicAttestorNote: 'User took the photo',
})
// save attestation data:
await builder.submit()
} catch (err) {
console.error('error processing the attestation', err)
}
Get information about attestee requesting the verification
In case when agency would like to know which globaliD identity is requesting the verification
// prepare builder
const builder: Modules.AttestationBuilder = await sdk.processAttestationRequest(
trackingId
)
// get attestee information
let attestee: AttesteeInfo = builder.getAttesteeInfo()
// get attestee information without using the builder option
let attestee: AttesteeInfo = await sdk.getAttesteeInfo(trackingId)
Validating PII value
In case when agency would like to check if the PII value for one attestation is valid.
import SDK, { PIIValidationParameters } from 'attestation-agency-sdk'
try {
// prepare params
const params: PIIValidationParameters = {
piiValue: 'username@gmail.com', // plain PII value to check
attestationUuid: 'cb364193-4244-48be-b79d-ef482bdf5b92', // attestation uuid
saltPassword: 'saltPassword', // password with which salt is created and then data hash is generated
attestationType: 'email', // type of attestation
attestor: 'mandrill', // OPTIONAL attestor
attestee: 'oneGlobaliDUSer' // OPTIONAL attestee
}
const attestation = await SDK.PIIValidation(params)
} catch (err) {
console.error('error PII value is incorrect', err)
}
Documentation
SDK Configuration
- clientId: (required) used for authentication on globalId API
- clientSecret: (required) used for authentication on globalId API
- privateSigningKey: (required) private key used for signing
- signingPassphrase: (optional) passphrase for private signing key
- privateEncryptKey: (required) private key used for encryption
- encryptPassphrase: (optional) passphrase for private encryption key
- sandbox: (required default false), if sandbox is false, production api is used, otherwise - staging
Available Methods
SDK has the following public async methods:
-
sdk.verifyAndDecryptData
: Available after a successfulawait sdk.init()
call. Used to verify and decrypt data.async verifyAndDecryptData(trackingId: string, encryptedData: EncryptedData): Promise<object>
-
sdk.confirmAttestationRequest
: Available after a successfulawait sdk.init()
call. It takes attested data, encrypts the PII, signs verifications and sends attested data to globaliDasync confirmAttestationRequest(trackingId: string, piiData: PiiData): Promise<object>
-
sdk.processAttestationRequest
: Available after a successfulawait sdk.init()
call. Returns the verification response builder in case partial updates are needed and/or related attestations should be used (for marking sets of attestation data as groups)// see `AttestationBuilder` interface below async processAttestationRequest(trackingId: string, partialUpdate?: boolean): Promise<Modules.AttestationBuilder>
-
sdk.failAttestationRequest
: Available after a successfulawait sdk.init()
call. Used when agency completes the verification process and the verification has failed.async failAttestationRequest(trackingId: string, failReason: string): Promise<void>
-
sdk.failExpiredAttestationRequests
: Available after a successfulawait sdk.init()
call. Used when agency need to fail all expired verification requests.async failExpiredAttestationRequests(createdBefore: string): Promise<{ failed_requests_uuid: string[] }>
-
sdk.verifyAndDecryptData
: Available after a successfulawait sdk.init()
call. Used to verify and decrypt data.async verifyAndDecryptData(trackingId: string, encryptedData: EncryptedData): Promise<object>
-
sdk.PIIValidation
: Used when agency wants to check if the PII value is valid and a specific attestation is correctasync PIIValidation({ piiValue: string, attestationUuid: string, saltPassword: string, attestationType: string, attestor?: string, attestee?: string }: PIIValidationParameters): Promise<PIIAttestation>
-
sdk.getConfig
: Available after a successfulawait sdk.init()
call. It contains a configuration fetched from the globaliD backend during the configuration.let config: Config = sdk.getConfig()
-
sdk.getAgency
: Available after a successfulawait sdk.init()
call. It contains a agency information fetched from the globaliD backend during the configuration.let config: AgencyConfig = sdk.getAgency()
-
sdk.getAttesteeInfo
: Available after a successfulawait sdk.init()
call. Used to get information about attestee requesting the verification process.async getAttesteeInfo(trackingId: string): Promise<AttesteeInfo>
-
sdk.revokeAttestationRequest(trackingId: string, reason: string): Promise<AttestationRequest>
: Available after a successfulawait sdk.init()
call. Used to revoke an existing attestation.async revokeAttestationRequest(trackingId: string, reason: string): Promise<AttestationRequest>
-
updateOngoingAttestationStatus(appId: string, logRequestId: string, revocations?: RevokeInterface[]): Promise<UpdateOngoingStatusResponse>
: Available after a successfulawait sdk.init()
call. Used to update ongoing verifications, with the same call you can also revoke a batch of attestations.async updateOngoingAttestationStatus(appId: string, logRequestId: string, revocations?: RevokeInterface[]): Promise<UpdateOngoingStatusResponse>
Interfaces
interface Config {
clientId?: string
clientSecret?: string
privateSigningKey?: string
signingPassphrase?: string
privateEncryptKey?: string
encryptPassphrase?: string
sandbox?: boolean
}
interface EncryptedData {
enc_password: string
enc_data: string
}
interface PiiData {
[key: string]: string
}
interface PIIValidationParameters {
piiValue: string,
attestationUuid: string,
saltPassword: string,
attestationType: string,
attestor?: string,
attestee?: string,
}
interface AttestationBuilder {
/**
* Add new attestation
* @param {string} type
* @param {string} piiValue
* @param {object?} {
* relatedAttestations?:
* string of related attestation uuids (separated by comma if multiple)
* or string[] of related attestation uuids
* publicData?: string public attestation data
* publicAttestorNote?: string attestor notes
*}
* @returns {Promise<string} attestation uuid which can be used for related_attestations
*/
add(
type: string,
piiValue: string|Buffer,
options? : {
relatedAttestations?: string | string[]
publicData?: string
publicAttestorNote?: string
}
): Promise<string>
/**
* Add new file attestation
* @param {string} type
* @param {Stream | Buffer} file
* @param {object?} {
* relatedAttestations?:
* string of related attestation uuids (separated by comma if multiple)
* or string[] of related attestation uuids
* publicData?: string public attestation data
* publicAttestorNote?: string attestor notes
*}
* @returns {Promise<string} attestation uuid which can be used for related_attestations
*/
addFile(
type: string,
file: Stream|Buffer,
options? : {
relatedAttestations?: string | string[]
publicData?: string
publicAttestorNote?: string
}
): Promise<string>
/**
* Getting information about attestee requesting the process
*/
getAttesteeInfo(): AttesteeInfo
/**
* Remove existing attestation (when using partialUpdate feature)
* @param {string} attestationUUID existing attestation uuid to be updated
* @param {string} type
* @param {string} piiValue
* @param {object?} {
* relatedAttestations?:
* string of related attestation uuids (separated by comma if multiple)
* or string[] of related attestation uuids
* publicData?: string public attestation data
* publicAttestorNote?: string attestor notes
*}
* separated by comma
* if omitted, existing value will be kept
* if set new value will be set
* - use empty string to remove related
* attestations
*
* @returns {Promise<string} attestation uuid which can be used for related_attestations
*/
update(
attestationUUID: string,
piiValue: string|Buffer,
options? : {
relatedAttestations?: string | string[]
publicData?: string
publicAttestorNote?: string
}
): Promise<string>
/**
* Remove existing file attestation (when using partialUpdate feature)
* @param {string} attestationUUID existing attestation uuid to be updated
* @param {Stream|Buffer} file
* @param {object?} {
* relatedAttestations?:
* string of related attestation uuids (separated by comma if multiple)
* or string[] of related attestation uuids
* publicData?: string public attestation data
* publicAttestorNote?: string attestor notes
*}
* separated by comma
* if omitted, existing value will be kept
* if set new value will be set
* - use empty string to remove related
* attestations
*
* @returns {Promise<string} attestation uuid which can be used for related_attestations
*/
updateFile (
attestationUUID: string,
file: Stream | Buffer,
options?: AttestationOptions,
): Promise<string>
/**
* Remove attestation by uuid (when using partialUpdate feature)
* @param {string} attestationUUID
*/
remove(attestationUUID: string): boolean
/**
* Submit the prepared attestaion response
*/
submit():Promise<any>
}
interface AgencyConfig {
uuid: string // agency's uuid
globalid: string // agency's globalid (`attestor`)
attestation_process: string // description of agency verification process
name: string // agency name
logo: string // link to logo image
description: string // description of the agency
brand_color: string
gid_name?: string // agency's globalid (`attestor`)
client_id: string
signing_pbk: string // public key used to verify agency signatures
encryption_pbk: string // public key to share sensitive data with the
// agency
min_app_version: number // min version of globaliD app which supports
// the agency verification flow
types: AgencyType[]
category: AgencyCategory
created_at: string
updated_at: string
}
interface AgencyType {
uuid: string
type: string // attestation type (atttribute of identity)
agency: string // agency's uuid
optional: boolean // indicates if this type might not be present for all
// of the verifications by this agency
max_att_number: number // for multi attestation purpose - indicates how many
// salts for this type should be present if agency can
// attest for more than just one PII value related to
// this type
created_at: string
updated_at: string
}
interface AgencyCategory {
uuid: string // category uuid
name: string // category name
short_name: string // short category name
created_at: string
updated_at: string
}
interface AttesteeInfo {
gid_name: string
gid_uuid: string
}
Errors
Thrown on initialization, if required properties are missing from the configuration object
ERR_CONFIG_CLIENT_ID_REQUIRED
ERR_CONFIG_CLIENT_SECRET_REQUIRED
ERR_CONFIG_PRIVATE_SIGNING_KEY_REQUIRED
ERR_CONFIG_PRIVATE_ENCRYPTION_KEY_REQUIRED
During the verification processing
-
ERR_CREATE_AND_SIGN_ATTESTATION_INVALID_VALUE
the set PII value is not of string or Buffer type -
ERR_CREATE_AND_SIGN_ATTESTATION_INVALID_RELATED_ATTESTATIONS
related_attestations passed is passed but is not a string -
ERR_GET_GLOBALID_PUBLICKEY
obtaining the public encryption key from globaliD verification service failed. -
ERR_ENCRYPT_PII_DATA
encrypting of PII data failed, enable debugging to get additional data. -
ERR_DECRYPT_PII_DATA
something went wrong while using theverifyAndDecryptData
. Enable debugging for additional info. -
ERR_INVALID_ATTESTATION_REQUEST
globaliD problem, verification is corrupted and cannot be processed by the agency. -
ERR_REQUEST_NOT_FOR_THIS_AGENCY
the verification does not belong to the client configured for this sdk instance. -
ERR_COULD_NOT_UPDATE_ATTESTATION_SALT_IDX_INVALID
client did not prepare the verification request correctly, verification can not be successfully processed by the sdk. -
ERR_COULD_NOT_UPDATE_ATTESTATION_SALT_DUPLICATED
attestation is using the same salt that was already used by another attestation of the same type -
ERR_NO_SALTS_FOUND
client did not prepare the verification request correctly, verification can not be successfully processed by the sdk. -
ERR_NO_SUCH_ATTESTATION_IN_REQUEST
invalid trackingId is used, such verification request does not exist. -
ERR_ATTESTATION_REQUEST_CAN_NOT_BE_UPDATED_BY_AGENCY
the verification related to trackingId is not in correct status to be updated by the agency any more (was already marked as failed / processed before) -
ERR_NOTHING_TO_SUBMIT
using theprocessAttestationRequest
builder, asubmit()
is being called but no changes were made to the verification. -
ERR_ATTESTATION_NOT_FOUND
can not get attestation onPIIValidation
-
ERR_PII_NOT_MATCH_ATTESTATION
PII is incorrect for the given attestation -
FAILED_TO_GET_ATTESTATION
Attestations can not be found under this uuid -
ERR_MISSING_SALTS_FOR_<type>
verification request is missing salt for one attestation type -
ERR_ADD_ATTESTATION_INVALID_TYPE_VALUE
PII value is not a string -
ERR_INVALID_PII_VALUE
PII value is empty -
ERR_ENV_SDK_SANDBOX_NOT_IN_RIGHT_FORMAT
Environment value SANDBOX needs to be true or false
Other errors
Other errors can be thrown by the globaliD verification backend.
Debugging
Debug messages are printed using debug node module and namespaced as attestation-agency-sdk
.
In order to see the debug messages, enable debugger for the SDK:
DEBUG=attestation-agency-sdk node index.js
To enable debugging on deployed images, the debug should be added to the deployment yaml file:
env:
- name: DEBUG
value: attestation-agency-sdk
Failure reason codes
300 - Government ID
Code | Description |
---|---|
300-1 | Agency cannot determine the type of the document. The image provided does not contain a document |
300-2 | Agency determined that the submitted picture contains a document but does not support this document type. |
300-3 | Document expired, expiration date is in the past relative to the date/time of the verification request |
300-4 | Provided selfie doesn't match the picture on the photo ID |
300-5 | When second page/side is required, only one page/side was provided. |
300-6 | Possibly fraudulent document. Agency could parse and understand document, but cannot issue a successful verification. |
300-7 | Missing required document data: document number. Agency could parse and understand document, but cannot find a document number on it to issue a successful verification. |
300-8 | Document version is not supported and cannot be verified. |
300-9 | Age could not be verified from the submitted document image. |
300-10 | Document images provided are of low quality |
300-11 | Selfie image provided is of low quality |
300-12 | Verification failed: MRZ could not be read |
300-13 | Verification failed: Expiration date could not be read |
300-14 | Verification failed: Your name could not be read |
300-15 | Verification failed: Date of birth could not be read or missing |
300-16 | Verification failed: face could not be detected on the document |
300-17 | Verification failed: face could not be detected on the selfie |
300-18 | Verification failed: document number could not be read |
300-19 | Verification failed: User OVER the allowed age limit |
300-20 | Verification failed: Document doesn't have info about age |
300-21 | User is UNDER the allowable minimum age for this verification. |
300-22 | The name on the ID did not match the name submitted. |
300-23 | The user was banned. (Most commonly due to repeated attempts) |
300-24 | The user uploaded a fake or sample image of an ID. |
300-25 | 1st image sent was not of the front page |
300-26 | Verification failed: Gender could not be read |
300-27 | Service reported that customer deceased |
300-28 | Address in identity report can't be confirmed |
300-29 | Date of birth in identity report can't be confirmed |
300-30 | Person in the live photo or live video does not appear to be real (spoofed) |
300-31 | Two mis-matched pages were sent (they do not belong to the same document) |
300-32 | Submitted document is not accepted for this verification request because the user submitted a document which was different from the one allowed by this verification app. |
300-33 | Too many faces detected in the selfie |
300-34 | Direction of face of the user incorrect in the selfie |
300-35 | User declined consent to match selfie image |
300-36 | User entered some data from the document manually |
300-37 | Some text is missing from the front of the document |
300-38 | Some text is missing from the back of the document |
300-39 | Error reading barcode at the back of the document submitted |
300-40 | The user provided selfie image(s )that were unlikely to be genuine. |
400 - Financial category
Code | Description |
---|---|
400-1 | Required data cannot be verified because information provided by the user did not match the record. |
400-2 | Financial institution does not support verification of required data |
600 - All categories
Code | Description |
---|---|
600-1 | Verification failed, some required information could not be verified. |
600-2 | Verification service throws an exception and cannot service the request in the allotted time. |
600-3 | User canceled login to the system |
600-4 | User canceled the request for another reason |
600-5 | The user did not complete required steps in time. |
600-6 | No matching account information for the provided user details |
600-7 | globaliD system had an error or is not available at the moment |
600-8 | Verification provider system had an error or is not available at the moment |
600-9 | Provided address was not formatted properly |
600-10 | Validation of provided required verification(s) has failed |
600-11 | Only one ongoing instance is possible for this verification; the user cannot resubmit another one. |
600-12 | Verification not possible for given location |
600-13 | Velocity abuse suspected; suspicious repeated requests |
600-14 | You exceeded the allowed limit of requests to resend the verification code. Try again later |
600-15 | Unfortunately, you have reached the maximum number of confirmation attempts. Try submitting a new request for verification later |
700 - Self declaration
Code | Description |
---|---|
700-1 | Required info was not provided for self-declaration |