Interest Rate API Endpoints

Offer Interest-Bearing Purses to Customers

This endpoint allows Partners to offer interest bearing savings purses to their customers. Multiple interest rates are available and will be determined based on partner and business requirements.

Note: Interest Rate Tier information is only included in responses to POST /purses requests that include interestRateTier.
Refer to Endpoint: POST /accounts/{accountIdentifier}/purses for requests without interestRateTier information.

How it Works

• Submit a POST programs/{programCode}/accounts/{accountIdentifier}/purses request to create a new savings purse and provide a valid interestRateTier. The current enums (options) for interestRateTier are tier1 and tier2.
• A response will be received containing the:
  • interestRateTier
  • interestRateTierIdentifier
  • interestYieldStartDate
• Annual Percentage Yield (APY)

Things to Remember

• Partners will have the ability to assign interest rate tiers to customer savings purses, as well as to move customers from one tier to another.
• An interestRateTier is an optional feature. However, for an interestRateTier to be applied to a savings purse and for validations to be performed, an interestRateTier must be provided in the request.
• An interestRateTier is validated based on the productInterestTier, which means it will be validated based on what has been configured for the product and purse type associated with the account.
• Contact your Green Dot representative to request configuration with interest rate tiers

Set or Auto Align the Interest Yield Start Date When Creating a Savings Purse

Partners can also set a new interestYieldStartDate or auto align the interestYieldStartDate with the accountCycleDay (Bill Cycle Date) for interest rate tiers.

How it Works

• Set interestYieldStartDate when creating a Savings Purse:
  • Call POST …/accounts/{accountIdentifier}/purses with:
    • An Interest Rate Tier
    • An interestYieldStartDate – Must be the day of the request or after
  • If the autoAlignStartDate is false, then the interestYieldStartDate is set to the date provided.
  • If an interestYieldStartDate is not provided and the autoAlignStartDate is false, then the interestYieldStartDate will default to the current date of the request.
• Align interestYieldStartDate when creating a Savings Purse:
  • Call POST …/accounts/{accountIdentifier}/purses with:
    • An Interest Rate Tier
    • An interestYieldStartDate – Must be the day of the request or after
• If the autoAlignStartDate is true, then the interestYieldStartDate will be set to start on the next accountCycleDay (Bill Cycle Date).
• Note: If the interestYieldStartDate is not provided, the accountCycleDay will be on or after the current date of the request.

Request & Response Bodies

Sample Request Body Snippet:-
(Creating a Savings Purse - autoAlignStartDate: false and interestYieldStartDate provided)
{
   "purseType":"savings",
   "purseDescription":"SavingsgoalaVGzR",
   "iconName":"IconNameTesting",
   "goalAmount":"88.88",
   "interestRateTier":"tier3",
   "interestYieldStartDate":"2020-07-15T21:09:24.862Z",
   "autoAlignStartDate":false
}

Sample Response Body Snippet:-
{
   "purse":{
      "purseIdentifier":"ef85c080-c11e-499c-b25f-6a5fe4c76fe9",
      "purseType":"savings",
      "purseDescription":"SavingsgoalaVGzR",
      "availableBalance":0.0,
      "ledgerBalance":0.0,
      "availableBalanceAsOfDateTime":"2020-07-13T21:09:26Z",
      "ledgerBalanceAsOfDateTime":"2020-07-13T21:09:26Z",
      "isHidden":false,
      "status":"active",
      "goalAmount":88.88,
      "iconName":"IconNameTesting",
      "createDate":"2020-07-13T14:09:26.079Z",
      "changeDate":"2020-07-13T14:09:26.079Z",
      "purseNumber":"15156",
      "interestRateTierIdentifier":"eba23a6d-c7fd-43f4-b07b-4ae590d67bae",
      "interestRateTier":"tier3",
      "interestYieldStartDate":"2020-07-15T23:02:51Z",
      "APY":1.000
   },
   "responseDetails”: [
 {
 "code": 0,
 "subCode": 0,
 "description": "Success",
 "url": "http://tbd"
 }
 ]
}

Sample Request Body Snippet:-
(Creating a Savings Purse - autoAlignStartDate: true and interestYieldStartDate not provided)
{
   "purseType":"savings",
   "purseDescription":"SavingsgoalYAfmT",
   "iconName":"IconNameTesting",
   "goalAmount":88.88,
   "interestRateTier":"tier4",
   "interestYieldStartDate":"",
   "autoAlignStartDate":"true"
}

Sample Response Body Snippet:-
{
   "purse":{
      "purseIdentifier":"8d3bb5af-da59-424f-86ef-e0d949bd71c1",
      "purseType":"savings",
      "purseDescription":"SavingsgoalYAfmT",
      "availableBalance":0.0,
      "ledgerBalance":0.0,
      "availableBalanceAsOfDateTime":"2020-07-13T21:13:10Z",
      "ledgerBalanceAsOfDateTime":"2020-07-13T21:13:10Z",
      "isHidden":false,
      "status":"active",
      "goalAmount":88.88,
      "iconName":"IconNameTesting",
      "createDate":"2020-07-13T14:13:10.740Z",
      "changeDate":"2020-07-13T14:13:10.740Z",
      "purseNumber":"39372",
      "interestRateTierIdentifier":"1be2b101-9cd7-4d6b-99af-0d1f3521958f",
      "interestRateTier":"tier4",
      "interestYieldStartDate":"2020-08-13T21:13:10Z",
      "APY":1.250
   },
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Response Codes

Add Interest Rate Tiers

This endpoint allows Partners to add interestRateTiers to existing primary and savings purses.

How it Works

To successfully add an interest rate tier to an existing purse, call POST /purses/{purseIdentifier}/interestRateTiers and include the interestRateTier you would like to add to the purse.

A response containing the interestRateTierIdentifier, interestRateTier, interestYieldStartDate and the Annual Percentage Yield (APY) will be returned.

The interestYieldStartDate will be set to the current date, if you are adding an interestRateTier to the purse for the first time.

If the purse already has an interestRateTier applied, then the interestYieldStartDate will be set to the next anniversary of the billing cycle.

Note: The next anniversary of the billing cycle will be returned as the accountCycleDay in the POST /enrollments, GET /accounts, and GET /enrollments endpoint responses.

Set or Auto Align the interestYieldStartDate

• Align interestYieldStartDate when adding an Interest Rate Tier to an existing purse:
  • Call POST …/accounts/{accountIdentifier}/purses/{purseIdentifier}/interestRateTiers with an interestYieldStartDate (optional).
  • If the autoAlignStartDate is true, the interestYieldStartDate is set to start on the next accountCycleDay (Bill Cycle Date).
  • Note:
    • If the interestYieldStartDate is not provided, the accountCycleDay will be on or after the current date of the request.
    • If applicable - The interestYieldEndDate of the previous Interest Rate Tier on the purse is automatically set to the day before the new Interest Rate Tier’s interestYieldStartDate.
• Set interestYieldStartDate when adding initial (first) Interest Rate Tier to an existing purse:
  • Call POST …/accounts/{accountIdentifier}/purses/{purseIdentifier}/interestRateTiers with an interestYieldStartDate (optional).
  • If the purse does not have an interestRateTier applied to it and:
    • The autoAlignStartDate is false
    • The interestYieldStartDate is the current date of the request or after
  • The interestYieldStartDate is set to the date provided in the request.

Example Request & Responses

Sample Request Body Snippet:-
(Existing Purse - autoAlignStartDate: true and interestYieldStartDate provided)
{
   "interestRateTier":"tier1",
   "interestYieldStartDate":"2020-07-15T19:20:46.648Z",
   "autoAlignStartDate":"true"
}

Sample Response Body Snippet:-
{
   "interestRateTierIdentifier":"8df0ef9e-369d-4d97-9533-d56f77389e39",
   "interestYieldStartDate":"2020-07-15T19:20:46.648Z",
   "apy":"1.250",
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Sample Request Body Snippet:-
(Existing Purse - autoAlignStartDate: false and interestYieldStartDate provided)
{
   "interestRateTier":"tier2",
   "interestYieldStartDate":"2020-07-15T19:44:47.255Z",
   "autoAlignStartDate":"false"
}

Sample Response Body Snippet:-
{
   "interestRateTierIdentifier":"98528f0b-a43f-475a-8676-7186d41166d4",
   "interestYieldStartDate":"2020-07-15T19:44:47.255Z",
   "apy":"0.750",
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Sample Request Body Snippet:-
("Existing Purse - autoAlignStartDate":true,
"interestYieldStartDate not provided)"{
   "interestRateTier":"tier4",
   "interestYieldStartDate":"",
   "autoAlignStartDate":"true"
}

Sample Response Body Snippet:-
{
   "interestRateTierIdentifier":"8df0ef9e-369d-4d97-9533-d56f77389e39",
   "interestYieldStartDate":"2020-08-13T19:44:47.255Z",
   "apy":"1.250",
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Response Codes

Update an Interest Rate Tier

This endpoint is used to:

• End an interest rate tier on a user’s account by adding an end date.
• Remove an end date from an interest rate tier and return it to active on a user’s account.
• Update an interest rate tier end date to the day before the next bill cycle date

How to add an end date to an interest rate tier:

• An interestRateTier can be ended or closed by adding an end date to it. Simply call PUT /purses/{purseIdentifier}/interestRateTier/{interestRateTierIdentifier} with:
• A valid interestRateTierIdentifier
• A valid end date (must be in the future and the last day of a monthly cycle for the account)
• Note: The interestRateTier that the end date is being applied to, cannot have an end date already and it must have the most recent start date if there are multiple tiers on the account.
• An interestRateTier that is scheduled to start at a future date can be updated if it has a valid interestRateTierIdentifier and a valid interestRateTier enum.
• Simply call PUT /purses/{purseIdentifier}/interestRateTier/{interestRateTierIdentifier} to update.
• Note: Adding an end date to an interestRateTier and updating an interestRateTier that is scheduled to start at a future date can both be done in a single call. So, submitting a valid end date AND a new interestRateTier will update both fields.

How to remove an end date from an interest rate tier:

• Partner calls PUT …/purses/{purseIdentifier}/interestRateTier/{interestRateTierIdentifier} and the following is true:
• Current interest rate tier has an end date that is today or in the future
• No interest rate tier is scheduled to follow the current interest rate tier
• removeEndDateFlag is true
• Optional interestYieldEndDate is provided – Ignored if removeEndDateFlag is true
• The end date is removed, and the interest rate tier remains active.

How to update an end date on an interest rate tier:

• Partner calls PUT …/purses/{purseIdentifier}/interestRateTier/{interestRateTierIdentifier} and the following is true:
• Current interest rate tier has an end date that is today or in the future
• Provided interest rate tier has an end date that is today or in the future
• No interest rate tier is scheduled to follow the current interest rate tier
• The interest rate tier end date is updated to:
• The day before the next bill cycle on or after the new interestYieldEndDate or
• If no interestYieldEndDate is provided, the day before the very next bill cycle date occurs
• The updated end date is included in the response.

Sample Request and Responses

Sample Request Body - Add an End Date to an interestRateTier:-
{
   "interestRateTier":"tier1",
   "interestYieldEndDate":"2020-06-14T19:44:47.255Z"
}

Sample Response:-
{
   "interestRateTierIdentifier":"21d30f48-43d1-4eed-a747-c163f9459528",
   "interestYieldStartDate":"2020-05-15T19:44:47.255Z",
   "interestYieldEndDate":"2020-06-14T19:44:47.255Z",
   "apy":"2.000",
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Sample Request Body - Update Future interestRateTier to New Tier with an End Date:-
{
   "interestRateTier":"tier2",
   "interestYieldEndDate":"2020-07-14T19:44:47.255Z"
}

Sample Response:-
{
   "interestRateTierIdentifier":"d74f53c1-e4f2-45e6-8934-2027139449e2",
   "interestYieldStartDate":"2020-06-15T19:44:47.255Z",
   "interestYieldEndDate":"2020-07-14T19:44:47.255Z",
   "apy":"2.250",
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Response Codes

Retrieve Interest Rate Information

Partners who are configured to offer interest bearing savings purses can also provide interest rate information to their customers and support teams using the following endpoints:

• GET programs/{programCode}/accounts/{accountIdentifier}/purses
• GET programs/{programCode}/enrollments/accounts/{accountIdentifier}

How it Works

When purse or account information is requested using GET programs/{programCode}/accounts/{accountIdentifier}/purses or GET /programs/{programCode}/enrollments/accounts/{accountIdentifier}, the response will include:

• The current and active interestRateTier
• The interestRateTierIdentifier
• The interestYieldStartDate
• The Annual Percentage Yield (APY) at the time of the request

Note: No interest rate information will be returned for purses that have not been configured with an interestRateTier. Contact your Green Dot representative to request configuration with interest rate tiers.

Sample Response:-
{
   "purses":[
      {
         "purseIdentifier":"111997ea-46d2-4e15-bec6-8d0fdb332222",
         "purseType":"primary",
         "purseDescription":"Savings1",
         "availableBalance":3.27,
         "ledgerBalance":3.27,
         "availableBalanceAsOfDateTime":"2020-03-05T18:41:19Z",
         "ledgerBalanceAsOfDateTime":"2020-03-05T18:26:05Z",
         "isHidden":false,
         "status":"active",
         "createDate":"2019-08-21T06:41:19.5Z",
         "changeDate":"2020-03-05T10:41:20.253Z",
         "purseNumber":"12345",
         "If an interestRateTier is not applied to a purse",
         "the following properties will not be returned":"interestRateTierIdentifier":"6d49e4eb-6b6a-4b5c-9dc4-81446cc66a80",
         "interestRateTier":"tier1",
         "interestYieldStartDate":"2020-03-05",
         "APY":"1.23"
      }
   ],
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Retrieve Interest Paid Information

Partners who are configured to offer interest bearing savings purses can also provide interest paid information to their customers and support teams using GET /programs/{programCode}/accounts/{accountIdentifier}/transactions.

How it Works

• When transaction information is requested for an account using GET /programs/{programCode}/accounts/{accountIdentifier}/transactions, the response will include information about the purse the interest was applied to, as well as the amount of interest applied.
• The transactionType will be interest.
• The transactionTypeDescription will be Interest Paid.

Sample Response:-
{
   "transactions":[
      {
         "paymentIdentifier":"7b9258f5-6125-40fb-af5e-ab3ecf6e87a3",
         "transactionIdentifier":"ae1803b5-5d9a-424e-be9b-829fa9628821",
         "transactionType":"interest",
         "transactionTypeDescription":"Interest Paid",
         "transactionStatus":"completed",
         "accountIdentifier":"049d7c6e-2f1f-4c5b-96dc-6aa36323a468",
         "purseIdentifier":"5daf99c7-1164-4c1f-a349-8c1b9149d2ef",
         "bin":"500000",
         "last4Pan":"4900",
         "currency":"USD",
         "postedDateTime":"2020-05-12T23:44:19Z",
         "transactionAmount":“6.12”,
         "isCredit":true,
         "postedInternalTransactionData":{
            "adjustmentIdentifier":"2d5ae387-24c4-41f9-a5c0-780cd8321cf6",
            "description":"Interest Earned Credit",
            "transferType":"None"
         }
      }
   ],
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Obtain Interest Rate Tiers

This endpoint allows Partners to retrieve a list of all Interest Rate Tiers and Annual Percentage Yields (APYs) associated with a specific purseIdentifier.

Note: Interest Rate Tiers that are deleted using DELETE /purses/interestRateTier/{interestRateTierIdentifier} will not be included in responses to this endpoint.

Response Codes

Obtain List of Product Code Interest Rate Tiers and APYs by Program

This endpoint allows Partners to retrieve a list of all Product based Interest Rate Tiers and Annual Percentage Yields (APYs) associated with a specific programcode.

Obtain List of Product Code Interest Rate Tiers and APR Yields

This endpoint allows Partners to retrieve a list of all Interest Rate Tiers and Annual Percentage Yields (APYs) associated with a specific productCode.

Delete Interest Rate Tier

This endpoint allows Partners to delete interest rate tiers.

Response Codes

INT-1099 Forms

🚧

This feature is only available to programs that are configured to offer interest-bearing accounts. Please contact your Green Dot liaison to request Interest Rate configuration.

INT-1099 forms are generated for customers who earn $10 USD or more in interest per year on their interest-bearing accounts despite the account status. Each year in January, forms will be generated based on the customer’s billing cycle day + 2 calendar days. All forms will be available by 1/31 and will include the total interest earned in the previous year, 1/1 – 12/31.

Sample Screen Mock-up

In the sample screen mock-up, INT-1099 forms are displayed for each year the customer accrued $10 USD or more in interest on their interest-bearing account. If at least $10 USD in interest was not accrued during a particular year, a form for that year will not be displayed. The customer can click the link under each year to access the INT-form for that year.

Sample INT-1099 Form

Retrieve List of INT-1099 Forms

This endpoints is used to retrieve a list of INT-1099 forms per calendar year This endpoint allows the retrieval of a list of INT-1099 forms for interest-bearing accounts that earn $10 USD or more in interest per calendar year. If $10 USD or more in interest was not earned during a particular year, a form for that year will not be available.

Note: Contact your Green Dot liaison for assistance with configuration.

API Call Structure Parameters

Sample Response

{
   "documentStatements":[
      {
         "accountIdentifier":"dd0419da-caec-4c6b-8f44-f3dbbdce98e2",
         "year":2019,
         "title":"INT1099Form_2019"
      }
   ],
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Response Codes

Retrieve INT-1099 Form

This endpoint allows the retrieval of an INT-1099 form for a specific year. INT-1099 forms are only available for interest-bearing accounts that earn $10 USD or more in interest per year.

Note: Contact your Green Dot liaison for assistance with configuration.

API Call Structure

GET /programs/{programCode}/accounts/{accountIdentifier}/taxdocuments/{year}

API Call Structure Parameters

Sample Response

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

Response Codes