ValidateCardForUnload API Method

This operation validates the below and is used to check if the account is unload-able when customer provides card details and unload amount.
• If card is Green Dot Card (Non-GD card is not allowed)
• If status of the account/card is healthy.
• If validateAmount is true, system will do balance & limit check.

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

Syntax

POST {baseUrl}/unload/validate/card

Example Request

Success Request

POST {baseUrl}/unload/validate/card
Authorization: bearer {token}
Content-Type: application/json
X-GD-RequestId: test101
{
    "metadata": {
        "merchantId": "fscc0342",
        "registerId": "01",
        "requestDateTime": "2023-10-11T07:25:43Z",
        "storeId": "CC970",
        "userId": "[email protected]"
    },
    "accountNumber": "",
    "transactionAmount": 50.00,
    "validateAmount": true,
    "accountIdentifier": "007f8f2d-f1be-49c1-b029-ef6dcc902006"    
}

Negative Request

POST {baseUrl}/unload/validate/card
Authorization: bearer {token}
Content-Type: application/json
X-GD-RequestId: test101
{
    "metadata": {
        "merchantId": "fscc0342",
        "registerId": "01",
        "requestDateTime": "2023-12-11T06:16:06",
        "storeId": "CC970",
        "userId": "[email protected]"
    },
    "accountNumber": "",
    "transactionAmount": 40000.00,
    "validateAmount": true,
    "accountIdentifier": "007f8f2d-f1be-49c1-b029-ef6dcc902006"    
}

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 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.
accountNumber	No	String	16 digits PAN	Account Number (PAN) of the card. If accountIdentifier is supplied this value should be empty. If AccountNumber and accountIdentifier both supplied, system will use accountNumber. Note: Either AccountNumber or AccountIdentifier is required
transactionAmount	Yes	Decimal	500.00	Amount of money to be unload. Must be greater than zero. For example: Five Hundred Dollars is entered as 500.00. Twenty Dollars is entered as 20.00.
validateAmount	Yes	Bool	true or false	True: system checks if there is enough amount and if it pass the unload limit check. False: system skips the balance & limit checking.
accountIdentifier	No	GUID	e5843e05-d367-4bf1-a223-3af46ae18802	Newly created unique identifier for sale card, should be using for all subsequent API calls Note: Either AccountNumber or AccountIdentifier is required

Example Response

Success Response

HTTP/1.1 200 OK
Content-Type: application/json
X-GD-RequestId: test101
X-GD-ResponseId: 9c3bd050-9c6b-4d87-8029-26a480c22eb7
X-GD-ResponseCode: 0
{
    "balance": "380.00",
"unloadFee": null,
"maxAllowedAmount": null,
    "metadata": {
        "requestId": "test101",
        "responseId": "9c3bd050-9c6b-4d87-8029-26a480c22eb7",
        "responseDateTime": "2023-10-11T07:25:46.3031642Z",
        "responseCode": 0,
        "responseDescription": "Success"
    }
}

Negative Response

HTTP/1.1 200 OK
Content-Type: application/json
X-GD-RequestId: test101
X-GD-ResponseId: be8e4cf4-1698-46dd-9e35-ed15fc3d6ba6
X-GD-ResponseCode: 700
{
    "balance": "44801.19",
"unloadFee": null,
"maxAllowedAmount": "24990.00",
    "metadata": {
    "requestId": "test101",
    "responseId": "be8e4cf4-1698-46dd-9e35-ed15fc3d6ba6",
    "responseDateTime": "2023-12-11T06:16:10.5019499Z",
    "responseCode": 700,
    "responseDescription": "Exceeds account daily unload limit"
    }
}

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.
balance	Yes	String	50.00	Current available balance in main account purse. If it fails basic validation like metadata value validation or account not found, this field will be null.
unloadFee	Yes	String	50.00	Fee for unload. If there’s no fee at GD side, no value(null) will be returned.
maxAllowedAmount	Yes	String	“370.00”	The max amount allowed to perform the unload based on load limit check. If ValidateAmount is false, no value will be returned.

Response Cases

Code	CodeText	Response Description	Description
0	Success		Success.
100	InvalidParameter	• RequestId is required • UserId is required • RequestDateTime is required • StoreId is required • MerchantId is required • RequestId is too long • UserId is too long • StoreId is too long • MerchantId is too long • Either AccountNumber or AccountIdentifier is required • TransactionAmount should be greater than zero • TransactionAmount is required. • The ValidateAmount field is required. • The field RegisterId must be a string or array type with a maximum length of '20'. • Invalid length of AccountNumber • Either AccountNumber or AccountIdentifier is required	Invalid parameter in the request. Examples: MerchantID not supplied, StoreID not supplied.
130	InvalidMerchant	InvalidMerchant	MerchantId in request has not been found/enabled in the system.
800	InvalidStore	• Store feature is invalid • Store was not found • Block by Store Hierarchy setting	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.
700	LoadLimitValidationFailed	• Exceeds account daily unload limit • Exceeds account monthly unload limit • Unload amount of Non-active initial card should equal to available balance. • The account has insufficient funds to execute the transfer.	Per transaction, account balance, daily account reload limit reached or insufficient fund on account.
110	InvalidAccountNumber	• ProgramCode does not match the card • AccountStatus is Closed. • AccountStatus is Pending. • AccountStatus is Locked. • Account Status is Restricted • Account Not Found. • AccountNotFound	Account is not found, account status is not valid or account is not unloadable
600	UnableToProcessRequest		Unable to process request due to downstream errors.
1000	GeneralFailure	GeneralFailure	Service failure.