Standard Metadata

Standard Metadata Overview

Metadata about the retail location must be provided with each API call, except for the PingCheck API call.

If it’s a GET request. All the metadata should be passed in header. Other request like POST/PUT, the metadata will be set in request body. NOTE: RequestId should only be passed in the header with prefix “X-GD-” for all requests.

Metadata via API Headers (Get Verbs)

When passed as HTTP headers each parameter must be prefixed with “X-GD-“. Below is an example of a call including the HTTP headers. NOTE: For GET endpoints, metadata should be passed in the HTTP headers

GET {baseUrl}/XXXX/XXX
Accept: application/json
X-GD-RequestId: 123456789
X-GD-MerchantId: FSCC0342
X-GD-RegisterId: 01001
X-GD-StoreId: CC970
X-GD-UserId: [email protected]
X-GD-RequestDateTime: 2023-09-18T10:53:07Z

Metadata via Request body payload (POST, PUT Verbs)

The meta data can also be passed in the request body, metadata element. Below is an example of a call using metadata in the request body. NOTE: For POST endpoints, metadata should be passed in the body.

POST {baseUrl}/XXXX/XXX
Content-Type: application/json
X-GD-RequestId: 123456789

{
    "metadata": {        
        "merchantId": "FSCC0342",
        "registerId": "01001",
        "storeId": "CC970",
        "userId": "[email protected]"
        "requestDateTime": "2013-09-18T10:53:07Z"
            },
    ... {remainder of payload}
}

Request Parameters


ParameterRequired (Y/N)Format/Data TypePatternDescription
X-GD-RequestIdYesStringMaxLength:50The unique request ID generated from 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:

YYYY-MM-DDTHH:mm:ssZ
registerIdNoStringMaxLength: 20The unique register ID,where the transaction has occurred.
userIdYesStringMaxLength:50It is a unique ID of the user performing 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: 20Unique merchant Id. It is defined by Green Dot – Merchant corresponding with Retailer.

Metadata Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
"metadata": {
     "requestId": "201309181254",
     "responseCode": 0, 
     "responseDescription": "Success",
     "responseDateTime": "2013-09-18T17:53:07.1411753Z",
     "responseId": "583775d2-78d6-4735-8fed-e02a2c35bf51"
},
       …{remainder of payload}
}

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:
YYYY-MM-DDTHH:mm:ssfffffffK
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.