API Details

API Details

Making a Transfer

A simple workflow for making a transfer to an external bank account looks like:

  1. Make a POST /customers/{customerid} request as documented at POST /customers to create a new customer. If holding an existing account, retrieve its AccountID from the Registration API.
  2. Make a POST/customers/{customerid}/links/type/{fundingtype} request using CustomerID from the previous response to create a funding link. Make a second similar request to setup a destination link. If using a Green Dot bank account for either the source or destination, skip establishing that link.
  3. Make a POST/transfers/{transferid} request using CustomerID from the previous response to create a funding source.
  4. Make a POST/transfers/confirm/{transferId} request using TransferId from the previous response to confirm or void the associated Transfer. (This step is only used for a 2-phase commit or void Transfer Process).

Request Headers

Standard Headers

  • accept: What the response should be formatted with. We currently support the following:
    • application/xml
    • application/json (Default)
  • Accept-Encoding: gzip, deflate
  • Content-Type: application/json;charset=UTF-8

Custom Headers

  • requestid: The unique request ID generated by the client for transaction tracking. It is advisable to prepend the ID with the unique partner name. This header is optional for all APIs, except for POST/Transfer.
  • endusersecurityid: The agreed upon unique Security ID of the End User. This header is used for fraud prevention and is a required value.
  • enduserip: The IP address of the End User. This header is used for fraud prevention and is a required value.
  • partneridentifier: Identifies the sender of the request. The value will be provided by Green Dot. This header is required if it is not an admin call. If it is an admin call, this is not required (the url is / admin/ xyz.
  • apikey: This is an admin identifier/key. The value is “disbAdmin.” This is an optional header for non-admin calls but required for admin calls. If this header is populated, the caller needs to use an admin credentials to generate the authorization header. For all CRM calls, they can pass apikey along with the corresponding authorization header. If you are using version 1.2 and above, this is no longer used.
  • x-gdc-authentication-method: Specifies the authentication method. This is used in version 1.2 and above. Values are:
    • Basic – 1
    • Oauth -2 (will be supported in the future)
  • x-gdc-client-type: Specifies the client type. This is used in version 1.2 and above. Values are:
    • External – 1 (default)
    • Internal -2

Response Headers

Standard Headers

  • date: The date and time that the response was sent (in "HTTP-date" format as defined by RFC 7231
  • content-type: What the request was encoded with. Currently we support:
    • application/xml
    • application/json (Default)

Custom Headers

Common HTTP Status Codes

Common HTTP Status Codes

Upon receipt of any HTTP status codes, the Partner can either submit a GET/transfers/{transferId} to find out the status of the transaction or retry the transaction. If the transaction is retried, the POST/Transfer must be with the SAME TransferID so that idempotency is triggered and double-funding is prevented.

Status CodeDescription
200Successful Request. See specific operation to see details for this response.
201Resource was able to be created. See specific operation for details for this response.
400Malformed request; missing fields, incorrect data, or malformed input structure. All possible error codes are listed below in Error Codes section.
400If malformed requestid, an additional error code of 1010 will be sent.
400If malformed endusersecurityid, an additional error code of 1020 will be sent.
400If malformed enduserip, an additional error code of 1030 will be sent.
401Unauthorized. Please provide valid credentials in the authorization header.
404Unable to find resource. Unable to find resource specified by the URL parameter identifier.
405Method Not Allowed. Unable to handle with the specified URI.
409The requestid in the header already exists (duplicate request) in the Green Dot System for the given partner. An additional Error code of 2100 will be sent.
409Unable to proceed because resource already exists in our system and is not in a valid state. See specific operation to see details for this response.
500Internal Server Error.
501Not implemented. Will be implemented at a future date.
502Bad Gateway. The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.
503Service Unavailable. The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
504Gateway Timeout. The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (e.g. HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed to access in attempting to complete the request.

Common Response Codes

Upon receipt of any common response codes, the Partner can either submit a GET/transfers/{transferId} to find out the status of the transaction or submit a new transaction. The new transaction should include a DIFFERENT TransferID. Sending the transaction with the same TransferID will only trigger idempotency and result in the same original response.

1No response received for the API Request in a pre-defined time period.
11No record found
20Invalid Customer
40Invalid Card Status
41No Card Found
50Parameter - Invalid
51Missing parameter or Exceeded max length for the field
52Invalid Amount
70Invalid partnerIdentifier
80Limit exceeded
90Validation failed
91Card Load Failed
99Non-successful - Unspecified
100Internal Exception
101Internal Exception - call to other services failed
102Partner service return failure
103Customer is blocked
112ProgramPartnerIdentifier is not supported
113Transfer id is already completed
114Verify account key failed
123Failed in GREEN DOT AuthCommit
131Invalid card
153Personalized card not yet activated
159Partially funded
160Load not allowed
161Card lost or stolen
162Personalized card not found
163Card account closed
164Card account blocked
165Card not registered
166Validate Pin Other
167Failed OFAC Verification
168Card Expired
213Missing valid MasterCard processor configuration UberPayments
301Transfer reversal not allowed
302Invalid Barcode Fields
303The RetailerKey does not match the barcode retailer key
304Transfer not previously authorized

Common Response Detail Codes

Detail Codes are designed to provide additional detail information about the associated parent response code being returned.

Response CodeDescription
50Exception occurred
3010Sender limit exceeded
3020Recipient limit exceeded
3030Invalid recipient account
3040Other validation failures
3041Invalid customer id
3042There is no customer profile information by the CustomerID and PartnerProgramIdentifier
3043Missing partner program configuration
3046Partner Program Identifier is not allowed for this API
3047No partner client credential found
3048Partner program identifier do not match with original disbursement transfer request
3049Original transfer id is a reversal id
3050Either source or target account does not match original transfer
3052Barcode number not found
3053Invalid Retailer Information
3054Account transaction not found
3055Two Phase Commit Transfer not allowed
3056Invalid Source Account
3057Error encountered with GDN System - Transaction Successfully Voided
3058Invalid UserName
3059No user method groups found
3071File type not supported
3072File size exceeded
3073Invalid BankName
3074Invalid RoutingNumber
3075DebitFundingSourceDetailAccountTransactionType is invalid
3076CreditFundingSourceDetailAccountTransactionType is invalid
3077Invalid Identification Info
3600Transaction Cancelled successfully
3601Transaction Cancelled already
4001Ach Rejected
4004Dct Timeout
4005Partner Service Error
4010Missing partner identifier
4020Invalid partner identifier
4021Invalid or no corresponding configuration for partner identifier
4030PartnerProgramChannel not supported
4040Amount cannot be less than or equal to 0
4041Amount format is invalid
4050OriginationRequestId cannot be empty
4060SourceProfile's CustomerID cannot be empty
4070TargetProfile's CustomerID cannot be empty
4080Request is null
4100Invalid source profile
4110Invalid target profile
4120Invalid source profile type
4130Invalid Transfer request option
4131Invalid Transfer request option(IsGDNCard)
4132Invalid Transfer request option(OriginalMessageID)
4133Invalid Transfer request option(OriginalConfirmationID)
4134Invalid Transfer request option(TransactionReferenceNumber)
4135Invalid Transfer request option(SourceAccountReferenceNumber)
4136Invalid Transfer request option(TargetAccountReferenceNumber)
4230Invalid target profile type
4250Missing/Duplicate request id
4260Missing request transaction
4270Missing request transferobject
4280Missing partner service configuration
4290Missing partner target uri
4300Missing target customer information
4310Missing target profile
4320Missing channel configuration
4330Missing target profile token
4340Mismatch source customer and target customer
4350The program is not supported
4360Missing customer id
4370Missing profile token
4380Invalid transaction date
4390Invalid transfer id
4391Invalid claimCode
4392Invalid transfer id or invalid claimcode
4400Invalid target account token
4410Invalid workflow process activity
4420Invalid workflow activity status
4430Invalid workflow process
4440Invalid workflow process status
4441Invalid DisbursementTransferRequestKey
4442Invalid DisbursementBatchKey
4450Invalid WorkflowProcessExecutionInstanceKey
4460Invalid RegistrationKey
4461No Registration profiles found
4470Missing PIN
4471Missing PIN Reference
4480Missing first name
4490Missing last name
4500Missing customer info
4510Missing account token
4513Invalid or missing expiration info
4520Missing last 4 digits
4521Missing BIN
4530Missing card association type
4540Missing account number
4550Missing expiry month
4560Missing expiry year
4570Invalid expiry month
4572Account Blocked
4573No Auth Request Found
4574Invalid profile key
4575Unable to void - already posted or full amount not available
4576Either does not meet minimum or exceeds maximum per transaction amount.
4577Account Not Active
4578Invalid GDN Program
4579GDN Program Blocked
4580Invalid expiry year
4581Invalid Payment Type
4582Invalid Partner ResponseId
4583Invalid Processor
4584Exceeds IP Audit Limit
4585ANI - Blocked by Green Dot
4586Account Not Reloadable
4587Account Not Eligible
4588Card Declined
4589Potential Fraud Detected
4590Invalid customer key
4591Partner has exceeded the daily limit
4592Transaction limit is less than the minimum configured for the partner
4593Consumer has exceeded the monthly limit configured in the system
4594Per transaction maximum amount limit reached
4595Missing RequestID
4596Missing Transfer ResponseCode Description
4597Missing Transfer ResponseDetailCode Description
4598Invalid Transfer Status ChangeDate
4599Missing Partner Program Identifier
4600Missing phone number
4601Consumer has exceeded the daily load amount limit in the system
4602Consumer has exceeded the daily load count limit in the system
4603Consumer has exceeded the weekly load amount limit in the system
4604Consumer has exceeded the weekly load count limit in the system
4605Consumer has exceeded the monthly load amount limit in the system
4606Consumer has exceeded the monthly load count limit in the system
4610Missing email address
4620Invalid email address
4630Invalid phone number
4640Invalid SSN
4660Invalid processing waiting hours
4670Invalid expired waiting hours
4680Invalid cancel waiting hours
4690Invalid original disbursement transfer request key
4700Invalid original disbursement transfer request id
4710Missing original disbursement transfer request id
4720Reversal amount exceeds original transaction amount
4730Original transfer not successful
4740Invalid reversal amount
4750Original transfer not found
4751Invalid Barcode Status
4752Request ID provided not found
4753Transfer ID provided not found
4800Account balance is less than the reversal amount
4802Refer to card issuer
4807Cardholder not on file
4809Bank not supported by switch
4810Allowable PIN tries exceeded, capture
4812Requested function not supported
4813Insufficient funds on card
4814Incorrect Pin - Invalid PIN number
4815Transaction Denied - Transaction not Permitted to Cardholder
4818Exceeds Withdrawal Limit
4821Hard capture, permanent restraint
4822Pin Exceeded
4826Transaction Decline - Violation of Law
4830Authorization life cycle expired or unacceptable
4831Inactive card
4832AVS Failed - The AVS validation was not a match
4900Invalid InvalidPartnerKey
4910No transaction is calculated
4920Missing partner list configuration
4921Missing email flag
4922The Card type is Unknown
4923No Valid CardTransfer found
4924Missing PartnerKey
4925Invalid Batch Id
4926Invalid argument experienced with internal service
4927Invalid PartnerId
4928Invalid PartnerName
4929Invalid ProgramId
4930Invalid PartnerProgramId
4931Missing notification product definition token
4932Missing notification type key
4933Missing detail account transaction type
4934Missing or invalid GdGdV3LimitVeriPaymentType
4935Missing Personal Card / CRV Removal configuration
4936Duplicated identifier/record/requiest id detected
4937Suspicious Fraud
4938Operation is not allowed
4939Failed to add the disbursementtransferledger information for the debit source profile
4940Failed to add the disbursementtransferledger information for the fund target profile
4941Failed to add the disbursementtransferledger information for the credit source profile
4942Failed to update the disbursementtransferrequest information
4943AccountManagement Credit Api Timeout
4944AccountManagement Debit Api Timeout
4945Tpg stage failed
4946Missing Transaction Info
4947Missing Identification Info
4948Missing Credential Info
4949Missing tpg processor configuration
4950Missing payment processor configuration
4951Missing Disbursement Transfer Token
4952Missing Claim Code
4953Missing TransactionId
4954Unable to determine SSN based on last 4 provided

Field Standards

FieldTypeFormatRequiredValues Allowed
firstNameStringMin 2 characters Max 25 charactersYesa-z, A-Z, hyphen, space Regex="^[a-zA-Z][- a-zA-Z']+$
LastNameStringMin 2 characters Max 25 charactersYesa-z, A-Z, hyphen, space Regex="^[a-zA-Z][- a-zA-Z']+$
MiddleInitialStringMin 1 character Max 1 characterYesa-z, A-Z Regex=@"^[a-zA-Z]{1}$
AddressLine1StringMin 0 characters Max 25 charactersYesa-z, A-Z, 0-9, hyphen, space, /, period Regex=@"^[a-zA-Z0-9][- a-zA-Z0-9/\.]{2,}$
AddressLine2StringMin 0 characters Max 25 charactersNoa-z, A-Z, 0-9, hyphen, space, /, period Regex=@"^[a-zA-Z0-9][- a-zA-Z0-9/\.]{2,}$
CityStringMin 0 characters Max 25 charactersYesa-z, A-Z, hyphen, space Regex=@"^[- a-zA-Z]*$
StateStringMin 0 characters Max 2 charactersYesany word character Regex=@"^\w{2}?$
ZipCodeStringMin 5 characters Max 10 charactersYes0-9, hyphen Regex=@"^\d{5}(-?\d{4})?$
SSNStringMin 11 characters Max 11 charactersYes0-9, hyphen Regex=@"^[0-8]\d{2}-\d{2}-\d{4}$
DateOfBirthStringMin 10 characters Max 10 charactersYes0-9, hyphen, dash, period Regex=@"^(0[1-9]|1[012])[- /.](0[1-9]|[12][0- 9]|3[01])[- /.]19 | 20\d\d$
ATMPinStringMin 4 characters Max 4 charactersYes0-9 Regex=@"^[0-9]{4}$
PhoneNumberStringMin 13 characters Max 14 charactersYes0-9, hyphen, space, (,) Regex=@"^([2-9]\d{2}) ?\d{3}-\d{4}$
EmailAddressStringMin 6 characters Max 50 charactersYesa-Z, A-Z, 0-9, underscore, hyphen, period, ampersand Regex=@"^[a-zA-Z0-9_-]+(.[a-zA-Z0-9_-]+)@[a[1]zA-Z0-9-]{2,}(.[a-zA-Z0-9-]+).([a-zA-Z]{2,4})$


Prefix: https://[server]/gateway/[version]/


The current version is 1.1

Error Response

When an error occurs, there will be an errors property with a list of errors applicable to the request

  • errorcode: Green Dot error code.
  • errordescription: Descriptive error message.


         "errordescription":"Missing request id”