Validate Registration
ValidateRegistration API Method
This method validates whether customer can purchase and be registered for a new card or not. Multiple identity types are supported to validate a new customer. A “Registration Token” returns, which is used in Sale Card Method to register the customer with the card.
Every request triggered should have a unique X-GD-RequestId value in the header.
Syntax
POST {baseUrl}/registration/validate
Example Request
Success Request
POST {baseUrl}/registration/validate
Authorization: bearer {token}
Content-Type: application/json
X-GD-RequestId: 123456789
{
"productCode": "51720",
"personData": {
"cellPhone": "6535738728",
"dateOfBirth": "2004-08-24",
"email": "[email protected]",
"firstName": "NIEDj",
"homeAddress": {
"addressLine1": "164 Peachtree Street",
"addressLine2": "SUITE 511",
"city": "Atlanta",
"countryCode": "USA",
"postalCode": "17513",
"state": "GA"
},
"homePhone": "5535741193",
"identification": [
{
"id": "108143604",
"issuerCountryCode": "USA",
"type": "SSN",
"expiryDate": null,
"hasCubaRelationship": null,
"hasVenezuelaRelationship": null
}
],
"lastName": "mfWKx",
"middleName": "C"
},
"termsAcceptances": [
{
"termsIdentifier": "coa",
"termsAcceptanceFlag": true,
"termsAcceptanceDateTime": "2023-09-19T03:05:05Z"
}
],
"metadata": {
"storeId": "CC970",
"merchantId": "FSCC0342",
"userId": "[email protected]",
"requestDateTime": "2023-09-19T03:06:05Z",
"registerId": "001"
}
}
Negative Request
POST {baseUrl}/registration/validate
X-GD-RequestId: 35977479313965
Content-Type: application/json
Authorization: Bearer {token}
{
"productCode":"51720",
"personData":{
"cellPhone":"6249629180",
"dateOfBirth":"2004-09-22",
"email":"[email protected]",
"firstName":"QJLkL",
"homeAddress":{
"addressLine1":"494 Peachtree Street",
"addressLine2":"SUITE 390",
"city":"Atlanta",
"countryCode":"USA",
"postalCode":"12844",
"state":"GA"
},
"homePhone":"5639410915",
"identification":[
{
"id":"107865641",
"issuerCountryCode":"USA",
"type":"SSN",
"expiryDate":"2099-09-09",
"hasCubaRelationship":null,
"hasVenezuelaRelationship":null
}
],
"lastName":"RmGro",
"middleName":"a"
},
"termsAcceptances":[
{
"termsIdentifier":"coa",
"termsAcceptanceFlag":true,
"termsAcceptanceDateTime":"2023-09-22T10:59:04Z"
}
],
"metadata":{
"storeId":"032810293123",
"merchantId":"FSCC0342",
"userId":"[email protected]",
"requestDateTime":"2023-09-22T10:59:04Z",
"registerId":"001"
}
}
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. |
| 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 | The unique merchant Id. Defined by Green Dot – Merchant corresponding with Retailer. |
| productCode | Yes | String | 4-7 digits | It is 4 digit Green Dot internal product code. E.g., 7680, 7681, 7682. New product has 5 digits typically. It’s required for BaaS card. |
| personData | Yes | object | { 1, … } | The customer data to be registered. |
| firstName | Yes | String | Max: 30 | The first name of the customer. |
| middleName | No | String | Max: 1 | The initial letter of middle name of the customer. |
| lastName | Yes | String | Max: 30 | The last name of the customer. |
| dateOfBirth | Yes | Date | YYYY-MM-DD | The customer’s birth date. Default format: YYYY-MM-DD |
| Yes | String | Max: 40 | The email address of the customer. | |
| cellPhone | Yes | String | 10 digits | The customer cell phone number. |
| homePhone | No | String | 10 digits | The customer Home phone number of the customer. |
| HomeAddress | Yes | object | { 1, … } | The address of the customer. |
| addressLine1 | Yes | String | Max: 30 | The mailing address of the customer. |
| addressLine2 | No | String | Max: 30 | Second line of address of customer |
| city | Yes | String | Max: 30 | The city in which customer resides. |
| state | Yes | String | Max: 2 | The state in which the customer city belongs to. |
| postalCode | Yes | String | Min: 5 Max:10 | Postal code of the customer address. |
| countryCode | No | String | "USA" | CountryCode in ISO 3166-1 alpha-3 format. By default it is set as “USA” if no value is provided. |
| identification | Yes | Array | { 1, … } | Array of Identification provided by the customer. |
| type | Yes | String | Min: 3 , Max: 21 | Accepted type of identification that can be provided by the user are as follows: - US IDs (Primary - SSN, ITIN) - Non-US IDs for 10 countries (Mexican Matricula, National ID, and Passports) Values can be SSN, Passport, ITIN and NationalIdCard. Note that Mexican Matricula use nationalIdCard as Type. |
| id | Yes | String | Min: 1 , Max: 50 | The unique identification number of user. For example: SSN, passport number. |
| expiryDate | No | Date | “YYYY-MM-DD" | Provided identification expiry date in “YYYY-MM-DD” format. Note that when type is “NationalIdCard” or “Passport”, the expiryDate has to be provided. |
| issuerCountryCode | Yes | String | Min: 3 | Country that issued the identification card in ISO 3166-1 alpha-3 format. Possible values are USA, COL, CUB, DOM, ECU, SLV, GTM, HND, MEX, NIC and VEN. |
| hasCubaRelationship | No | bool | true/false | It’s mandatory if IssuerCountryCode is CUB |
| hasVenezuelaRelationship | No | bool | true/false | It’s mandatory if IssuerCountryCode is VEN. |
| termsAcceptances | Yes | array | {1, …} | Sets of terms acceptance info that customer signed |
| termsIdentifier | Yes | string | Max:10 | Identifier of the terms. “coa” is mandatory. However, “daa” , “privPlcy” & “eca” are optional. |
| termsAcceptanceFlag | Yes | bool | true/false | Whether customer accepted or not |
| termsAcceptanceDateTime | Yes | datetime | YYYY-MM-ddTHH:mm:ssZ | The datetime that customer accepts the terms in UTC format. |
Example Response
Success Response
HTTP/1.1 200 OK
Content-Type: application/json
X-GD-RequestId: 201309181254
X-GD-ResponseId: d928f8bf-814a-4b63-bdee-aea9a7e5429d
X-GD-ResponseCode: 0
{
"metadata": {
"requestId": "201309181254",
"responseCode": 0,
"responseDescription": "Success",
"responseDateTime": "2013-09-18T17:53:07.1411753Z",
"responseId": "d928f8bf-814a-4b63-bdee-aea9a7e5429d"
},
"registrationToken": "2E28C3D0-A1EC-4178-A707-77AFD46D4B24",
"validateRegistrationCure": "Healthy"
}
Negative Response
HTTP/1.1 400 Bad Request
Content-Type: application/json
X-GD-RequestId: 35977479313965
X-GD-ResponseCode: 800
X-GD-ResponseId: c1e20f33-1160-43d0-8a0f-b1cc9d8a124c
{
"registrationToken":null,
"validateRegistrationCure":null,
"metadata":{
"requestId":"35977479313965",
"responseId":"c1e20f33-1160-43d0-8a0f-b1cc9d8a124c",
"responseDateTime":"2023-09-22T10:59:06.4041579Z",
"responseCode":800,
"responseDescription":"Store was not found"
}
}
Response Parameters
| Parameter | Required(Y/N) | Format/Data Type | Pattern | Description |
|---|---|---|---|---|
| requestId | Yes | String | MaxLength:50 | The unique request ID from request. |
| responseId | Yes | String | MaxLength:50 | The unique response identifier (generated by GreenDot). |
| responseDateTime | Yes | 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 | Yes | Numeric | MaxLength:4 | Indicates success and failure of the response codes. It is in the numeric format. |
| responseDescription | Yes | String | MaxLength:255 | Describes the Response Code in more detail. It is in the String format. |
| registrationToken | Yes | String | e5843e05-d367-4bf1-a223-3af46ae18802 | The unique registration identifier, which is generated by GreenDot system. It will only have value when response is success. |
| validateRegistrationCure | No | String | “IDV” “None” “Healthy” | Health of the CIP validation. Healthy/IDV/None. |
Response Cases
| Code | Code Text | Response Description | Explanation of the Response Code |
|---|---|---|---|
| 0 | Success | Success | Customer passes the registration validation and good to do card sale. |
| 100 | InvalidParameter | • CellPhone has to be 10 digits. • The Email field is not a valid e-mail address. • CountryCode has to be 3 alphabets. • The field PostalCode must be a string with a minimum length of 5 and a maximum length of 10. • The field State must be a string with a minimum length of 2 and a maximum length of 2. • HomePhone has to be 10 digits • IssuerCountryCode has to be 3 alphabets • The field ProductCode must be a string with a minimum length of 4 and a maximum length of 7. • The CellPhone field is required. • The DateOfBirth field is required. • The Email field is required. • The PostalCode field is required. • The State field is required. • The Id field is required. • The Type field is required. • StoreId is required • MerchantId is required • RequestDateTime is required • The ProductCode field is required. • The AddressLine1 field is required. • RequestId is required • UserId is required • The FirstName field is required. • The LastName field is required. • The City field is required. • The IssuerCountryCode field is required. • The TermsAcceptances field is required. • The field Id must be a string with a minimum length of 1 and a maximum length of 50. • The field AddressLine1 must be a string with a minimum length of 1 and a maximum length of 30. • RequestId is too long • UserId is too long • StoreId is too long • MerchantId is too long • The field FirstName must be a string with a minimum length of 1 and a maximum length of 30. • The field LastName must be a string with a minimum length of 1 and a maximum length of 30. • The field Email must be a string with a minimum length of 1 and a maximum length of 40. • The field AddressLine2 must be a string with a maximum length of 30. • The field MiddleName must be a string with a maximum length of 1. • The field City must be a string with a minimum length of 1 and a maximum length of 30. • The field Type must be a string with a minimum length of 3 and a maximum length of 21. • Only numbers and alphabets are allowed in Id field • Member Gov / Military Sanctioned Country • Questions required for Cuba/Venezuela gov or military • Invalid identity value | Invalid parameter when validating the request. Examples: MerchantID not supplied, StoreID not supplied, Invalid identityType. |
| 130 | InvalidMerchant | • InvalidMerchant | MerchantId in request has not been found/enabled in the system. |
| 500 | CIPFailed | • Hard decline • OFAC hard decline | Customer gets hard declined by CIP. |
| 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 in system. |
| 451 | SoftDeclineVerifyPending | • IDV soft decline | Customer gets soft declined by CIP process which is curable by uploading further IDV document in FSC IdvUpload endpoint. There’s ValidateRegistrationCure in response to indicate which cure customer can perform. |
| 453 | CustomerHasSsn | • Customer has SSN | CIP check result indicates customer has SSN but not use it to register. Customer may use SSN to submit registration again. |
| 600 | UnableToProcessRequest | • The product code XXXXX is unknown for this program code. • DOB is invalid, the minimum age must be 18. • The termsAcceptanceDateTime is either in the future or not a recent date. • TermsAcceptanceDateTime is not a valid UTC date/time. • dateOfBirth must be between Jan. 1, 1901 and today. • Required terms were not accepted. • Fail | Non-CIP error happens when processing presignup. |
| 1000 | GeneralFailure | • GeneralFailure | Service failure/unexpected exception in system |
Updated 16 days ago