Optional API Add-Ons Endpoints

Generate Verifications

This API generates contact verifications.

API Call Structure

POST /programs​/{programCode}​/contactVerifications

Request Body

{
	"accountIdentifier": "string",
	"verificationEventType": "string",
	"contactType": "string",
	"communicationType": "string",
	"contactHandle": "string",
	"firstName": "string",
	"lastName": "string",
	"productCode": "string",
	"retailCardIdentifier": "string"
}

Response Body

{
	"contactVerificationIdentifier": "string",
	"responseDetails": [
		{
			"code": 0,
			"subCode": 0,
			"description": "string",
			"url": "string"
		}
	]
}

Check Verifications

This API checks contact verifications.

API Call Structure

PUT /programs​/{programCode}​/contactVerifications/{contactVerificationIdentifier}

Request Body

{
	"contactVerificationIdentifier": "string",
	"verificationCode": "string"
}

Response Body

{
	"responseDetails": [
		{
			"code": 0,
			"subCode": 0,
			"description": "string",
			"url": "string"
		}
	]
}

Verify User Address

The Address Verification API verifies a user's address by returning a list of suggested addresses and address-validity indicators.

API Call Structure

POST /programs/{programCode}/addressVerification

📘

This endpoint may be called to mitigate returned mail issues.

Request Body

{
   "addressLine1": "string",
   "addressLine2": "string",
   "city": "string",
   "state": "string",
   "zipCode": "string"
}

Response Body

{
	"addresses": [
		{
		"addressLine1": "string",
		"addressLine2": "string",
		"city": "string",
		"state": "string",
		"zipCode": "string",
		"countryCode": "string",
		"type": "string"
		}
	],
	"isValidAddress": true,
	"matchLevel": "string",
	"responseDetails": [
		{
		"code": 0,
		"subCode": 0,
		"description": "string",
		"url": "string"
		}
	]
}

Obtain Contact Verification Status

This API obtains the status of contact made by a specific contact type.

API Call Structure

GET /programs/{programCode}/verification/status/{sessionIdentifier}

Response Body

{
	"sessionIdentifier": "string",
	"contactVerificationStatus": 0,
	"contactType": "phone",
	"communicationType": "sms",
	"responseDetails": [
	{
	   "code": 0,
	   "subCode": 0,
	   "description": "string",
	   "url": "string"
	}
   ]
}

Sample Request

{
   "addressLine1":"123 Timbuktu St",
   "addressLine2":"",
   "city":"Pasadena",
   "state":"CA",
   "zipCode":"91107",
   
}

Sample Response

{
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"string",
         "url":"string"
      }
   ],
   "addresses":[
      {
         "addressLine1":"215 Main St.",
         "addressLine2":"Suite 200",
         "city":"Pasadena",
         "state":"CA",
         "zipCode":"91107",
         "addressType":"camelCasedStringOfValueReturnedFromFraudAPI""countryCode":"USA"
      }
   ],
   "isValidAddress":true,
   "matchLevel":"verified"
}

Address Verification Response Codes

Click here to view a list of response codes for the Address Verification API.

Track My Mail

This API returns the delivery information for a card (payment instrument) that was most recently shipped to a user with the same PAN (card number displayed on the front of the card) as the provided paymentInstrumentIdentifier.

Emboss Types

An optional emboss type attribute in the TMM response to specifies the following GO2bank or SCC card - issue activity. Emboss types include:

• REP – This is a replacement card.
• LSR – This is a replacement for a lost/stolen card.
• REI – This is a reissued card due to expiration.

Obtain Delivery Status Information

This API returns delivery information for most recently shipped payment instruments (cards) only.

Note: Delivery information is only available for 60 days after the card is sent to fulfillment

API Call Structure

GET /programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}/deliveryStatus

Sample Response Body

{
   "trackingNumber":"0031011111111111111111111111",
   "deliveryMethodCode":"reg",
   "deliveryMethod":"Regular",
   "deliveryStatusCode":"printing",
   "deliveryStatus":"Card In Production",
   "shippedDate":"2019-12-03T11:34:53.99Z",
   "estimatedArrivalDate":"2019-12-13T00:00:00Z",
   "last4Pan":"7040",
   "bin":"499998",
   "cardHolderName":"Jack White",
   "productMaterialType":"pvc",
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"API operation was successful.",
         "url":"http://tbd"
      }
   ]
}

Response Codes

Delivery information for an event occurring before the Payment Instrument issued date will not be returned. If the Payment Instrument provided in the request has been activated, the deliveryStatusCode will be returned as activated.

Tracking Newly Ordered and Activated Cards

Adjustments

This API adjusts BaaS account balances. It can be used to credit or debit an account for purposes, such as adjustments and funds transfers that cover ACH sweeps and anyDebit transfers. Each adjustment has a corresponding reversal adjustmentType

• When a reversal is requested, the request is considered a new adjustment and it will include an amount to rollback. Note: Green Dot will use this amount to rollback, instead of looking for the original transaction
• A daily batch will be provided to allow you, the partner, to reconcile with the previous day’s balance adjustments (including credits and debits).

Note: Before its use, this API requires partner-specific configurations before it can be used.

Transactions Initiated by Adjustment API

An adjustmentIdentifier and an adjustment description will be returned via the GET Transactions webhook and API for any transactions that are initiated from the Adjustment API.

Example

• A transaction is initiated via an Adjustment API call.
• The transaction is processed.
• The transaction webhook will include the adjustmentIdentifier under postedInternalTransactionData.
• A GET Transactions API call covering the period of the Adjustment API request will also include the adjustmentIdentifier under postedInternalTransactionData.
• The description returned will be based on the description provided via the Adjustment API.

Sample Response Snippet

"postedInternalTransactionData":{
   "adjustmentIdentifier":"20433e90-0935-4ca1-8beb-ae7de12ef759",
   "description":"Value passed to adjustmentDescription"
}

• For additional information on Transaction Webhooks, click here.
• For additional information on GET Transactions, click here.

Crediting Partner Accounts

Partners can credit their accounts using an API call containing the “promo” adjustmentType.

How it Works

Simply call POST /programs/{programCode}/accounts/{accountIdentifier}/adjustments to request a promo adjustment

Include the following in your request along with a description:

• After the request is processed, a promo transaction is created containing:
  • Promo credit adjustment
  • postedInternalTransaction.transactionDescription containing the adjustmentDescription
• Note: Partners will need to throttle their calls to this API to avoid overloading the system.

Sample Request

POST /programs/programCode/accounts/561d3e0d-3b06-4083-a140-3348656fb628/adjustments{
   "adjustmentIdentifier":"6262f1df-0548-4a4c-92ed-bee6a746eaaa",
   "amount":"12.86",
   "currency":"USD",
   "adjustmentType":"promo",
   "adjustmentDescription":"Acme Cashback",
   
}

Sample Response:-

{
   "adjustmentStatus":"completed",
   "adjustmentStatusReason":"success",
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Instruction Credit and instruction Debit

• Usage of the POST /adjustments endpoint is limited to partners based on what Adjustment Types they have access to.
  • To facilitate automated testing, the instructionCredit and instructionDebit Adjustment Types are available to all partners in the Partner Integration Environment (PIE) only.
  • In PIE, use instructionCredit to deposit money to a testing account and instructionDebit to debit money from a testing account.

Sample Request Bodies

Sample Request – instructionCreditL:-

{
   "adjustmentIdentifier":"a166254f-d7a6-491b-9bcc-f142c973eb42",
   "amount":"5",
   "currency":"USD",
   "adjustmentType":"instructionCredit",
   "adjustmentDescription":"Partner Funding Instruction Credit",
   "fee":""
}

Sample Request – instructionDebit:-

{
   "adjustmentIdentifier":"9b8188ed-32b7-418f-82aa-ccffdc4c8030",
   "amount":"5",
   "currency":"USD",
   "adjustmentType":"instructionDebit",
   "adjustmentDescription":"Partner Funding Instruction Debit",
   "fee":"0"
}

Create Adjustments

API Call Reference

POST /programs/{programCode}/accounts/{accountIdentifier}/adjustments

• The following adjustment types must be specifically configured for a program code in order to be used by a partner.
  • promo and promoReversal
  • instructionCredit and instruction
  • Debit disbursement, disbursementReversal
  • anyDebitOut, anyDebitOutReversal
  • achOut, achOutReversal
• If an adjustmentType has not been configured for a program code, then the request will be rejected.
• If you have any further questions, please contact your Green Dot Product liaisons.

Sample Request:-

{
   "adjustmentIdentifier":"string",
   "amount":10.00,
   "currency":"string",
   "adjustmentType":"string",
   "adjustmentDescription":"string""fee":5.00
}

Sample Response:-

{
   "adjustmentStatus":"string",
   "adjustmentStatusReason":"string",
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"string",
         "url":"string"
      }
   ]
}

Response Parameters

Check Adjustment Status

This API is used to check the status of adjustments to BaaS account balances.

API Call Reference

GET /programs/{programCode}/accounts/{accountIdentifier}/adjustments/{adjustmentIdentifier}

Sample Response Body

{
   "adjustmentStatus":"string",
   "adjustmentStatusReason":"string",
   "currency":"string",
   "adjustmentDescription":"string",
   "transactionDate":"string",
   "amount":"string",
   "fee":"string",
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"string",
         "url":"string"
      }
   ]
}

Sample Response - When adjustment call for cardless funds returns successfully:-

{
   "responseHeader":{
      "responseId":"cb636f2a-20ed-43ab-9d90-02ccca12b57d",
      "statusCode":0,
      "subStatusCode":0,
      "message":"Success"
   },
   "adjustmentIdentifier":"274f5e17-0c63-4c8d-8d16-abd5fee4531a",
   "amount":9.4000,
   "currency":"USD",
   "adjustmentType":"cardlessFundsPickup",
   "adjustmentDescription":"Cardless Funds Pickup",
   "fee":0.0,
   "transactionDate":"2021-06-23T11:41:21.120Z",
   "debitToNegative":false,
   "adjustmentStatus":"completed",
   "adjustmentStatusReason":"success"
}

Response Parameters

Account Features Overview

This API allows Partners to provide additional account features such as Backup Balance or Cash Back Rewards to their customers.

Note: A feature can only be used if it has been agreed upon during onboarding and included in the onboarding contract.

Enroll or Unenroll Customer Account Feature

API Call Reference

PUT /programs/{programCode}/accounts/{accountIdentifier}/features/{featureId}

Negative Balance Feature

• The Negative Balance feature is available to be used by Partners. This feature can only be requested during onboarding.
• Feature ID: NB100 – Negative balance $100 feature code
• Depending on the terms and conditions included in the daa that is accepted during account registration, some features may need to be explicitly accepted via the PUT /accounts endpoint.
• Initially, all programs will be configured to not enforce terms acceptance.
• Once the system is configured to enforce terms acceptance for a feature, any customer that does not accept the terms for that feature will not be allowed to use the feature.
• For any programs, where customers are already using features that may require explicit terms acceptance, a data backfill will be required for those customers prior to enforcement being enabled.
• Please work with your Green Dot Account Manager and/or Product Manager to understand the impact and transition plan for your program and features.

UCB 1 – 4

• UCB tiers are cash back reward tiers based on program setup. These features are mutually exclusive. For example, if a customer is enrolled in UCB 1, then they cannot be enrolled in UCB 2, 3, or 4.
• However, a customer can be enrolled in NB100 and a UCB feature. For example, NB100 and UCB 2.

Remote Check Deposit Tiers (RCDTier)

• Check Deposit Tiers are required to use MRDC and to manage MRDC hold periods on an account.
• CDTiers are mutually exclusive, meaning an account can only be enrolled in one CDTier at a time.
• Call PUT /accounts/{accountIdentifier}/features/{featureId} to assign a CDTier to an account.

Response Codes

Negative Balance Terms

If a customer chooses to opt out of (does not accept) the terms for Negative Balance but they have the Negative Balance feature (NB100) already enabled on their account, then they will automatically be unenrolled from NB100.

How it Works

If PUT /features/{featureid} is used to unenroll a customer from the Negative Balance feature, then the Negative Balance terms will automatically be opted out of.

Sample Request

{
   "authorize":false
}

Sample Response

{
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

If PUT /accounts/{accountIdentifier} is used to opt out of the Negative Balance terms first, and the Negative Balance feature is already active on the customer’s account, then the request will fail.

Sample Request

{
   "termsAcceptances":[
      {
         "termsIdentifier":"negBal",
         "termsAcceptanceFlag":"false",
         "termsAcceptanceDateTime":"2020-04-03T09:12:11.627Z"
      }
   ]
}

Sample Response

{
   "responseDetails":[
      {
         "code":5,
         "subCode":58,
         "description":"Terms cannot be opted out because feature is still in use",
         "url":"http://tbd"
      }
   ]
}

Legacy Request Parameters

• Call PUT /programs/{programCode}/accounts/{accountIdentifier}/features/{featureid}
• In the request body, there will be one Boolean field called “authorize”. The authorize field will contain two options, true or false.
  • True means to enroll the customer into the feature.
  • False means to unenroll the customer from the feature.

Note: If a customer tries to enroll in a feature that does not exist, an HTTP Status Code 503 with the following message will be returned

• No ProductFeatureGroupKey exists for specified productFeatureGroupKey

Sample Response Body

{
   "responseDetails":{
      "code":"0",
      "subCode":"0",
      "description":"string",
      "url":"http://tbd"
   }
}

Obtain Customer Enrolled Features

This API retrieves the active features in which customers are enrolled.

API Call Reference

GET /programs/{programCode}/accounts/{accountIdentifier}/features

Sample Response Body

{
   "feautures":[
      "nb100"
   ]"responseDetails":{
      "code":"0",
      "subCode":"0",
      "description":"string",
      "url":"http://tbd"
   }
}

Note: If a customer is not enrolled in any additional account features, the following response will be returned.

{
   "features":[
      
   ],
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Response Sub-Codes