Barcode / eCash API

This section covers endpoints for accepting cash payments at retail POS using a customer's barcode. Barcodes are scanned at the register and can be used to load funds onto a card account or to make a cash payment toward an eCommerce order, utility bill, loan, rent, or similar obligation.

The typical integration flow is:

Get Barcode Details — Validate the barcode and retrieve fee and limit information before presenting the transaction to the customer.
Barcode Payment — Commit the cash deposit or payment.

Note: Every request must include a unique X-GD-RequestId header value.

Get Barcode Details

Validates a cash deposit using a barcode prior to initiating the transaction. Returns fee, limit, and balance information to display to the customer before proceeding.

Syntax:

POST {baseUrl}/barcode/details

Request

POST {baseUrl}/barcode/details
Authorization: Bearer {access_token}
Content-Type: application/json
X-GD-RequestId: req-20260115-bcd001

{
  "metadata": {
    "storeId": "STORE-0042",
    "merchantId": "MRC-20001",
    "registerId": "REG-01",
    "userId": "[email protected]",
    "requestDateTime": "2026-01-15T12:00:00Z"
  },
  "barcode": "748291039485729301847562930148",
  "transactionAmount": "75.00",
  "paymentProgramType": "Regular"
}

Request Parameters

Parameter	Required	Type	Pattern	Description
`X-GD-RequestId`	Yes	String	Max: 50	Unique transaction identifier generated by the retailer. Passed as HTTP header.
`requestDateTime`	Yes	DateTime	`YYYY-MM-DDTHH:MM:SSZ`	UTC timestamp of the transaction.
`storeId`	Yes	String	Max: 20	Store number for the location where the transaction occurred.
`merchantId`	Yes	String	Max: 20	Unique merchant ID assigned by Green Dot.
`registerId`	No	String	Max: 20	Register identifier at the store.
`userId`	No	String	Max: 50	Unique ID of the user performing the transaction.
`barcode`	Yes	String	Max: 30	The customer's barcode. Accepts the full 30-digit barcode or the last 19 digits.
`transactionAmount`	No	Decimal	e.g. `75.00`	Amount of cash to be deposited. Must be greater than zero if provided.
`paymentProgramType`	Yes	Enum	`Regular`, `CheckCashing`	Payment option selected by the customer. Use `CheckCashing` when the customer is paying with a check.

Response

Successful Response

HTTP/1.1 200 OK
X-GD-ResponseId: a2b3c4d5-e6f7-8901-abcd-ef0123456789

{
  "requestId": "req-20260115-bcd001",
  "responseId": "a2b3c4d5-e6f7-8901-abcd-ef0123456789",
  "responseCode": 0,
  "responseDescription": "Success",
  "responseDateTime": "2026-01-15T12:00:07.9632687Z",
  "reloadFee": "3.95",
  "merchantFee": "2.00",
  "availableBalance": "50.00",
  "maxAllowedAmount": "9500.00",
  "minAllowedAmount": "20.00",
  "fixedAllowedAmount": null
}

Response Parameters

Parameter	Required	Type	Pattern	Description
`requestId`	Yes	String	Max: 50	Echo of the `X-GD-RequestId` from the request header.
`responseId`	Yes	String	UUID	Unique response identifier generated by Green Dot.
`responseCode`	Yes	Numeric	0–1000	Success/failure code. See Response Codes.
`responseDescription`	Yes	String	Max: 255	Human-readable description of the response code.
`responseDateTime`	Yes	DateTime	YYYY-MM-DDTHH:mm:ss.fffffffZ	UTC timestamp of the response.
`reloadFee`	Yes	Decimal	e.g. `"3.95"`	Fee charged to the customer for this transaction. Returned when all validations except load limits pass.
`merchantFee`	Yes	Decimal	e.g. `"2.00"`	Fee credited to the merchant for this transaction. Returned when all validations except load limits pass.
`availableBalance`	No	String	e.g. `"150.00"`	Available balance on the account linked to the barcode. Returned only for accounts under the requesting partner's program.
`maxAllowedAmount`	No	String	e.g. `"9500.00"`	Maximum amount allowed based on load limit rules. Returned when load limit check is applicable.
`minAllowedAmount`	No	String	e.g. `"20.00"`	Minimum amount allowed based on load limit rules. Returned when load limit check is applicable.
`fixedAllowedAmount`	No	Decimal	e.g. `"20.00"`	If the barcode only supports a fixed transaction amount, this field returns that amount.

Response Codes

Code	Code Text	Response Description	Explanation
0	Success	Success	Request processed successfully.
100	InvalidParameter	(See description)	Invalid parameter in the request. Examples: MerchantId not supplied, StoreId not supplied.
110	InvalidAccount	(See description)	The account linked to the barcode is not found, status is not valid, or is not reloadable for this partner.
130	InvalidMerchant	Invalid Merchant	MerchantId not found or not enabled.
140	InvalidBarcode	(See description)	Barcode not found or barcode status is not valid. Possible statuses: Pending Consumption, Already Consumed, Declined, Voided, Expired.
600	UnableToProcessRequest	—	Unable to process due to fee split not configured or downstream error.
700	LoadLimitValidationFailed	(See description)	Transaction amount does not pass load limit validation.
800	InvalidStore	Store was not found	Store not found, not associated with this partner, or does not support this operation.
801	StoreBlocked	The store is blocked	Store blocked by Green Dot store blocker rules.
999	RequestTimeout	Request Timeout	Request expired or no downstream response received.
1000	GeneralFailure	—	Service failure.

Barcode Payment

Deposits cash to a Green Dot or Green Dot Partner Card account, or makes a cash payment toward an eCommerce order, utility bill, loan, rent, or similar obligation using a customer's barcode. Call Get Barcode Details first to validate the barcode and retrieve fee information before initiating this request.