<<Back

Overview of GDN Retail Cash Acceptance APIs

The Green Dot Network (GDN) consists of the following:

Consumption API - Enables partners to authorize and accept cash deposits and payments made by their customers at Green Dot Network retailers. For complete information, refer to the Consumption API section.

Partner Web API - This is a REST API used to stage eCash barcode-based Cash-In transactions by enabling partners to :

  • Generate eCash barcodes linked to the target account or transaction

  • obtain lists of retailers

For complete information, refer to the Partner Web API section.

Retail Transaction Simulator - This is a Cash-In Simulation service that simulates a Consumption API call at various retailers for the following transactional simulation features:

  • Walmart Swipe Reload

  • CVS Swipe Reload & eCash Load

  • Walgreens Swipe Reload & eCash Load

  • Rite Aid Swipe Reload & eCash Load

  • Kroger Swipe Reload & eCash Load

For complete information, refer to the Retail Transaction Simulator section.

POB Partner API - The POB (Point of Banking) Partner API provides an alternative method to the Consumption API to receive cash deposit transactions to debit card accounts. This API authenticates Green Dot and the Partner, obtains customer information, processes transactions, and returns responses back to the retailer. For complete information, refer to the POB Partner API section.

Store API - This is a REST API that partners use to obtain a list of stores where the specific Cash-In services are available. The results can then be displayed to the users on the Partner’s mobile app or website. The API uses different endpoints to produce a list of stores by:

  • Zip code

  • Longitude and latitude

For complete information, refer to the Stores API section.

Green Dot Network Transactions

The Green Dot Network (GDN) APIs allow your company to accept cash at Green Dot’s Retailer Network for a wide range of user cases including:

  • Cash Deposit to debit cards

  • Cash top-up to virtual accounts

  • Bill Payments

  • Rent payments

  • Collections payments

  • Crypto accounts

  • Many more

Note: If your company uses a processor for your accounts that is already integrated into the GDN, you do not need to integrate to the Consumption API to handle payment authorization and posting. 

GDN Integrated Processor Partners

Our integrated GDN processor partners include:

  • FIS North

  • VISA DPS

  • Galileo

  • Jack Henry

  • FIS Direct

  • FSV

  • Paysign

  • Synapse

  • MCrePower

  • i2C

  • The Perfect Processor

  • Cascade Fintech

  • First Data

Two Ways for Customers to Make Cash Deposits or Payments

The customer can use two methods to make cash deposits or payments through GDN retailers:

  • Debit Card Swipe Reload (at the retail point of sale)

  • eCash Mobile Barcode (cash-in for anything other than debit-card accounts)

Following is a description of each method.

Debit Card Swipe Reload

All Green Dot Retailer locations can perform cash deposits to debit cards. To accommodate this, partners have two options for API integration. Following are descriptions of these options and their key differences.

Integration Option 1:  Direct Authorization with Green Dot

APIs Used

  • Consumption API

Key Features

  • XML API

  • Directly authorizes and posts funds in response to Green Dot requests triggered by the customer at the point of sale.

  • The partner approves or declines the deposit in response to the Auth request from Green Dot.
    Note: If you approve the Cash Deposit Auth request, you must honor a subsequent Auth Commit call to post funds.

  • Green Dot may send an Auth Void call if the retailer experiences technical problems with the transaction.

  • The transaction type is identified.

  • The Individual retail store information is included in the AuthCommit call.

Partner Requirements

  • Set up the endpoints to accept the following Green Dot requests:

    • Auth

    • Auth Commit

    • Auth Void

  • Configure the processing system to:

    • Determine when to authorize cash deposits when the Auth is received, based on the debit card PAN and amount only. 

    • Post funds when an Auth Commit call is received.

    • Void a previous Auth call if received.

  • Provide credentials to access the endpoints you set up, and whitelist Green Dot IP addresses to enable our requests to reach your endpoints successfully.

  • Pass the individual retail store information in the AuthCommit call.

Settlement Method

Using SFTP protocol, you can directly settle with Green Dot using the Settlement file posted the day after settlement.

Integration Option 2:  Lookup to Enable Usage of Debit Network Integration

APIs Used

  • Point-of-Banking API

Key Features

  • REST API

  • To process and approve a cash deposit, the API:

    • Receives the information lookup call from Green Dot.

    • Receives the standard funds posting authorization call from the program’s preferred debit or ATM network.

  • Green Dot only sends an information lookup API call, GET Customer information, then uses that information to send a combined funds authorization and posting call via its connection to the MasterCard Send gateway. 

  • MasterCard Send matches your BIN to the best funds posting channel, which could be Visa OCT, MasterCard MoneySend, NYCE, STAR, and Pulse ATM networks. Note: These networks might already be set up.

Partner Requirements

  • Configure the processing system to retrieve the information Green Dot needs to use the debit network rails to post funds.

  • Make available a connection and established process for receiving account credits via the debit networks and configure it to specifically authorize cash deposits.

Settlement Method

Use the existing settle process that the debit networks use to push account credits.

eCash Mobile Barcode Cash In

If you seek to accept cash for any purpose other than a cash deposit to a debit card, you need to use an eCash mobile barcode.  Many of Green Dot’s leading retailers (including Walmart, 7-Eleven, CVS, Rite Aid, and Walgreens) accept eCash. We are always adding retailers, so please check with your account manager for the latest list of retailers supporting eCash.

Generally, the eCash mobile barcode is generated as a one-time usage transaction and must be generated fresh for each usage. If you require a repeat-usage barcode or need bulk barcodes generated for printed statements, etc., please contact your Green Dot account manager for assistance.

Completing an eCash facilitated cash-in transaction is a two-step process:

  1. The Customer generates an eCash barcode or displays one already provided on their mobile phone to show the retail cashier.

  2. After the customer tenders cash at the retailer, Green Dot authorizes the cash-in transaction with the partner and the funds are posted.

To integrate the eCash Mobile Barcode, there are two options:

  • Real-time payments

  • All payments accepted and posted the next day

The following table summarizes the functionality, options, and requirements for integrating to the eCash mobile barcode.

How the Digital Signature Works

Calculating the Signature

Green Dot issues each partner a secret key used to calculate the digital signature. Calculating each key involves the following steps:

  1. Sorting the headers (except the Signature header) and removing extra spaces around the fields.

  2. Concatenating the headers using a delimiter &.

  3. ASCII encoding the SecretKey.

  4. UTF8 encoding the concatenated header string.

  5. Hashing the string using SHA-256 (use the key as SecretKey). Secret Key is shared between Green Dot and the partner.

Coding Used

Green Dot uses the following C# code to generate the signature.

//sort
var dict = requestHeaderDictionary.OrderBy(t => t.Key).ToList();
//concatenate
var pairs = dict.Where(p => (p.Key != “x-gdn-signature”) && (!string.IsNullOrWhiteSpace(p.Value))).Select(x => string.Format("{0}{1}{2}", x.Key, ":", x.Value));
var concatnatedString = string.Join("&", pairs).ToLower();
var encoding = new ASCIIEncoding();
byte[] secretKeyBytes = encoding.GetBytes(secret);
byte[] signature = Encoding.UTF8.GetBytes(concatnatedString);
using (var hmac = new HMACSHA256(secretKeyBytes))
{       
byte[] signatureBytes = hmac.ComputeHash(signature);     
return string.Concat(signatureBytes.Select(b => b.ToString("X2")).ToArray());
}

NOTE: Before performing the concatenation/hashing, make sure all characters are converted to lower case and the strings are trimmed (left/right) for the extra white spaces. Do not include headers that have null/empty values.

Sample Procedures

Following are the steps to generate the digital signature. You may check the results of each step.

  1. //sort
    var dict = requestHeaderDictionary.OrderBy(t => t.Key).ToList();

  2. //concatenate
    var pairs = dict.Where(p => (p.Key != WebApiRequestHeaders.X_GDN_Signature) && (!string.IsNullOrWhiteSpace(p.Value))).
    Select(x => string.Format("{0}{1}{2}", x.Key, ":", x.Value));
    var concatenatedString = string.Join("&", pairs).ToLower();

    The is x-gdn-channeltype:1&x-gdn-devicetype:2&x-gdn-encryptiontype:1&x- gdn-ipaddress:192.168.1.1&x-gdn-messageid:61aa6e58-b442-4839-8432- 948af2fad3c5&x-gdn-programnumber:bahu-bc2019&x-gdn-timestamp:2020-05- 22t03:07:53z

  3. var encoding = new ASCIIEncoding();
    byte[] secretKeyBytes = encoding.GetBytes(secret);

    The secret is i4pu7k3y secretKeyBytes.Length is 8

  4. byte[] signature = Encoding.UTF8.GetBytes(concatenatedString);
    signature.Length is 211

  5. using (var hmac = new HMACSHA256(secretKeyBytes))
    {
    byte[] signatureBytes = hmac.ComputeHash(signature);
    return string.Concat(signatureBytes.Select(b =>b.ToString("X2")).ToArray());
    }

    signatureBytes.Length is 32

    The x-gdn-signature is

    0116eb70450b743f26ccc701f598341f3e6d5b04d50979897571125928d65e8d

Invalid X_GDN  Signature Error

<base_response xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://greendotcorp.com/WebServices/Corporate/GDFNReloadServices/">
<gd_response_code>351000019</gd_response_code>
<gd_response_date>2020-05-27T07:32:57.0244211Z</gd_response_date>
<gd_response_message>Invalid X_GDN_Signature</gd_response_message>
<gd_transaction_reference>3b938107-cef0-4515-8e0f- efca6e45d656</gd_transaction_reference>
<partner_transaction_reference i:nil="true" />
</base_response>

Sample Input and Resulting Signature

Sample Header Input

{
      "x-gdn-timestamp": "2020-05-22T03:07:53Z",
      "x-gdn-encryptiontype": "1",
      "x-gdn-messageid": "61aa6e58-b442-4839-8432-948af2fad3c5",    
  "x-gdn-channeltype": "1",    
  "x-gdn-devicetype": "2",   
   "x-gdn-ipaddress": "192.168.1.1",    
  "x-gdn-programnumber": "Bahu-BC2019"
}

Sample Body Input

{
"gd_retailer_key”: "2433",
"amount”: "22.22"
}

Sample Concatendated Values

“x-gdn-channeltype:1&x-gdn-devicetype:2&x-gdn-encryptiontype:1&x-gdn-ipaddress:192.168.1.1&x-gdn-messageid:61aa6e58-b442-4839-8432-948af2fad3c5&x-gdn-programnumber:bahu-bc2019&x-gdn-timestamp:2020-05-22t03:07:53z”

Resulting Signature

Using the sample secret key i4pu7k3y, the resulting hash/signature would be as follows:

0116eb70450b743f26ccc701f598341f3e6d5b04d50979897571125928d65e8d