onboard/v1/customer/status

[GET] /onboard/v1/customer/status

Get customer status

The get customer status endpoint allows for the retrieval of the current status of a customer. After a customer is onboarded their data will pass through several KYC (know-your-customer) vendor systems aimed at preventing money laundering and fraud. The status endpoint will provide information based on the response of those checks, and if any additional identification verification is required.

The request allows the newCustomerTag parameter as a string. When provided, Avenu's API will query the Customer Account and Customer Sub-ledger Event to retrieve the Customer Account Status.

Example [GET] Request

{{avenu_base_url}}/onboard/v1/customer/status?newCustomerTag={{newCustomerTag}}

Query Parameter

Parameter	Format	Required	Possible Error Codes
"newCustomerTag"	String	Y	1001, 1002, 1003

Example Response

{
    "newCustomerTag": "",
    "customerAccountNumber": "",
    "status": "",
    "statusInfo": "",
    "idScanUrl": ""
}

Response Elements

Element	Meaning	Reference
newCustomerTag	The customer's new customer tag. This value is set in during onboarding prior to an account number being associated with the customer.
customerAccountNumber	The Avenu customer account number is returned only after onboarding finalization (status code: `ENABLED`)
status	The customer's status code.	See Below
statusInfo	Additional information associated with status code.
idScanUrl	URL for serving iFrame implementation of KYC ID scan and liveliness.

The status field will change depending on the value of accountStatus returned by the query. The following table illustrates possible response values and behavior. If a status of PENDING is returned, then the Avenu API is still awaiting a response from the KYC vendors and you should check back soon for an updated status.

Customer Status Codes

accountStatus	customerAccountNumber	statusInfo	status
PENDING	null	Account is pending.	"PENDING"
DISABLED	null	Account is disabled. No payments can be made from/to this account.	"DISABLED"
ENABLED	set to SubLedger `customerAccounts`	Account is enabled	"ENABLED"
ID_SCAN	null	Customer needs to provide ID scan. `statusInfo` field contains the KYC session ID.	"ID_SCAN"
FAILED	null	As a result of an issue with the ID Scan (see table below for all statusInfo scenarios)	"FAILED"
REVIEW	null	The customer is being manually reviewed by the compliance team to determine onboarding outcome. `statusInfo` object contains the IDology KYC ID number	"REVIEW"
ERROR	null	Unknown App Error	"ERROR"

Response per Status

Condition	Response
CustomerAccount `accountStatus` = `PENDING`	`{ status: 'PENDING', customerAccountNumber: null, statusInfo: null }`
CustomerAccount `accountStatus` = `PENDING` AND `accountKyc` = `ID_SCAN`	`{ status: 'ID_SCAN', customerAccountNumber: null, statusInfo: [Idology KYC ID number] }`
CustomerAccount `accountStatus` = `SUSPENDED`	`{ status: 'DISABLED', customerAccountNumber: null, statusInfo: null }`
CustomerAccount `accountStatus` = `CLOSED`	`{ status: 'DISABLED', customerAccountNumber: null, statusInfo: null }`
CustomerAccount `accountStatus` = `OPEN`	`{ status: 'ENABLED', customerAccountNumber: [customerAccountNumber], statusInfo: null }`

FAILED customer status scenarios and next steps

idScan Response [status]	idScan Actions [statusInfo]	Customer [status]	Customer [statusInfo]	Next Step
Fail	Pass back each qualifier; {{id-scan-verification-result/qualifier}}	FAILED	IDScan Failure	Initiate Onboarding
Fail	Photo ID Not Valid	FAILED	Photo ID Not Valid	Initiate Onboarding
Pending	Photo ID Not Readable, please try again	FAILED	Photo ID Not Valid, please try again	Initiate Onboarding
Fail	Timed Out	FAILED	IDScan Timed Out	Initiate Onboarding
Fail	Abandoned Session	FAILED	Abandoned Session	Initiate Onboarding

Errors

code	Message
1001	"Missing required field"
1002	"Invalid data structure"
1003	"Invalid data"