Appendices
Environments, Authentication, and Codes
API Environments
https://{env}-partners.greendotcorp.com/GDCPartners/api/v1
| DNS NAME | Actual Environment | Public IP Address |
|---|---|---|
| qa2-partners.greendotcorp.com | QA4 | 67.131.213.47 |
| qa3-partners.greendotcorp.com | QA3 | 67.131.213.49 |
| qa4-partners.greendotcorp.com | QA5 | 67.131.213.73 |
| partners.greendotonline.com | PROD | 66.116.101.64 /26 208.87.176.0 /22 Or 66.116.101.91 port 443 208.87.176.53 port 443 208.87.177.53 port 443 |
https://gssprt.{env}.nextestate.com/partnerdisbursement/api/v1
| DNS NAME | Actual Environment |
|---|---|
| gssprt.qa.nextestate.com | QA |
| gssprt.pie.nextestate.com | PIE |
| gssprt.dc1.greendotcorp.com | PROD |
NOTE: The DNS name and Actual environment names do not match.
Development Environment Settings
Green Dot Development & Testing Environment URL
https://partners.greendotonline.com/GDCPartners/GDCWS_GDNPartnerAPI/GDNPartnerAPIService.svc
Green Dot Development & Testing Environment Host File Settings
| DNS NAME | Actual Environment | Public IP Address |
|---|---|---|
| gdcpartners.greendotcorp.com | QA-4 | 67.131.213.47 |
| partners.greendotonline.com | QA-4 | 67.131.213.47 |
| gdcpartners.greendotcorp.com | QA-3 | 67.131.213.49 |
| partners.greendotonline.com | QA-3 | 67.131.213.49 |
Note: For the production environment, there is no need to add HOSTS file entries.
About API Authentication
- The services will be hosted in an environment which is IP restricted. Only authorized partners will have access to this service.
- The payload will be encrypted in the SSL environment.
- A secret key/token will be shared between GDN and the partner. Please contact Green Dot development team for the secret key/token
- Individual data elements like CustomerID will be sent as plain text.
Header Information
The GDN APIs use the following headers.
| Field | Required? | Description |
|---|---|---|
| x-gdn-timestamp | Yes | Timestamp in http header is using the pattern [YYYY]- [MM]- [DD]T[hh]:[mm]:[ss][time zone] that preserves time zone information and complies with ISO 8601. The time zone component is an offset from UTC (for example, +01:00, -07:00). The time zone component uses ‘Z’ (which stands for zero offset) to represent UTC. Timestamp string without time zone component is assumed to be UTC. Example: 202005-22T03:07:53Z |
| x-gdn-signature | Yes | Signature of the message (see API Authentication section below) |
| x-gdn-encryptiontype | Yes | 0-none 1-Digital Signature |
| x-gdn-sessionid | No | The Transaction Session ID (for future use). |
| x-gdn-messageid | Yes | The unique Transaction ID |
| x-gdn-channeltype | Yes | 1-mobile 2–web 0-other |
| x-gdn-deviceid | No | The Device ID of the client making the API call(for future use). |
| x-gdn-devicetype | Yes | 0-other 1- mobile 2- desktop |
| x-gdn-ipaddress | Yes | The IP Address of the client making the API call |
| x-gdn-latitude | No | Latitude of the client device/browser making the API call. |
| x-gdn-longitude | No | Longitude of the client device/browser making the API call. |
| x-gdn-programnumber | Yes | Program number assigned by Green Dot |
Common Response Fields
The following common response fields are used in the GDN APIs.
| Parameter | Datatype | Description |
|---|---|---|
| partner_transaction_reference | String | TransactionReference of the partner if the partner passes this information. |
| gd_transaction_reference | String | The Unique reference that Green Dot generated for this transaction. |
| gd_response_code | Int | Refer to Response Codes. |
| gd_response_message | String | Custom text describing the success or failure of the API. |
| gd_response_date | DateTime | The Response date time in UTC. |
Common Response Codes
Following are the GDN response codes and their displayed descriptions for the GDN client messages.
| Description | Description | Client Message |
|---|---|---|
| 0 | Success | Success |
| 00 | Returned if request completed successfully. | Success |
| 01 | Returned if any parameter is invalid or missing. | Parameter – Invalid |
| 02 | Returned if partner identifier [PartnerCode] is invalid. | Processor – Invalid |
| 03 | Returned if the RequestID is the exact same as another request. | Duplicate Request |
| 04 | Returned if BIN/program is invalid. | Program – Invalid |
| 05 | Returned if BIN/program is blocked. | Program – Blocked |
| 06 | Returned if Payment type is invalid for the corresponding Program. | Payment Type- Invalid |
| 20 | Returned if account is invalid. | Account – Invalid |
| 22 | Returned if account is closed. | Account – Closed |
| 23 | Returned if account is not reloadable. | Account - Not Reloadable |
| 24 | Returned if account is expired. | Account – Expired |
| 25 | Returned if account is lost or stolen. | Account - Lost/Stolen |
| 26 | Returned if account is not active. | Account - Not Active |
| 27 | Returned if account is blocked by Partner. | Account - Blocked by Partner |
| 28 | Returned if account is blocked by Green Dot. | Account - Blocked by Green Dot |
| 39 | Returned if total amount transacted by customer is not in the per transaction limit range. | Invalid Per Transaction Green Dot Program Limit Amount |
| 40 | Returned if total amount transacted by customer exceeded retailer daily limits. | Exceeds Daily Retailer Limits |
| 41 | Returned if total number of transactions performed by customer exceeded Green Dot's daily limits. | Exceeds Daily Green Dot Program Limits – Count |
| 42 | Returned if total amount transacted by customer exceeded Green Dot's daily limits. | Exceeds Daily Green Dot Program Limits – Amount |
| 43 | Returned if total number of transactions performed by customer exceeded Green Dot's weekly limits. | Exceeds Weekly Green Dot Program Limits – Count |
| 44 | Returned if total amount transacted by customer exceeded Green Dot's weekly limits. | Exceeds Weekly Green Dot Program Limits – Amount |
| 45 | Returned if total number of transactions performed by customer exceeded Green Dot's monthly limits. | Exceeds Monthly Green Dot Program Limits – Count |
| 46 | Returned if total amount transacted by customer exceeded Green Dot's monthly limits. | Exceeds Monthly Green Dot Program Limits - Amount |
| 47 | Returned if transaction amount is invalid. | Invalid Amount – Either Does Not Meet Minimum or Exceeds Maximum Amount. |
| 48 | Returned if total number of transactions performed by customer exceeded Partner's daily count limits. | Exceeds Partner Daily Load Limits - Count |
| 49 | Returned if total amount transacted by customer exceeded Partner's daily amount limits. | Exceeds Partner Daily Load Limits - Amount |
| 50 | Returned if total amount transacted by customer exceeded maximum account balance. | Exceeds Max Account Balance |
| 51 | Returned if total number of web attempts performed by customer from the same IP exceeds Green Dot’s Limits | Exceeds IP Audit Limit |
| 52 | Returned if the ANI or customer’s phone number is black listed in Green Dot’s system | ANI – Blocked by Green Dot |
| 53 | Returned if total number of transactions performed by customer exceeded Partner's weekly count limits. | Exceeds Partner Weekly Load Limits - Count |
| 54 | Returned if total amount transacted by customer exceeded Partner's weekly amount limits. | Exceeds Partner Weekly Load Limits - Amount |
| 55 | Returned if total number of transactions performed by customer exceeded Partner's monthly count limits. | Exceeds Partner Monthly Load Limits - Count |
| 56 | Returned if total amount transacted by customer exceeded Partner's monthly amount limits. | Exceeds Partner Monthly Load Limits - Amount |
| 60 | Returned if MoneyPak number is invalid. | MoneyPak - Invalid |
| 61 | Returned if MoneyPak status is not active. | MoneyPak Status - Invalid |
| 63 | Returned if MoneyPak is blocked by Green Dot. | MoneyPak - Blocked |
| 64 | Returned if MoneyPak is already consumed. | MoneyPak - Consumed |
| 65 | Returned if MoneyPak is partially used. | MoneyPak - Insufficient Fund |
| 66 | Returned if there is a funding delay on MoneyPak. | MoneyPak Funding Delay |
| 98 | Returned if original transaction amount loaded to customer’s account cannot be reversed as full amount is not available. | Unable to Void – Already Posted, Full Amount Not Available |
| 99 | Reserved ONLY for system errors.Please use the appropriate error codes above to report any transactional errors. | Non-Successful – Unspecified |
| -999 | Internally generated by Green Dot if no response is received for the API Request from Partner in a pre-defined time period OR Partner can return this response code in a use case where an AuthVoid or AuthCommit should be re-tried. This response code will result in a re-try for AuthVoid and AuthCommit only. | Timeout |
| 111111111 | Success but the oldest barcode will be cancelled | The oldest barcode will be cancelled |
| 351000001 | This is an invalid barcode | Invalid barcode |
| 351000015 | This is an invalid Program | Invalid X_GDN_Program_Number |
| 351000016 | The retailer is invalid | gd_retailer_key is invalid or empty |
| 351000017 | The time stamp is invalid | Invalid X_GDN_TimeStamp or Expired |
| 351000018 | Invalid Parameter. i.e. One or more of required fields are null or empty | FIELDNAME cannot be empty Ex: sender_first_name cannot be empty |
| 351000019 | Invalid Signature Digest | Invalid X_GDN_Signature |
| 351000021 | The Start date is not in valid date format (yyyy-mm-dd) or start date > current date | Invalid start_date |
| 351000022 | The end date is not in valid date format (yyyy-mm-dd) | Invalid end_date |
| 351000023 | Start date > End date | Invalid Date Range. start_date should not be greater than end_date |
| 351000025 | Missing Required Header Fields | Missing Required Header Fields |
| 351000026 | Encryption Type Not Supported | Encryption type not supported |
| 351000027 | Invalid Device Type | Invalid X_GDN_DeviceType |
| 351000028 | Invalid Channel Type | Invalid X_GDN_ChannelType |
| 351000029 | GDFN Load Limits Exceeded | GDFN load limits are exceeded |
| 351000030 | Barcode Velocity Limits Exceeded | Barcode velocity limits are exceeded |
| 351000031 | Invalid Zip Code | Invalid Zip Code |
| 351000032 | Error Occurred in Get Zip Code Location | Error Occurred in Get Zip Code Location |
| 351000033 | Error Occurred in Get Store | Error Occurred in Get Store |
| 351000034 | Invalid Page Number | Invalid Page Number |
| 351000035 | Invalid Latitude | Invalid Latitude |
| 351000036 | Invalid Longitude | Invalid Longitude |
| 351000037 | Invalid Service Type | Invalid Service Type |
| 351000038 | Invalid Count Number | Invalid Count Number |
| 351000039 | Count Number Exceed Maximum | Count Number Exceed Maximum |
| 351000040 | The Given Barcode Amount is less than GDFN's user limits | Amount is less than the minimum transaction amount |
| 351000041 | The Given Barcode Amount is more than GDFN's user limits | Amount is more than the maximum transaction amount |
| 351000042 | Barcode not found | Barcode Id not found |
| 351000044 | Invalid encryption type | Invalid encryption type |
| 351000045 | Invalid gd_barcode_type | Invalid gd_barcode_type |
| 351000046 | If sender_email does not support email format | Invalid sender_email |
| 351000047 | If sender_phone does not support phone number format | Invalid sender_phone |
| 351000048 | If recipient_email does not support email format | Invalid recipient_email |
| 351000049 | If recipient_phone does not support phone number format | Invalid recipient_phone |
| 999999999 | System Error | System Error |
HTTP Response Codes
Following is a complete list of the response codes that the application needs to return for requests. In the event of network or infrastructure issues, the infrastructure may return other response codes.
| HTTP Response Codes | Description |
|---|---|
| 200 OK | The request was completed successfully. |
| 400 BAD REQUEST | General error when the request could not be fulfilled due to problems such as validation errors, missing required data, etc. |
| 401 UNAUTHORIZED | Error code response for a missing or invalid authentication token. |
| 404 NOT FOUND | The requested resource is not found. For example, the PAN is not found or the card is expired. |
Error Codes
Error response messages contain the following parameters.
| Error Code | Error Description |
|---|---|
| ACCOUNT_EXPIRED | Account expired |
| ACCOUNT_NOT_FOUND | Account not found |
| AUTHORIZATION_FAILED | Authorization failed |
| GATEWAY_TIMEOUT | Gateway timeout |
| ACCOUNT_BLOCKED | Account blocked |
Glossary
Green Dot hosted -- Green Dot is hosting the API.
Green Dot Initiated -- Green Dot initiates the request.
Partner hosted -- Partner is hosting the API.
Partner Initiated -- Partner initiates the request.
PULL -- Partner is sending the request to Green Dot.
PUSH -- Green Dot is sending the request to the partner.
Updated about 2 months ago