API Reference

Overview

The BaaSReferralGateway exposes three endpoints. All paths are appended to the Base URL provided by Green Dot for the target environment.

Client timeout: Set your HTTP client timeout to at least 35 seconds on all requests.

Enrollment API

Creates a Green Dot customer account, issues a virtual card, and runs KYC/OFAC - all in a single synchronous call. Physical card issuance is a separate, subsequent call.

Endpoint

POST {BASE_URL}/programs/{PROGRAM_CODE}/enrollment

Required role: ENROLLMENT

Required Flags

• requestPhysicalCardFlag - must be false. Physical card ordering is a separate call.
• executeKycFlag - must be true. KYC is always performed.

PII Encryption

All customer PII is sent encrypted inside user.encryptedUserData.data. Non-PII control fields are sent in plaintext.

Green Dot provides an EC public key per environment. The partner:

1. Builds the PII JSON payload (see PII Payload below).
2. Serializes it as a string.
3. Encrypts it using Green Dot's EC public key (EC_v1 / ECIES).
4. Base64-encodes the result and places it in encryptedUserData.data.
5. Provides the ephemeral public key and public key hash generated during encryption.

Request Body

{
  "user": {
    "encryptedUserData": {
      "version": "EC_v1",
      "ephemeralPublicKey": "{string}",
      "publicKeyHash": "{string}",
      "data": "{base64-encrypted-pii-payload}"
    }
  },
  "account": {
    "productCode": "{PRODUCT_CODE}",
    "productMaterialType": "{PRODUCT_MATERIAL_TYPE_VIRTUAL}",
    "currency": "USD",
    "termsAcceptances": [
      {
        "termsIdentifier": "{TERMS_IDENTIFIER}",
        "termsAcceptanceFlag": true,
        "termsAcceptanceDateTime": "2024-04-15T10:30:00.000Z"
      }
    ],
    "fraudData": {
      "IpAddress": "{customer_ip_address}"
    }
  },
  "requestPhysicalCardFlag": false,
  "executeKycFlag": true
}

PII Payload

Serialize this JSON object as a string, then encrypt it using Green Dot's EC public key before placing the result in encryptedUserData.data.

{
  "profileData": {
    "firstName": "John",
    "middleName": "Smith",
    "lastName": "Robert",
    "addresses": [
      {
        "type": "home",
        "isDefault": true,
        "addressLine1": "15777 Foothill Blvd",
        "addressLine2": "SUITE 560",
        "city": "Pasadena",
        "state": "CA",
        "zipCode": "91107",
        "isVerified": true
      }
    ]
  },
  "identifyingData": {
    "ssn": "XXXXXXXXX",
    "ssnSuffix": "",
    "dateOfBirth": "YYYY-MM-DD"
  },
  "email": {
    "emailAddress": "[email protected]",
    "isDefault": true,
    "isVerified": true
  },
  "phoneNumbers": [
    {
      "number": "XXXXXXXXXX",
      "type": "mobile",
      "isDefault": true,
      "isVerified": true
    }
  ]
}

PII Field Rules

Name Fields

Address Fields

Identity Fields

Contact Fields

Terms Acceptances

The termsAcceptances array must include all terms required for your product. Green Dot confirms the exact required list during product setup.

Known Terms Identifier Values

The exact required terms for your product code will be confirmed by Green Dot during product setup.

termsAcceptanceDateTime Format

Must be ISO 8601 UTC with fractional seconds ending in Z. Accepted formats:

yyyy-MM-ddTHH:mm:ssZ
yyyy-MM-ddTHH:mm:ss.SZ
yyyy-MM-ddTHH:mm:ss.SSZ
yyyy-MM-ddTHH:mm:ss.SSSZ

Valid examples:

• "2024-04-15T10:30:00.000Z" ✅
• "2024-04-15T10:30:00.0Z" ✅

Invalid examples:

• "2024-04-15T10:30:00" ❌ - missing Z and fractional seconds
• "2024-04-15T10:30:00.000" ❌ - missing Z

The datetime must be within ±720 hours of the server's current time. Outside that window → error 620/0. Unparseable format → error 720/0.

Fraud Data

Green Dot will advise if additional fraud fields are required during onboarding.

Enrollment Success Response (HTTP 201)

{
  "responseDetails": [
    {
      "code": 0,
      "subCode": 0,
      "description": "API operation was successful.",
      "url": "http://tbd"
    }
  ],
  "account": {
    "accountIdentifier": "f096a92e-a7e9-4d66-8fc6-c3ee99227d59",
    "accountReferenceNumber": "ACCJ2530733",
    "status": "normal",
    "accountStatusChangedDateTime": "2024-07-03T03:08:36.933Z",
    "statusReasons": ["healthy"],
    "directDepositInformation": {
      "accountNumber": "15101332927074",
      "routingNumber": "124303162"
    },
    "purses": [
      {
        "purseIdentifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "purseType": "primary",
        "availableBalance": 0.0000,
        "ledgerBalance": 0.0000,
        "status": "active"
      }
    ],
    "accountHolders": [
      {
        "user": {
          "userIdentifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "status": "active",
          "isPrimaryAccountHolder": true,
          "kycStateData": {
            "ofacStatus": "passed",
            "kycStatus": "passed",
            "kycPendingGate": "healthy"
          }
        },
        "accountHolderIdentifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "paymentInstruments": [
          {
            "paymentInstrumentIdentifier": "9b0dbe09-6e98-4488-bde7-52828aa4b324",
            "paymentInstrumentType": "virtual",
            "status": "activated",
            "isPinSet": false,
            "last4Pan": "****",
            "encryptedPrivatePaymentInstrumentData": {
              "version": "EC_v1",
              "ephemeralPublicKey": "string",
              "publicKeyHash": "string",
              "data": "string"
            }
          }
        ]
      }
    ]
  }
}

Fields to Persist

You must store these values from the enrollment response - both are required for the Order Card call:

Idempotency

The Enrollment API uses X-GD-RequestId as an idempotency key. If you re-submit an enrollment request with the same X-GD-RequestId as a previous KYC/OFAC failure, the response kycStateData fields will return zeros rather than the original failure values. The responseDetails code and subcode will still reflect the original result.

Important: Always generate a fresh UUID for new enrollment attempts. Reusing an X-GD-RequestId from a failed request is not a retry mechanism.

Enrollment Error Codes

Errors are returned in responseDetails[0] as code / subCode. Check both the HTTP status and the code field - some non-zero codes are returned with HTTP 200 or HTTP 201.

Warning: Do not treat HTTP 201 as unconditional success. A 201 response with a non-zero code indicates a KYC/OFAC decline. Always inspect responseDetails[0].code.

KYC / Identity Verification Results

For tax-season referral partner products, KYC and OFAC failures result in a permanent hard decline. There is no identity verification step-up, document upload, or cure action available through this API.

Full Error Code Catalog

Order Card API

Orders a physical EMV card for a customer whose account was created via the Enrollment API. Physical card issuance is intentionally decoupled from enrollment — the partner calls this API when their business trigger occurs.

Endpoint

PUT {BASE_URL}/programs/{PROGRAM_CODE}/lifecycleEvent

Required role: ORDERCARD

When to Call

There is no minimum or maximum time window between enrollment and Order Card. For tax referral partners, this call is typically made when the IRS accepts the customer's tax filing - which may be days or weeks after enrollment.

10-day dedup window: Once an Order Card call succeeds for an account, a second call for that same account within 10 days is rejected with code 4 / subCode 308. There is no maximum deadline - the call is accepted whenever it arrives.

Request Body

{
  "accountIdentifier": "{accountIdentifier from enrollment response}",
  "paymentInstrumentIdentifier": "{paymentInstrumentIdentifier from enrollment response}",
  "lifeCycleEventType": "replacement",
  "productMaterialType": "{PRODUCT_MATERIAL_TYPE_EMV}",
  "replaceReason": "initialPhysicalCard"
}

Request Fields

Success Response (HTTP 200)

{
  "responseDetails": [
    {
      "code": 0,
      "subCode": 0,
      "description": "API operation was successful.",
      "url": "http://tbd"
    }
  ]
}

No additional fields are returned on success. Green Dot does not provide an order ID or card tracking token in this response.

Order Card Error Codes

Important: All Order Card errors - including account and card state rejections - are returned with HTTP 200 and a non-zero code. Do not treat an HTTP 200 response as unconditional success - always check responseDetails[0].code.

Health Check

Verifies connectivity to the BaaSReferralGateway and its downstream services. Use this endpoint before running integration tests.

Endpoint

GET {BASE_URL}/healthcheck

No Bearer token required. X-GD-RequestId is still required. Use X-Program-Code in PROD to route the probe to the correct program's downstream services.

Response (HTTP 200 — healthy)

{
  "responseDescription": "Health Check Completed.",
  "status": "OK",
  "totalTime": "1873.0287",
  "healthCheck": [
    { "serviceName": "Service1", "status": "OK", "totalTime": "650.5256" },
    { "serviceName": "Service2", "status": "OK", "totalTime": "593.6144" },
    { "serviceName": "Service3", "status": "OK", "totalTime": "532.6803" },
    { "serviceName": "Service4", "status": "OK", "totalTime": "96.1526" }
  ],
  "responseDetails": [
    { "code": 0, "subCode": 0, "description": "Success", "url": "http://tbd" }
  ]
}

A degraded status on any individual service indicates a partial outage affecting that component only.

Error Handling Recommendations

Always Check responseDetails[0].code

The HTTP status code alone is not sufficient to determine success or failure:

• Some enrollment failures return HTTP 201 with a non-zero code (KYC/OFAC declines).
• All Order Card errors return HTTP 200 with a non-zero code.
• Always read responseDetails[0].code and responseDetails[0].subCode on every response.

Retry Strategy

Partner Implementation Checklist

• Receive Azure AD clientId and clientSecret from Green Dot for each environment
• Implement OAuth 2.0 client credentials token acquisition with caching and auto-refresh
• Receive Green Dot EC public key per environment
• Implement EC_v1 PII encryption using GD public key
• Generate a unique X-GD-RequestId (UUID) on every request
• Build the Enrollment request with all required fields and correct termsAcceptances
• Persist accountIdentifier and paymentInstrumentIdentifier per customer after enrollment
• Confirm terms identifiers with Green Dot and validate the datetime format
• Implement the Order Card call with the business trigger condition
• Handle HTTP 200 responses with non-zero code - do not treat as success
• Implement retry and error handling for 400 and 503 responses
• Verify connectivity using the /healthcheck endpoint before testing
• Set HTTP client timeout to at least 35 seconds

Appendix A - Valid Characters and Address Rules

Name Fields (firstName, middleName, lastName)

Unicode is not allowed. Accepted values are ASCII range 32–126, excluding:
33–38, 40–43, 47, 58–64, 91–96, 123–126

Street and City Fields (addressLine1, addressLine2, city)

Unicode is not allowed. Accepted values are ASCII range 32–126 and 192–255, excluding:
33–34, 36–37, 42–43, 58–64, 91–96, 123–126, 215, 217–220, 247

PO Box Rejection

PO Box detection applies to addressLine1, addressLine2, and city. A broad pattern of common variants is rejected:

PO Box, P.O. Box, POB, POBOX, Post Office Box, Box NNN, General Delivery, Drawer, Caller, Lockbox, PMB, and deliberate obfuscation variants (e.g., p0 box, po-box).

Allowed exceptions (legitimate addresses that match PO Box patterns): Army Post Office (APO), Fleet Post Office (FPO), Diplomatic Post Offices, PSC N Box N, RR N Box N, and street names such as Box Hill, Box Canyon, Box Street, Post Oak, and Postal Road.

State Codes

State must be exactly 2 uppercase ASCII characters. Accepted values:

50 U.S. States + DC:

AL AK AZ AR CA CO CT DE DC FL GA HI ID IL IN IA KS KY LA ME
MD MA MI MN MS MO MT NE NV NH NJ NM NY NC ND OH OK OR PA RI
SC SD TN TX UT VT VA WA WV WI WY

U.S. Territories (also accepted):

PR  (Puerto Rico)
VI  (U.S. Virgin Islands)
GU  (Guam)
AS  (American Samoa)
MP  (Northern Mariana Islands)

Military APO/FPO codes (also accepted):

AA  (Americas)
AE  (Europe / Middle East / Africa)
AP  (Pacific)

Canadian province codes (AB, BC, ON, etc.) and any other two-letter code not listed above are rejected with error 1042/31003.

ZIP Code Rules

• Format: XXXXX (5 digits) or XXXXX-XXXX (ZIP+4). Both are accepted.
• The ZIP must correspond to the state field. A mismatch with the state (or its bordering states) returns 1042/31006.
• If state is omitted, the state is inferred from the ZIP prefix. If the prefix maps to multiple states, error 1042/31009 is returned - include the state field to resolve.
• Unrecognized ZIP prefixes return 1042/31008.