IdvUpload API Method

This operation is used to provide ID documentation in the case when ValidateRegistration response comes with ValidateRegistrationCure = IDV. On successful response from this endpoint (ValidateRegistrationCure = Healthy), SaleCard endpoint can be called.

📘
Every request triggered should have a unique X-GD-RequestId value in the header.

Syntax

POST {baseUrl}/registration/validate/idv

Example Request

Success Request

POST {baseUrl}/registration/validate/idv
Authorization: bearer {token}
Content-Type: application/json
X-GD-RequestId: test101

{
  "registrationToken": "fdd196f1-b180-47d9-9e31-43540e11efc5",
  "idvDocumentInfo": {
    "documentFrontImage": "(base64codeofmockedimagedata)",
    "documentBackImage": "(base64codeofmockedimagedata)",
    "documentType": "driverslicense",
    "documentCountryCode": "USA"
  },
  "metadata": {
    "storeId": "CC970",
    "merchantId": "FSCC0342",
    "userId": "[email protected]",
    "requestDateTime": "2023-10-11T05:53:15Z",
    "registerId": ""
  }
}

Negative Request

POST {baseUrl}/registration/validate/idv

Authorization: bearer {token}
Content-Type: application/json
X-GD-RequestId: test101

{
  "registrationToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "idvDocumentInfo": {
    "documentFrontImage": "",
    "documentBackImage": "",
    "documentType": "passport",
    "documentCountryCode": "MEX"
  },
  "metadata": {
    "storeId": "CC970",
    "merchantId": "FSCC0342",
    "userId": "[email protected]",
    "requestDateTime": "2023-10-11T06:13:56Z",
    "registerId": ""
  }
}

Request Parameters

Parameter	Required (Y/N)	Format/ Data Type	Pattern	Description
X-GD-RequestId	Yes	String	MaxLength:50	It is a unique transaction identifier that is generated by the retailer.
requestDateTime	Yes	DateTime	2023-08-08T12:34:56Z	Time stamp at which transaction occurred. The time stamp has to be in UTC time zone and follow the following date and time formats: • YYYY-MM-DDTHH:mm:ssZ
registerId	No	String	MaxLength: 20	Register where the transaction occurred.
userId	Yes	String	MaxLength:50	The unique ID of the user generating the transaction. If not supplied, InvalidParameter (Code:100) error will be return.
storeId	Yes	String	MaxLength: 20	The store number associated with the retailer that sold the package. If not supplied, InvalidParameter (Code:100) error will be return.
merchantId	Yes	String	MaxLength: 20	Unique merchant Id. It is defined by Green Dot – Merchant corresponding with Retailer. If not supplied, InvalidParameter (Code:100) error will be return.
registrationToken	Yes	GUID	e5843e05-d367-4bf1-a223-3af46ae18802	RegistrationToken from the ValidateRegistration response.
idvDocumentInfo
documentFrontImage	Yes	String		Documents Front Image File in base64 string format.
documentBackImage	No	String		Documents Back Image File in base64 string format. Back image is required for all documents except passport.
documentType	Yes	String		Values can be driverslicense, passport, stateidcard, nationalidcard, or ConsulateID. For passport card, nationalidcard or ConsulateID should be used.
documentCountryCode	Yes	String		Documents Country Code in ISO 3166-1 alpha-3 format.

Example Response

Success Response

HTTP/1.1 200 OK
Content-Type: application/json
X-GD-RequestId: test101
X-GD-ResponseId: 20d67bb8-466e-461f-a0e8-119d53176b3d
X-GD-ResponseCode: 0
{
    "validateRegistrationCure": "Healthy",
    "metadata": {
        "requestId": "test101",
        "responseId": "20d67bb8-466e-461f-a0e8-119d53176b3d",
        "responseDateTime": "2023-10-11T05:53:18.7420977Z",
        "responseCode": 0,
        "responseDescription": "IDV Approved."
    }
}

Negative Response

HTTP/1.1 400 OK
Content-Type: application/json
X-GD-RequestId: test101
X-GD-ResponseId: 7d25ffac-4c0e-4d11-a6c0-c6cd98e2710d
X-GD-ResponseCode: 100
{
    "validateRegistrationCure": null,
    "metadata": {
        "requestId": "test101",
        "responseId": "7d25ffac-4c0e-4d11-a6c0-c6cd98e2710d",
        "responseDateTime": "2023-10-11T06:13:57.7622981Z",
        "responseCode": 100,
        "responseDescription": "The DocumentFrontImage field is required."
    }
}

Response Parameters

Parameter	Format/Data Type	Pattern	Description
requestId	String	MaxLength:50	The unique request ID generated from the request.
responseId	String	MaxLength:50	The unique Response Identifier (generated by GreenDot).
responseDateTime	DateTime	2023-09-07T16:12:23.4541445+08:00	Time stamp at which transaction occurred. The time stamp is in UTC time zone and follow the following date and time formats: • YYYY-MM-DDTHH:mm:ssfffffffK
responseCode	Numeric	MaxLength:4	Indicates success and failure of the response codes. It is in the numeric format.
responseDescription	String	MaxLength:255	Describes the Response Code in more detail. It is in the String format.
validateRegistrationCure	String	“IDV” “None” “Healthy”	Health of the CIP validation - Healthy /IDV/None

Response Cases

Code	CodeText	Response Description	Description
0	IDV Approved	IDV Approved	Success.
100	InvalidParameter	• KYC Gate does not match kycPendingGate. • Verification request not found • DocumentCountryCode has to be 3 alphabets • DocumentBackImage is required • Invalid DocumentType value • The RegistrationToken field is required. • The DocumentFrontImage field is required. • The DocumentType field is required. • Invalid DocumentType value • The DocumentCountryCode field is required. • StoreId is required • MerchantId is required • UserId is required • RequestId is required • RequestDateTime is required • RequestId is too long • UserId is too long • StoreId is too long • MerchantId is too long	Invalid parameter in the request. Examples: MerchantID not supplied, StoreID not supplied, registration token not found, account is not in IDV mode.
130	InvalidMerchant	InvalidMerchant	MerchantId in request has not been found/enabled in the system.
800	InvalidStore	Store was not found	Store is not found; store is not for the partner or store does not support this operation.
861	RetailChainUserNotFound	User is not found.	UserID in request is not found in system.
862	RetailChainUserNotActive	User is not active.	UserId in request is not active.
500	CIPFAILED	• IDV Scan Upload Failure. • IDV Not Readable. • IDV Scan Upload Success - Verification Failed. • IDV scan Max Attempt Reached. • Invalid Document country code	CIP fails after process document
1000	GeneralFailure	GeneralFailure	Service failure.