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

Parameter	Required (Y/N)	Format/Data Type	Pattern	Description
X-GD-RequestId	Yes	String	MaxLength:50	The unique request ID generated from 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	The unique register ID,where the transaction has occurred.
userId	Yes	String	MaxLength:50	It is a unique ID of the user performing 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	Unique 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

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.