Before You Begin

This page covers everything that has to be in place before your first API call, and the one
decision that shapes the rest of your integration: which disbursement flow to build.

Program setup

Program setup is handled by your Green Dot onboarding team. It is not an API call, and it is a
prerequisite for everything else.

During onboarding you receive:

Your onboarding team also confirms which recipient data fields are required for your program.
Minimum data requirements vary by program type and use case, so treat your program onboarding
documentation as authoritative on that point.

IP allowlisting

Before you can reach the APIs in any environment, Green Dot must allowlist your development and
production IP address ranges. Submit your ranges during onboarding. Requests from addresses that
have not been allowlisted are refused, so complete this before you start testing.

Funding your disbursement account

Every payout is pushed from your disbursement business account. Before any payout can go out, you
move funds into that account and keep a sufficient balance available to cover the payments you
intend to initiate. A payout initiated against an underfunded account will not complete.

Environments

Green Dot provides a partner integration environment for development and testing, and a production
environment. Base URLs are issued during onboarding. Do not guess or construct them.

The Single Call Disbursement Flow (Async) endpoints use a different base URL from the other
Digital Money Movement APIs. Your onboarding team provides both.

{baseUrl}/programs/{programCode}/...

Use synthetic test data in the integration environment. Never send production cardholder data to a
non-production environment.

Authentication

Digital Money Movement APIs use OAuth 2.0 with the client credentials (machine-to-machine) grant.
You exchange your client ID and secret for an access token, then send that token on every API call.

Step 1 — Request an access token

POST {baseUrl}/authentication HTTP/1.1
Authorization: Basic {base64(clientId:clientSecret)}
X-GD-RequestId: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "scope": ""
}

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.example.signature",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "general"
}

Step 2 — Call the APIs with the token

Send the token as a bearer token on every request:

Authorization: Bearer {accessToken}

The Single Call Disbursement Flow (Async) endpoint expects the same bearer token in a differently
named header — x-Remapped-Authorization — and uses Request-ID for the request identifier. Its
reference page shows the exact headers.

Managing the token lifecycle

• Cache the token and reuse it across requests. Green Dot recommends caching for 23 hours, so you
  refresh before the 24-hour expiry rather than after it.
• If a call returns 401 Unauthorized because the token expired, request a new token and retry
  the call. Treat this as an authentication event, not a payout failure.
• Keep the client secret and access token on your servers only. Never expose them in client-side
  code or logs.

See the portal's BaaS API Authentication guide for code samples in C#.

Standard headers

These headers apply to every Digital Money Movement API except the Single Call Disbursement Flow
(Async), which uses the headers shown on its reference page.

Always log the request identifier you sent alongside your own internal record of the payout. It is
the fastest way for Green Dot support to find a specific transaction.

Idempotency

Use these identifiers to make retries safe and to trace requests.

Request identifier — a unique GUID you send on every HTTP request. Green Dot uses it to trace
the request; include it whenever you contact support.

transferIdentifier — a GUID you generate for the payout itself, sent in the request body.
This is your idempotency key for the money movement. If you submit a transfer whose transferIdentifier
already exists, the platform returns the status of the existing transfer instead of creating a
second one (response code 4202, sub-code 1502). That behavior is deliberate: on an ambiguous
timeout, resubmitting the identical request is the safe move.

Generate transferIdentifier from your own system of record, store it before you send the request,
and reuse it on every retry of that payout.

Do not reuse a transferIdentifier across payouts. Each payout needs its own. A
transferIdentifier already recorded against a different partner is rejected.

Recipient setup has its own duplicate protection:

• Recipient profiles are checked on customerToken. If you supply your own tokens, a retried
  request for an existing token returns a "record already exists" error rather than a second
  profile. If Green Dot generates the token for you, a retry after a timeout cannot be matched to
  the original, so supply your own tokens where your program allows it.
• Card links are checked on the recipient and card details. Linking a card that is already
  linked to the same recipient returns the existing card link.

Encrypting sensitive data

Card numbers, expiration dates, and recipient identity data are never sent in plain text. They are
encrypted with your program's public certificate and submitted inside an encryptedData envelope:

The create recipient profile and link card requests also include a salt value, which must match
the X-GD-RequestId header.

You have two options for card capture:

1. Use Green Dot's hosted PCI widget. The recipient enters their card details into a
   Green Dot–hosted interface. Card data never reaches your servers, which keeps your PCI scope as
   small as it can be.
2. Collect and encrypt card data yourself. Available if you already hold PCI DSS certification
   and prefer to control the recipient experience end to end.

See the portal's Encryption in BaaS API guide for the encryption workflow, payload structure,
and code samples, and the Certificates endpoint for retrieving your program's public
certificate.

Choosing an integration flow

Two flows are available for Debit Push payouts. They deliver the same result. The difference is
whether Green Dot stores the recipient and their card, and whether you get the outcome in the
response or by webhook.

The Standard Disbursements Flow suits programs that pay the same people repeatedly — payroll,
earned wage access, marketplace sellers. You set up each recipient and card once, and each later
payout is a single call with an immediate result.

The Single Call Disbursement Flow (Async) suits programs that pay each recipient once or
occasionally — settlements, one-time rebates, emergency relief. Everything travels in one request,
nothing is stored for reuse, and the outcome arrives at your webhook endpoint.

Neither flow is better than the other; each fits a different payment pattern. You can use both in
the same program — for example, a payroll platform might use the Standard Disbursements Flow for
regular employees and the Single Call Disbursement Flow (Async) for one-off contractor payments.

Before you go live

• Confirm your IP ranges are allowlisted in production.
• Confirm your program limits and required recipient data fields.
• Confirm your fraud prevention requirements. See Fraud, Risk, and Disputes.
• If you use the Single Call Disbursement Flow (Async), deploy and test your webhook endpoint.
• Confirm your funding and reconciliation process with your Green Dot program manager.
• Test the failure paths, not just the happy path: ineligible card, insufficient funds, limit
  exceeded, expired token, and timeout-then-retry.