Introduction

The GDN Partner WebAPI is a REST API used to stage eCash barcode-based Cash-In transactions by enabling the partner to:

Generate eCash barcodes linked to the target account or transaction
Obtain lists of retailers

API Endpoints

Testing the API Response

Ping Without Headers

This API pings the Web API and provides a response. It is used only to determine if the service is responding to requests and echoes the string or input parameter.

Structure of API Call:

GET /v1/ping/{test string}

GET /v1/ping/123xyz

Request

Parameter	Datatype	Required	Description
input	String	Yes	Some custom text (i.e., 123)

Response

Parameter	Datatype	Description
Output	String	The text you entered as input

<string      
			xmlns="http://schemas.microsoft.com/2003/10/Serialization/"> 123
</string>

Ping With Headers

This API pings the Web API and performs the following:

Determines if the service is responding to requests·
Determines if headers are valid
Determines if encryption/hashing is working correctly on both ends
Echoes the input parameter

Structure of API call:

GET /pingwithheaders/{id}

Sample Request – Headers

{
    x-gdn-ipaddress:127.0.0.1 x-gdn-encryptiontype:1
    x-gdn-devicetype:1
    x-gdn-programnumber:Bahu-BC2019 x-gdn-channeltype:1
    x-gdn-messageid:ba435239-26f0-4678-b95e-f7f55f723dd4
    x-gdn-signature:6EB2CCC767CC360FC43957F05A4C88023C6B746B298821D6661055441B453735
    x-gdn-timestamp:2020-06-18T06:07:44Z x-gdn-sessionid:null
    x-gdn-deviceid:b329954c-ff60-4c0e-8f48-21b0978ec9cd x-gdn-latitude:25.78
    x-gdn-longitude:288.11
}

Request Parameters

Parameter	Datatype	Required	Description
input	String	Yes	Some custom text (i.e., 123)

Response

Parameter	Datatype	Description
Output	String	The text you entered as input

<string      
			xmlns="http://schemas.microsoft.com/2003/10/Serialization/"> 123
</string>

Generating Barcodes

The BarCode Generation API generates a barcode number for a given program/product/customer.

Structure of API Call:

POST /v1/barcode

Sample Request - Add Cash Partner (Header)

{
   x-gdn-ipaddress: 127.0.0.1
   x-gdn-encryptiontype: 1
   x-gdn-devicetype: 1
   x-gdn-programnumber: Catalina-BC x-gdn-channeltype: 1
   x-gdn-messageid: 200306011700823 x-gdn-signature:
   573BCFB6212C434680D72BE36F72C7FD5306D7779521B8EA2F082721FB6899F8
   x-gdn-timestamp: 2020-03-06T01:17:00.00Z(Z means zero time zone offset from utc)
}

Sample Request - Add Cash Partner (Body)

{
   "gd_retailer_key": "2433",
   "gd_barcode_type": 2,
   "amount": "22.22",
   "partner_transaction_reference": "abcdefg",
   "sender_customer_ref": "123456789",
   "sender_first_name": "123",
   "sender_last_name": "sln",
   "sender_email": "[email protected]",
   "sender_phone": "6263331234",
   "recipient_customer_ref": "1147762",
   "recipient_first_name": "rfn",
   "recipient_last_name": "rln",
   "recipient_email": "[email protected]",
   "recipient_phone": "2133334321",
   "notification_channel_type": 0,    
   "amount_match_type": 0
}

Sample Request – Bill Pay Partner (Headers)

{
   x-gdn-ipaddress: 127.0.0.1
   x-gdn-encryptiontype: 1
   x-gdn-devicetype: 1
   x-gdn-programnumber: Aptexx-BC (The program should configure the SubProgramCategory of the Bill Pay type)
   x-gdn-channeltype: 1
   x-gdn-messageid: 200306011700823 x-gdn-signature:
   573BCFB6212C434680D72BE36F72C7FD5306D7779521B8EA2F082721FB6899F8
   x-gdn-timestamp: 2020-03-06T01:17:00.00Z(Z means zero time zone offset from utc) Content-Type:application/json
}

Sample Request – Bill Pay Partner (Body)

{
   "gd_retailer_key": 2480,
   "gd_barcode_type": 2,
   "amount": 25,
   "partner_transaction_reference": "{{$timestamp}}",
   "sender_customer_ref": "123456789",
   "recipient_customer_ref": "1147762",
   "sender_first_name": "Abraham",
   "sender_last_name": "Washington",
   "sender_address": "shanghai",
   "sender_zipcode": "94926",
   "notification_channel_type": "0"
}

Request Parameter Field Descriptions

Note: With regards to requiring parameters for Add Cash and Bill Pay, Y=Required, N=Not required, and C=Conditional.

Parameter	Type	Add Cash Required	Bill Pay Required	Description
gd_retailer_key	Int	Y	Y	Retailer for which the barcode is being generated. The barcode number might be different based on the retailer. GD will provide the list of RetailerKeys to the consumer of the API.
gd_barcode_type	Int	Y	Y	- 0 = None - 1 = BarcodeLink - 2 = BarcodeNumberForPrint - 3 = BarcodeNumberForView Note: - Use 1 to send a barcode link so the customer can generate a barcode at a later stage.Note: If this is selected. then notification_channel_type must be either SMS or Email. - Use 2 when online web and print option is selected. Default barcode expiration time is 48 hours. - Use 3 for mobile barcodes. Default barcode expiration time is 1 hour. The default value can be overwritten if there is a value configured in DB.
amount	Decimal	C	C	This is the amount for which the barcode is being generated. It is required when parameter amount_match_type = 1 or 2.
amount_match_type	Int	N	N	0 = Default. No constraints. Barcode can be consumed without constraint on amount. 1 = Partial consumption. Barcode must be consumed less than or equal to the amount specified in amount parameter (Not currently supported). 2 = Full consumption. Barcode must be consumed with exact amount specified in the amount parameter.
partner_transaction_refer ence	String	Y	Y	This is the transaction reference for the current transaction (i.e., send money request, etc.). The partner generates/maintains this value. Green Dot uses it for audit purposes.
sender_customer_ref	String	Y	Y	Identifier/Reference which the partner generates for the source (sender) of this transaction. Example: If A is sending money to B, this field identifies A's account. Note: If applicable, sender risk controls are calculated off this identifier.
sender_first_name	String	Y	Y	For Add Cash type, this field passes the depositor’s first Name. For Bill Pay type, it passes the bill payer’s first name.
sender_last_name	String	Y	Y	For Add Cash type, this field passes the cash depositor’s last name. For Bill Pay type, it passes the bill payer’s last name.
sender_email	String	Y	N	For Add Cash type, this field passes the cash depositor’s email address. For Bill Pay type, it passes the bill payer’s email address.
sender_phone	String	Y	N	For Add Cash type, this field passes the cash depositor’s phone number. For Bill Pay type, it passes the bill payer’s phone number.
sender_address	String	N	Y	For Add Cash type, this field passes the cash depositor’s address. For Bill Pay type, it passes the bill payer’s address.
sender_zipcode	String	N	Y	For Add Cash type, this field passes the cash depositor’s zip code. For Bill Pay type, it passes the bill payer’s zip code.
recipient_customer_ref	String	Y	Y	This is the Identifier/Reference the partner generates for the target/receiver of this transaction. Example: If A is trying to send money to B, this is an identifier/ reference of B's account. Note: If applicable, receiver risk controls are calculated off this identifier.
recipient_first_name	String	Y	N	For Add Cash type, this field passes the recipient’s first name. For Bill Pay type, it passes the payee’s first name. Note: If the bill pay partner cannot pass this data, we will block certain states during program configuration. For more details, contact your account manager.
recipient_last_name	String	Y	N	For Add Cash type, this field passes the recipient’s last name. For Bill Pay type, it passes the payee’s last name. Note: If the bill pay partner cannot provide this data, we will block certain states during program configuration. For more details, contact your account manager. Note: If the payee is a business, only provide a name in the recipient_first_name field.
recipient_email	String	Y	N	For Add Cash type, this field passes the recipient’s email address. For Bill Pay type, it passes the payee’s email address.
recipient_phone	String	Y	N	For Add Cash type, this field passes the recipient’s phone number. For Bill Pay type, it passes the payee’s phone number.
recipient_address	String	N	N	For Add Cash type, this field passes the recipient’s address. For Bill Pay type, it passes the payee’s address. Note: If the bill pay partner cannot pass this data, we will block certain states during program configuration. For more details, contact your account manager.
recipient_zipcode	String	N	N	For Add Cash type, this field passes the recipient’s zip code. For Bill Pay type, it passes the payee’s zip code. Note: If the bill pay partner cannot pass this data, we will block transactions in certain states. For more details, contact your account manager.
notification_channel_type	String	N	N	0 = none, 1 = SMS 2 – Email (only if Green Dot is sending barcode notifications on the partner’s behalf.)
gd_barcode_payment_type	Int	N	N	0 = Default. None. Barcode for cash-in. 1 = Deposit 2 = Payment 3 = Debit. Barcode for cash-out.

Response Model

{
   "gd_barcode_id": "string",
   "gd_barcode_id_expiration": "2022-05-05T14:42:05.124Z",
   "gd_retailer_key": 0,
   "gd_barcode_type": 0,
   "gd_barcode_payment_type": 0,
   "gd_retailer_name": "string",
   "partner_transaction_reference": "string",
   "gd_transaction_reference": "string", 
   "gd_response_code": 0,    
   "gd_response_message": "string",   
   "gd_response_date": "2022-05-05T14:42:05.124Z"
}

Sample Response – Bill Pay Partner

<barcode_response xmlns:i="http://www.w3.org/2001/XMLSchema-
instance" xmlns="http://greendotcorp.com/WebServices/Corporate/GDFNReloadServices/">
<gd_response_code>0</gd_response_code>
<gd_response_date>2021-01-18T06:44:43.4410039Z</gd_response_date>
<gd_response_message>Success</gd_response_message>
<gd_transaction_reference>dd21cd41-a305-4768-97c3-40062b35f247</gd_transaction_reference>
<partner_transaction_reference>1610952228</partner_transaction_reference>
<gd_barcode_id>629964901010005816100000000000</gd_barcode_id>
<gd_barcode_id_expiration>2021-04-18T06:44:12.277Z</gd_barcode_id_expiration>
<gd_barcode_payment_type>None</gd_barcode_payment_type>
<gd_barcode_type>BarcodeNumberForPrint</gd_barcode_type>
<gd_retailer_key>2480</gd_retailer_key>
<gd_retailer_name>7-Eleven</gd_retailer_name>
</barcode_response>

Authorizing and Confirming Barcode Transactions

The Barcode Generation API authorizes and confirms barcode transactions.

Structure of API Calls:

POST /v1/auth

POST /v1authconfirm

Searching and Retrieving Barcodes

Depending on the endpoint used, the Barcode Lookup API searches and retrieves barcode information for given input criteria. This includes:

Barcode Number
Retailer Key
Specific Customer ID
Range of start and end dates

Structure of API Calls:

GET /~/v1/barcode/{gd_barcode_id}/Retailer/{gd_retailer_key}/partner_ref/{partner_transaction_reference}

GET /~/v1/barcode/{gd_barcode_id}/Retailer/{gd_retailer_key}

GET /~/v1/barcode/sender_customer_ref/{sender_customer_ref}/start_date/{start_date}/end_date/{end_date}/partner_ref/{partner_transaction_reference?}

GET /~/v1/Barcode/sender_customer_ref/{sender_customer_ref}/start_date/{start_date}/end_date/{end_date}

Sample Request Parameters

URL: ~/v1/barcode/830324007490008112325460183192/Retailer/2433

URL: ~/v1/barcode/830324007490008112325460183192/Retailer/2433/partner_ref/1234

URL: ~/v1/barcode/sender_customer_ref/123456789/start_date/2020-01- 01/end_date/2020-05-28

Headers

{
   x-gdn-timestamp:2020-05-25T02:30:35Z 
   x-gdn-encryptiontype:1
   x-gdn-messageid:2020052500823 
   x-gdn-channeltype:1
   x-gdn-devicetype:2
   x-gdn-ipaddress:192.168.1.1  
   x-gdn-programnumber:Catalina-BC    
   x-gdn-signature:21AE309FF0A8162439B1458B857599D8ECE5EA155AFDB327BCED728B0B2DB8D5
}

Request Parameters Field Descriptions

Parameter	Type	Required	Description
gd_barcode_id	String	Yes	The barcode number, output from the Barcode Generation API.
gd_retailer_key	int	Yes	This is the Retailer selected when generating the barcode.
partner_transaction_reference	String	Optional	The unique, partner-generated transaction reference (if provided).
sender_customer_ref	String	Yes	The Customer ID provided by the sender.
start_date	DateTime	Yes	The barcode start date, YYYY-MM-DD.
end_date	DateTime	Yes	The barcode end date, YYYY-MM-DD. Must not exceed current date.

Sample Response Model

{
     "Barcodes": [
           {
                "gd_barcode_id": "string",
                "gd_barcode_id_expiration": "2022-05-06T13:07:44.722Z",
                "gd_retailer_key": 0,
                "gd_retailer_name": "string",
                "gd_barcode_change_date": "2022-05-06T13:07:44.723Z",
                "sender_customer_ref": "string",
                "gd_barcode_status": 0,
                "amount": 0
           }
     ],
     "gd_search_count": 0,
     "partner_transaction_reference": "string",
     "gd_transaction_reference": "string",
     "gd_response_code": 0,
     "gd_response_message": "string",  
     "gd_response_date": "2022-05-06T13:07:44.723Z"
}

Response Sample 1

<barcode_inquiry_response xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://greendotcorp.com/WebServices/Corporate/GDFNReloadServices/">
<gd_response_code>0</gd_response_code>
<gd_response_date>2020-05-29T06:48:03.9009349Z</gd_response_date>
<gd_response_message>Success</gd_response_message>
<gd_transaction_reference>1ac3503d-ec0a-4582-8d80-875bcc1cdf93</gd_transaction_reference>
<partner_transaction_reference></partner_transaction_reference>
<amount i:nil="true" />
<gd_barcode_change_date>2020-03-05T13:34:22.593Z</gd_barcode_change_date>
<gd_barcode_id>830324007490008112325460183192</gd_barcode_id>
<gd_barcode_id_expiration>2020-06-03T09:17:14.18Z</gd_barcode_id_expiration>
<gd_barcode_status>7</gd_barcode_status>
<gd_retailer_key>2433</gd_retailer_key>
<gd_retailer_name>CVS</gd_retailer_name>
<sender_customer_ref>123456789</sender_customer_ref>
</barcode_inquiry_response>

Response Sample 2

<barcode_inquiry_response xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://greendotcorp.com/WebServices/Corporate/GDFNReloadServices/">
<gd_response_code>0</gd_response_code>
<gd_response_date>2020-05-29T06:46:31.6900736Z</gd_response_date>
<gd_response_message>Success</gd_response_message>
<gd_transaction_reference>f9fb346d-da6b-43ef-bebe-3763525d3958</gd_transaction_reference>
<partner_transaction_reference>1234</partner_transaction_reference>
<amount i:nil="true" />
<gd_barcode_change_date>2020-03-05T13:34:22.593Z</gd_barcode_change_date>
<gd_barcode_id>830324007490008112325460183192</gd_barcode_id>
<gd_barcode_id_expiration>2020-06-03T09:17:14.18Z</gd_barcode_id_expiration>
<gd_barcode_status>7</gd_barcode_status>
<gd_retailer_key>2433</gd_retailer_key>
<gd_retailer_name>CVS</gd_retailer_name>
<sender_customer_ref>123456789</sender_customer_ref>
</barcode_inquiry_response>

Response Sample 3

<barcode_inquiry_response xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://greendotcorp.com/WebServices/Corporate/GDFNReloadServices/">
<gd_response_code>0</gd_response_code>
<gd_response_date>2020-05-29T06:46:31.6900736Z</gd_response_date>
<gd_response_message>Success</gd_response_message>
<gd_transaction_reference>f9fb346d-da6b-43ef-bebe-3763525d3958</gd_transaction_reference>
<partner_transaction_reference>1234</partner_transaction_reference>
<amount i:nil="true" />
<gd_barcode_change_date>2020-03-05T13:34:22.593Z</gd_barcode_change_date>
<gd_barcode_id>830324007490008112325460183192</gd_barcode_id>
<gd_barcode_id_expiration>2020-06-03T09:17:14.18Z</gd_barcode_id_expiration>
<gd_barcode_status>7</gd_barcode_status>
<gd_retailer_key>2433</gd_retailer_key>
<gd_retailer_name>CVS</gd_retailer_name>
<sender_customer_ref>123456789</sender_customer_ref>
</barcode_inquiry_response>

Response Sample 4

<barcode_list_inquiry_response xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://greendotcorp.com/WebServices/Corporate/GDFNReloadServices/">
<gd_response_code>0</gd_response_code>
<gd_response_date>2020-05-29T06:38:52.3690967Z</gd_response_date>
<gd_response_message>Success</gd_response_message>
<gd_transaction_reference>c59d2656-28c8-4c0c-9b0b-752ebcc6f245</gd_transaction_reference>
<partner_transaction_reference>401db81d-59bf-4528-9b82-95626731d02d</partner_transaction_reference>
<Barcodes>
<barcode>
<amount i:nil="true" />
<gd_barcode_change_date>2020-03-05T13:34:22.593Z</gd_barcode_change_date>
<gd_barcode_id>830324007490008112325460183192</gd_barcode_id>
<gd_barcode_id_expiration>2020-06-03T09:17:14.18Z</gd_barcode_id_expiration>
<gd_barcode_status>7</gd_barcode_status>
<gd_retailer_key>2433</gd_retailer_key>
<gd_retailer_name>CVS</gd_retailer_name>
<sender_customer_ref>1147762</sender_customer_ref>
</barcode>
<barcode>
<amount>22.2200</amount>
<gd_barcode_change_date>2020-05-28T15:36:09.387Z</gd_barcode_change_date>
<gd_barcode_id>830324007490008112326038087609</gd_barcode_id>
<gd_barcode_id_expiration>2020-08-26T15:36:08.933Z</gd_barcode_id_expiration>
<gd_barcode_status>1</gd_barcode_status>
<gd_retailer_key>2433</gd_retailer_key>
<gd_retailer_name>CVS</gd_retailer_name>
<sender_customer_ref>1147762</sender_customer_ref>
</barcode>
</Barcodes>
<gd_search_count>2</gd_search_count>
</barcode_list_inquiry_response>

Response Field Descriptions

Parameter	Type	Description
gd_search_count	int	The total number of barcodes found in the search.
Barcodes	list	This is the Barcode information list.
gd_barcode_id	String	The barcode number or link code based on the type of barcode generated.
gd_barcode_id_expiration	DateTime	Expiration date/time of the barcode or barcode link based on the type selected.
gd_retailer_key	int	Retailer selected for generating the barcode.
gd_barcode_type	int	The barcode type.
gd_retailer_name	String	This is the retailer’s name as maintained in Green Dot’s system.
gd_barcode_change_date	DateTime	This is the last barcode change date.
sender_customer_ref	String	This is an echo of the sender_customer_ref field, which is received as input.
gd_barcode_status	int	1 = New 2 = Pending 3 = Consumed 4 = Voided 5 = Expired 6 = Cancelled 7 = Declined
amount	Decimal	When applicable, this is the amount for which the barcode was generated.
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.

Obtaining a List of Retailers

The Retailer API searches and retrieves a list of retailers for a given program.

Structure of API Calls:

GET ~/v1/retailers

GET ~/v1/retailers/partner_ref/{partner_transaction_reference}

Sample Request Parameters

URL: ~/v1/retailers

URL: ~/v1/retailers/partner_ref/1234

Headers

{
   x-gdn-timestamp:2020-06-18T06:07:44Z
   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
   x-gdn-signature:8674485661DF66A6A7F28CD23AC0D3464EAAB455409CB63D3A845446728CDFF4
}

Request Parameters Field Descriptions

Parameter	Datatype	Required	Description
partner_transaction_reference	String	Optional	Unique, partner-generated transaction reference (if provided).

Response Model

{
      "retailer_list": [
            {
                  "retailer_key": 0,
                  "short_name": "string",
                  "description": "string"
            }
      ],
      "partner_transaction_reference": "string",
      "gd_transaction_reference": "string",
      "gd_response_code": 0,      
      "gd_response_message": "string",  
      "gd_response_date": "2022-05-06T13:07:44.798Z"
}

Sample Response 1

<get_retailer_response xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://greendotcorp.com/WebServices/Corporate/GDFNReloadServices/">
<gd_response_code>0</gd_response_code>
<gd_response_date>2020-06-19T07:34:50.8240298Z</gd_response_date>
<gd_response_message>Success</gd_response_message>
<gd_transaction_reference>0883f7c0-c125-4985-baa4-e15ad290315f
</gd_transaction_reference>
<partner_transaction_reference></partner_transaction_reference>
<retailer_list>
<retailer>
<description>7-Eleven</description>
<retailer_key>2481</retailer_key>
<short_name>7ELVN</short_name>
</retailer>
<retailer>
<description>CVS</description>
<retailer_key>2433</retailer_key>
<short_name>CVS</short_name>
</retailer>
<retailer>
<description>Duane Reade</description>
<retailer_key>10796</retailer_key>
<short_name>DuaneReade</short_name>
</retailer>
<retailer>
<description>Rite Aid</description>
<retailer_key>2460</retailer_key>
<short_name>RIAID</short_name>
</retailer>
retailer>
<description>Walgreens</description>
<retailer_key>10794</retailer_key>
<short_name>Walgreens</short_name>
</retailer>
<retailer>
<description>Walmart</description>
<retailer_key>2812</retailer_key>
<short_name>Walmart</short_name>
</retailer>
</retailer_list>
</get_retailer_response>

Sample Response 2

<get_retailer_response xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://greendotcorp.com/WebServices/Corporate/GDFNReloadServices/">
<gd_response_code>0</gd_response_code>
<gd_response_date>2020-06-19T07:33:31.9310279Z</gd_response_date>
<gd_response_message>Success</gd_response_message>
<gd_transaction_reference>110892f9-3ad7-45a5-8c18-dda0cb1664d0
</gd_transaction_reference>
<partner_transaction_reference>1234</partner_transaction_reference>
<retailer_list>
<retailer>
<description>7-Eleven</description>
<retailer_key>2481</retailer_key>
<short_name>7ELVN</short_name>
</retailer>
<retailer>
<description>CVS</description>
<retailer_key>2433</retailer_key>
<short_name>CVS</short_name>
</retailer>
<retailer>
<description>Duane Reade</description>
<retailer_key>10796</retailer_key>
<short_name>DuaneReade</short_name>
</retailer>
<retailer>
<description>Rite Aid</description>
<retailer_key>2460</retailer_key>
<short_name>RIAID</short_name>
</retailer>
<retailer>
<description>Walgreens</description>
<retailer_key>10794</retailer_key>
<short_name>Walgreens</short_name>
</retailer>
<retailer>
<description>Walmart</description>
<retailer_key>2812</retailer_key>
<short_name>Walmart</short_name>
</retailer>
</retailer_list>
</get_retailer_response></get_retailer_response>

Response Field Descriptions

Parameter	Datatype	Description
retailer_list	list	Retailer List for input program number
short_name	String	Short name for retailer
retailer_key	int	Greendot retailer key
description	String	Retailer 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.