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.


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}

        "email":"[email protected]",
            "addressLine1":"494 Peachtree Street",
            "addressLine2":"SUITE 390",
        "userId":"[email protected]",

Request Parameters

ParameterRequired(Y/N)Format/Data TypePatternDescription
X-GD-RequestIdYesStringMaxLength:50It is a unique transaction identifier that is generated by the retailer.
requestDateTimeYesDateTime2023-08-08T12:34:56ZTime stamp at which transaction occurred.
The time stamp has to be in UTC time zone and follow the following date and time formats:

registerIdNoStringMaxLength: 20Register where the transaction occurred.
userIdYesStringMaxLength:50The unique ID of the user generating the transaction.
storeIdYesStringMaxLength: 20The store number associated with the retailer that sold the package.
If not supplied, InvalidParameter (Code:100) error will be return.
merchantIdYesStringMaxLength: 20The unique merchant Id. Defined by Green Dot – Merchant corresponding with Retailer.
productCodeYesString4-7 digitsIt 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.
personDataYesobject{ 1, … }The customer data to be registered.
firstNameYesStringMax: 30The first name of the customer.
middleNameNoStringMax: 1The initial letter of middle name of the customer.
lastNameYesStringMax: 30The last name of the customer.
dateOfBirthYesDateYYYY-MM-DDThe customer’s birth date.
Default format: YYYY-MM-DD
emailYesStringMax: 40The email address of the customer.
cellPhoneYesString10 digitsThe customer cell phone number.
homePhoneNoString10 digitsThe customer Home phone number of the customer.
HomeAddressYesobject{ 1, … }The address of the customer.
addressLine1YesStringMax: 30The mailing address of the customer.
addressLine2NoStringMax: 30Second line of address of customer
cityYesStringMax: 30The city in which customer resides.
stateYesStringMax: 2The state in which the customer city belongs to.
postalCodeYesStringMin: 5 Max:10Postal code of the customer address.
countryCodeNoString"USA"CountryCode in ISO 3166-1 alpha-3 format.
By default it is set as “USA” if no value is provided.
identificationYesArray{ 1, … }Array of Identification provided by the customer.
typeYesStringMin: 3 , Max: 21Accepted 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.
idYesStringMin: 1 , Max: 50The unique identification number of user. For example: SSN, passport number.
expiryDateNoDate“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.
issuerCountryCodeYesStringMin: 3Country 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.
hasCubaRelationshipNobooltrue/falseIt’s mandatory if IssuerCountryCode is CUB
hasVenezuelaRelationshipNobooltrue/falseIt’s mandatory if IssuerCountryCode is VEN.
termsAcceptancesYesarray{1, …}Sets of terms acceptance info that customer signed
termsIdentifierYesstringMax:10Identifier of the terms. “coa” is mandatory. However, “daa” , “privPlcy” & “eca” are optional.
termsAcceptanceFlagYesbooltrue/falseWhether customer accepted or not
termsAcceptanceDateTimeYesdatetimeYYYY-MM-ddTHH:mm:ssZThe 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
        "responseDescription":"Store was not found"

Response Parameters

ParameterRequired(Y/N)Format/Data TypePatternDescription
requestIdYesStringMaxLength:50The unique request ID from request.
responseIdYesStringMaxLength:50The unique response identifier (generated by GreenDot).
responseDateTimeYesDateTime2023-09-07T16:12:23.4541445+08:00Time stamp at which transaction occurred.
The time stamp is in UTC time zone and follow the following date and time formats:

responseCodeYesNumericMaxLength:4Indicates success and failure of the response codes. It is in the numeric format.
responseDescriptionYesStringMaxLength:255Describes the Response Code in more detail. It is in the String format.
registrationTokenYesStringe5843e05-d367-4bf1-a223-3af46ae18802The unique registration identifier, which is generated by GreenDot system. It will only have value when response is success.
Health of the CIP validation. Healthy/IDV/None.

Response Cases

CodeCode TextResponse DescriptionExplanation of the Response Code
0SuccessSuccessCustomer passes the registration validation and good to do card sale.
100InvalidParameter• 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.
130InvalidMerchant• InvalidMerchantMerchantId in request has not been found/enabled in the system.
500CIPFailed• Hard decline
• OFAC hard decline
Customer gets hard declined by CIP.
800InvalidStore• Store was not foundStore is not found; store is not for the partner or store does not support this operation.
861RetailChainUserNotFound• User is not found.UserID in request is not found in system.
862RetailChainUserNotActive• User is not active.UserId in request is not active in system.
451SoftDeclineVerifyPending• IDV soft declineCustomer 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.
453CustomerHasSsn• Customer has SSNCIP check result indicates customer has SSN but not use it to register. Customer may use SSN to submit registration again.
600UnableToProcessRequest• 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.
1000GeneralFailure• GeneralFailureService failure/unexpected exception in system