Getting Started - Retail API

Environments and Base URL

All Retail API requests use a versioned base URL. The {env} prefix determines the target environment.

Base URL: https://{env}-fscpartner-apim.go2bankonline.com/fscpartner/v1

Environment	`{env}` Value	Host
Production	`prod`	`prod-fscpartner-apim.go2bankonline.com`
Pre-Production (PIE)	`pie`	`pie-fscpartner-apim.go2bankonline.com`

PIE (Partner Integration Environment) is the recommended environment for integration development and testing. It mirrors the current production environment throughout Green Dot's development cycle, with the exception of the final week before each release.

IP Allowlisting: Access to the Retail API requires that your server's IP address be allowlisted by Green Dot. Submit your egress IP addresses to your Green Dot account manager before beginning integration work.

Authentication

The Retail API uses OAuth 2.0 Client Credentials flow via the Microsoft identity platform. All authentication credentials are provisioned by Green Dot during onboarding.

Step 1 — Generate an Access Token

Request a Bearer token from the Microsoft OAuth endpoint using your client credentials.

Request format:

POST login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&client_secret={client_secret}&grant_type=client_credentials&scope={scope}

Example request:

POST https://login.microsoftonline.com/a1b2c3d4-e5f6-7890-abcd-ef1234567890/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=b2c3d4e5-f6a7-8901-bcde-f12345678901
&client_secret=xK8mPqR2~NvBwYt7LCjZ91Ds3uGhFnXaVe3pQr4
&grant_type=client_credentials
&scope=api%3A%2F%2Ff3e4d5c6-b7a8-9012-cdef-123456789012%2F.default

Token Request Parameters

Parameter	Required	Type	Max Length	Description
`tenant_id`	Yes	String	255	Authentication domain. Provided by Green Dot.
`client_id`	Yes	String	255	ID associated with your account. Provided by Green Dot.
`client_secret`	Yes	String	255	Secret associated with your account. Provided by Green Dot.
`scope`	Yes	String	255	Scope for this authentication request, specific to the Retail API. Provided by Green Dot.
`grant_type`	Yes	String	255	Must be set to `client_credentials`.

Successful Token Response

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "ext_expires_in": 3599,
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhcGktY2xpZW50IiwiYXVkIjoiZjNlNGQ1YzYtYjdhOC05MDEyLWNkZWYtMTIzNDU2Nzg5MDEyIn0.<signature>"
}

Field	Required	Type	Description
`token_type`	Yes	String	Always `Bearer`.
`expires_in`	Yes	Numeric	Token validity in seconds.
`ext_expires_in`	Yes	Numeric	Extended lifetime indicator; used for resiliency during token service outages.
`access_token`	Yes	String	The Bearer token to include in subsequent API calls.

Token Error Response

{
  "error": "invalid_client",
  "error_description": "Client authentication failed.",
  "error_codes": [70011],
  "timestamp": "2026-01-15 12:00:00Z",
  "trace_id": "a1b2c3d4-efab-5678-cdef-ab9876543210",
  "correlation_id": "d4c3b2a1-bafe-8765-fedc-ab6789012345"
}

Field	Required	Type	Description
`error`	Yes	String	Error code string for classifying the error type.
`error_description`	Yes	String	Human-readable error message to help identify root cause.
`error_codes`	No	Numeric Array	STS-specific error codes for diagnostics.
`timestamp`	Yes	String	When the error occurred.
`trace_id`	Yes	String	Unique request identifier for diagnostics.
`correlation_id`	Yes	String	Unique identifier for tracing the request across components.

Authentication Error Codes

Error Code	Description	Resolution
`invalid_request`	Protocol error — missing required parameter.	Fix and resubmit. Typically a development-time error.
`unauthorized_client`	Client application not permitted to request a token.	Verify the client is registered and configured in Azure AD.
`invalid_client`	Client authentication failed.	Verify `client_id` and `client_secret` are correct.
`invalid_scope`	Requested scope is invalid or malformed.	Fix and resubmit. Typically a development-time error.
`invalid_resource`	Target resource in the scope does not exist or is not configured.	Verify the resource is configured in Azure AD.
`server_error`	Unexpected server-side error.	Retry. May be transient.
`temporarily_unavailable`	Server too busy to handle the request.	Retry with backoff.

Reference documentation:

Step 2 — Use the Token in API Requests

Include the access token as a Bearer token in the Authorization header of every API call that requires authentication.

Authorization: Bearer {access_token}

Example:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhcGktY2xpZW50In0.<signature>

Token expiration: If a token is invalid, expired, or issued for a different application, the API returns HTTP 401 Unauthorized with no response body. No detail about the specific failure reason is provided. Regenerate your token and retry.

Standard Metadata

Every API request (except Ping) requires metadata that identifies the retail location and operator. How metadata is passed depends on the HTTP verb:

GET requests — Pass metadata as HTTP headers, each prefixed with X-GD-.
POST/PUT requests — Pass metadata in the request body under a metadata object.

The X-GD-RequestId header must always be passed in the HTTP header for all request types.

Metadata Parameters

Parameter	Required	Type	Max Length	Description
`X-GD-RequestId`	Yes	String	50	Unique transaction identifier generated by the retailer. Must be unique per request. Always passed as an HTTP header.
`requestDateTime`	Yes	DateTime	—	UTC timestamp of the transaction. Format: `YYYY-MM-DDTHH:MM:SSZ`
`storeId`	Yes	String	20	Store number for the retail location where the transaction occurred.
`merchantId`	Yes	String	20	Unique merchant ID assigned by Green Dot.
`registerId`	No	String	20	Register identifier at the store where the transaction occurred.
`userId`	No	String	50	Unique ID of the user (cashier/operator) performing the transaction.

GET Request — Header Example

GET {baseUrl}/system/ping
Authorization: Bearer {access_token}
X-GD-RequestId: req-20260115-abc123
X-GD-StoreId: STORE-0042
X-GD-MerchantId: MRC-20001
X-GD-RegisterId: REG-01
X-GD-UserId: [email protected]
X-GD-RequestDateTime: 2026-01-15T12:00:00Z

POST Request — Body Metadata Example

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

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

Standard Response Envelope

All API responses return a consistent set of base fields:

{
  "requestId": "req-20260115-abc123",
  "responseId": "f8e7d6c5-b4a3-2190-fedc-ba9876543210",
  "responseCode": 0,
  "responseDescription": "Success",
  "responseDateTime": "2026-01-15T12:00:07.4411753Z"
}