Transfer Status & Webhooks

What happens after you initiate a payout matters as much as the request itself. This page covers
the states a payout can reach, how you find out about them in each flow, and what to do in each
case.

Statuses

Debit Push payouts move through these states:

Status	Meaning	Final?
`Pending`	The payout has been accepted and is in flight. Funds have not reached the recipient.	No
`Completed`	Funds reached the recipient.	Yes
`Failed`	The payout could not be processed because of a system or validation problem. Funds did not move.	Yes
`Declined`	The payout was refused — by the card network, by a limit, or by a compliance control. Funds did not move.	Yes

Failed and Declined are different outcomes and need different handling. Treating them as one
"error" state in your application is the most common source of avoidable support volume.

	`Failed`	`Declined`
Cause	Something went wrong in processing — a timeout, a system error, a malformed request	Something about the payout was not permitted — ineligible card, limit reached, compliance block
Will retrying help?	Often, once the underlying problem clears	No, not until the underlying condition changes
What to tell the recipient	Usually nothing yet; resolve it first	Usually something — they may need to supply a different card
What to do	Investigate the sub-code, then retry	Read the sub-code, fix the condition, then issue a new payout

Timing expectations

Debit Push payouts typically complete in near real-time, 24/7. A payout still Pending well beyond
a few minutes is worth looking up directly.

How you find out what happened

The two flows report outcomes differently.

	Standard Disbursements Flow	Single Call Disbursement Flow (Async)
Primary source of the outcome	The transfer response	A webhook to your endpoint
Webhooks generated	No	Yes
Status lookup	Retrieve a transfer by customer token and transfer ID	Retrieve a transfer by payee site ID and transfer ID

Standard Disbursements Flow: synchronous responses

The transfer response carries the outcome. Record transferStatus from the response against your
payout record. Use the status lookup for reconciliation and for any payout that came back
Pending.

When a Standard Disbursements Flow payout is pending

If a downstream timeout occurs while processing a transfer, the API returns HTTP 202 and the
payout is Pending. Green Dot then retries automatically, checking the transaction status at
increasing intervals for up to 24 hours. You do not need to resubmit the payout. Look up its status
periodically until it reaches a final state.

If you are unsure whether a request reached Green Dot at all — for example, your connection dropped
before any response — resubmit it with the same transferIdentifier. If the original was
received, you get the existing record back rather than a second payment.

Single Call Disbursement Flow (Async): webhooks

Green Dot posts to the endpoint you register during onboarding when a payout reaches a final state.
See Receive the outcome for
the payload.

Webhook handling rules:

Acknowledge fast, process asynchronously. Do not run your business logic inside the request.
Deduplicate on eventIdentifier. Assume any event can be delivered more than once.
Match on transferIdentifier. Never match on amount, timestamp, or recipient name.
Do not assume ordering. Handle each event on its own merits.
Log the raw payload. When something goes wrong, the response code and subCode are what
support will ask you for.

Use the status lookup as your fallback whenever your webhook endpoint has had an outage. Do not use
it as a polling loop in place of webhooks.

Retrying safely

The rule is simple: retry the same payout, do not send a second one.

Situation	What to do
No response received (connection dropped)	Retry with the same `transferIdentifier`. If the original went through, you get the existing record back (code `4202`, sub-code `1502`) rather than a duplicate payment.
`202` (Standard Disbursements Flow)	Do not resubmit. Green Dot is retrying; look up the status until it is final.
`500` or `503`	Retry with the same `transferIdentifier`.
`401`	Request a new access token and retry. Not a payout failure.
`400` validation error	Do not retry as-is. Fix the field the sub-code identifies, then send with a new `transferIdentifier`.
Status `Failed`	Investigate the sub-code. Once resolved, issue a new payout with a new `transferIdentifier`.
Status `Declined`	Do not retry. Resolve the condition — different card, lower amount, wait for a limit window to reset — then issue a new payout.

Never retry against a card that was declined for card eligibility. It will be declined again, and
repeated attempts against an ineligible card can attract network-level scrutiny.

Why payouts fail

Most failures come from a short list.

Cause	How to prevent it
Incorrect card details	Validate before initiating. Using the hosted PCI widget removes most transcription errors.
Ineligible card type	Ask recipients for a debit card, and act on eligibility declines by requesting a different card.
Insufficient funding	Confirm your disbursement account balance covers a run before you start it.
Limit exceeded	Know your per-transaction, daily, weekly, and monthly limits, and check amounts against them before submitting.
Amount below minimum	Enforce your program's minimum in your own logic.
Compliance hold (OFAC)	Expected in some cases. Route these to your compliance process, not to a retry queue.

Program limits

Per-transaction and program-level thresholds are configured for your program and confirmed during
onboarding. Design your payout process to operate within them rather than discovering them through
declines — a run that hits a daily limit halfway through leaves you with a partially completed
batch to reconcile.

Limits that commonly apply:

Maximum amount per transaction
Maximum number of transactions per day, week, or month
Maximum total amount per day, week, or month
Minimum amount per transaction
Per-recipient limits, separate from program limits

What to show the recipient

A suggestion, not a requirement — but it prevents support contacts:

Status	What the recipient should see
`Pending`	That the payment is on its way, without a minute-level promise of arrival
`Completed`	That the money has been sent to the card ending in the last four digits they recognize
`Failed`	That there was a problem and you are handling it — avoid technical detail
`Declined`, card eligibility	A clear prompt to provide a different debit card, with a plain explanation of which cards do not work
`Declined`, limit	That the payment could not be completed at this time, and when to expect it