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.

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:

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.