Overview

The BillPay API:

• Sends bill payments to recipients
• Schedules future payments
• Sets up payees to receive bill payments from customers

Customers can only schedule future bill payments with the payee. The payee can be either a person or a merchant. The following endpoints support the billpay API.

Note: Maintenance to the BillPay API will be done on a monthly and quarterly basis. During these maintenance windows, the API will be unavailable in production. Partners should display a maintenance message asking the customer to retry after the window expires. A 500 response code will be returned if any requests are submitted to the API during the maintenance windows. Contact your Green Dot liaison with any questions and for a copy of the maintenance schedule.

BillPay API Endpoints

Search Payee

This endpoint allows you to search for a payee in the payee directory, using the payee’s name. To search the payee directory, you must enter a minimum of 3 characters and a maximum of 32 characters from the payee’s name. Once the search is completed, a list of payee names that match the searched payee name will be returned.

API Call Structure

POST /programs/{programCode}/accounts/{accountIdentifier}/billpayPayees/search

Things to Remember

• This endpoint applies to merchant payees only. To add a payee, you must first use the search payee API to locate the payee and their merchantId in the directory.
• The payee name search is a full text search, so the payee’s full name must be provided.
• This endpoint is not designed for rapid asynchronous calls, because it pulls not only the payee’s names, but also the payee’s complete profile information. Requests may be denied if too many are called in a short period of time.
• Therefore, a two second wait is required between each search.
• Also, Partners should submit payee search requests after the customer stops typing or after the response to the initial payee search request is received.

Sample Response Body

{
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"string",
         "url":"string"
      }
   ],
   "payees":[
      {
         "name":"Green Dot Prepaid Card",
         "merchantZipRequired":"true",
         "merchantId":"12345",
         "address1":"101 MAIN ST.",
         "address2":"",
         "city":"Pasadena",
         "state":"CA",
         "zip":"91107",
         "country":"USA",
         "phoneNumber":"8001234455"
      }
   ]
}

Create New Payee

This endpoint is used to create a new payee for a customer’s account. A payee can be a merchant or a person. A Person payee is a custom individual not listed in Green Dot’s vendor’s payee directory, so the full address information would need to be provided in order to send the bill payment.

API Call Structure

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

Sample Request Body - Person Payee Type

{
   "payeeType":"person",
   "name":"John Doe",
   "nickName":"john",
   "address1":"101 MAIN ST.",
   "address2":"#202",
   "city":"Pasadena",
   "state":"CA",
   "zip":"91107",
   "country":"USA",
   "accountNumber":"12345678",
   "phoneNumber":"626-222-4455",
   "email":"[email protected]",
   "merchantId":"12345"
}

Sample Request Body - Merchant Payee Type

{
   "payeeType":"merchant",
   "name":"Green Dot Prepaid Card",
   "nickName":"GD card",
   "address1":"1234 Acme Blvd”,
   "address2": "202",
   "city"": "Pasadena",
   "state": "CA", 
   "zip": "91107", 
   "country": "USA",
   "accountNumber": "1234567890", 
   "phoneNumber": "800-456-7890", 
   "email": "[email protected]", 
   "merchantId": "12345", 

Sample Request Body

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

Update Payee

This endpoint updates an existing payee’s information using the payeeIdentifier.

API Call Structure

PUT /programs/{programCode}/accounts/{accountIdentifier}/billpayPayees/{payeeIdentifier}

Sample Request Body - Person Payee Type

{
   "payeeType":"payee",
   "name":"John Doe",
   "nickName":"john",
   "address1":"101 MAIN ST.",
   "address2":"#202",
   "city":"Pasadena",
   "state":"CA",
   "zip":"91107",
   "country":"USA",
   "accountNumber":"12345678",
   "phoneNumber":"800-123-4455",
   "email":"[email protected]"
}

Sample Request Body - Merchant Payee Type

{
   "payeeType":"merchant",
   "name":"Green Dot Prepaid Card",
   "nickName":"GD card",
   "address1":"1234 Acme Blvd”,
   "address2": "#202",
   "city": "Pasadena",
   "state": "CA"", 
   "zip": "91107", 
   "country": "USA",
   "accountNumber": "1234567890", 
   "phoneNumber": "800-456-7890", 
   "email": "[email protected]", 
}

Remove Payee

This endpoint deletes an existing payee from a user’s account using the payeeIdentifier. After the payee is removed, all associated scheduled bill payments are canceled.

API Call Structure

DELETE /programs/{programCode}/accounts/{accountIdentifier}/billpayPayees/{payeeIdentifier}

Sample Response Body

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

Response Parameters

Retrieve Payee List

This endpoint retrieves a list of all active payees according to their accountIdentifier.

API Call Structure

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

Response Message

If the GET request is successful, the following response message will be returned along with a 200 HTTP status code.

OK

If there are no payees associated with an account, due to one of the following reasons:

• User (customer) has not enrolled in GSS BillPay or
• User (customer) has enrolled, but has not made any payments

Then a successful response will be returned along with an empty payee list.

The following response message will also be returned along with a 200 HTTP status code

Empty Payee List

Note: To continue adding a payee, call addPayee or searchPayee and schedule a bill payment.

Sample Response Body

{
   "responseDetails":{
      "code":0,
      "subCode":0,
      "description":"string",
      "url":"string"
   }
],
"payees":[
   {
      "payeeIdentifier":"e0deb38f-a7e1-4e5c-a2d3-56119b317dd7",
      "payeeStatus":"active",
      "payeeType":"person",
      "name":"John Doe",
      "nickName":"john",
      "address1":"101 MAIN ST.",
      "address2":"#202",
      "city":"Pasadena",
      "state":"CA",
      "zip":"91107",
      "country":"USA",
      "accountNumber":"12345678",
      "phoneNumber":"8001234455",
      "email":"[email protected]"
   }
]
}

Response Parameters

Retrieve Payee by PayeeID

This endpoint retrieves payee information based on the Payee’s payeeID.

API Call Structure

programs/{programCode}/accounts/{accountIdentifier}/billpayPayees/{payeeIdentifier}

How it Works

If a customer has been enrolled in BillPay and has added at least one Payee, call GET programs/{programCode}/accounts/{accountIdentifier}/billpayPayees/{payeeIdentifier} and include the payeeID.

The API will use the payeeID provided to retrieve and return the associated Payee information in the response back to you.

Sample Response Body

{
   "payeeIdentifier":"0b830092-e5d4-45b8-ad26-8a42c94ddd4e",
   "payeeStatus":"active",
   "payeeType":"person",
   "merchant""name":"Green Dot Prepaid Card",
   "nickName":"GD card",
   "address1":"3465 E Foothill Blvd",
   "if payeeType is person""address2":"",
   "city":"Pasadena",
   "state":"CA",
   :2"zipCode":"91107-6072",
   "countryCode":"USA",
   "accountNumber":"1234567890",
   "phoneNumber":"1234567890",
   "email":"[email protected]",
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"string",
         "url":"string"
      }
   ]
}

Schedule Bill Payment

This endpoint schedules a one-time or recurring future bill payment to the selected payee using their payeeIdentifier.

📘

If used for Joint Accounts, a new property userIdentifier is added in the request body and is required only for Joint Accounts. If missing, this property will get an error response.

API Call Structure

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

Recurring Future Bill Payments

• The payee needs to be added using POST /billpayPayees to obtain a payeeIdentifier.
• The frequencyType is required.
• If the recurring billPay schedule has an ending date, then the paymentEndDate should be the same date.
• If the recurring billPay schedule is unknown, the paymentEndDate can be set to null.
• The send date set at the time when the original recurring bill payment was scheduled will be revised automatically when the deliver by date lands on either a weekend or federal holiday to ensure there is enough time (5 business days) for the check to arrive by the original expected date.
• Once the payee is added, the paymentIdentifier will be assigned for the recurring future bill payment.
• The confirmation number will also be returned to the user for schedule confirmation.
• The scheduled bill payment will be debited from the user’s account on the payment date.
• After the first scheduled bill payment is processed, future recurring bill payments will be automatically scheduled for the next payment due date, based on frequencyType.

Note: If there are issues with debiting a payment, it can be retried up to two times the same morning. If the payment still fails, the paymentStatus will show as failed and it will not be tried again.

Terms and Conditions Enforcement

• 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.

Bill Pay Transaction Limits

Programs configured for Bill Pay will have a $7,500 limit per Bill Pay transaction.

Note: Some programs may have custom limits configured for Bill Pay transactions.

Sample Request Body

{
   "accountIdentifier":"ecdaf678-cbc0-41f3-b4ca-51f31024dcd6",
   "payeeIdentifier":"53abc4fc-db6f-4180-a53a-5a81dc62a686",
   "amount":7500,
   "paymentDate":"2020-08-06T19:44:47.255Z",
   "paymentMemo":"testPayment",
   "note":"test"
}

Sample Response Body

{
   "paymentStatus":"scheduled",
   "confirmationNumber":"QLPS0-5N81N",
   "paymentIdentifier":"b213bc74-64c0-41e1-b0cc-744e1778e1c8",
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"success",
         "url":http://tbd

      }
   ]
}

Response Codes

Request Parameters

{
   "payeeIdentifier":"0b830092-e5d4-45b8-ad26-8a42c94ddd4e",
   "amount":100.00,
   "paymentDate":"2019-03-05T19:44:47.255Z",
   "paymentEndDate":"2019-06-05T19:44:47.255Z", //Optional
   "paymentMemo":"memo",
   "note":"note",
   "frequencyType":"oneTime"  //Required
}

Request Parameters

Sample Response Body

{
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"string",
         "url":"string"
      }
   ],
   "paymentStatus":"scheduled",
   "paymentIdentifier":" 7324fb15-4da4-482b-b670-fb45a37c8d5b",
   "confirmationNumber":"P6Q4Q-TVWLJ"
}

Response Parameters

BillPay Joint Account Scenario

If the Schedule Bill Payment API is used for a Joint Account, a new property userIdentifier is added in the request body and is required only for Joint Accounts. If missing, this property will get an error response.

Route Parameters

Headers

Request Sample

{
  "accountIdentifier": "B87DE573-33CC-4081-8A80-F4EC2539D715",
  "payeeIdentifier": "4b156ff7-7b1c-457c-adb4-887cfa4bb121",
  "userIdentifier": "8FC507C2-E21E-471A-905F-734AAEECFCAF", // Required for Joint Accounts
  "amount": 1,
  "paymentDate": "2025-01-17",
  "paymentEndDate": "",
  "paymentMemo": "testPayment",
  "note": "test"
}

Webhook

BillPay Transfer Joint Account Webhook

Delete Scheduled Bill Payment

This endpoint is used to delete or cancel a scheduled bill payment using the paymentIdentifier. Both one-time and recurring scheduled bill payments can be deleted.

API Call Structure

DELETE programs/{programCode}/accounts/{accountIdentifier}/billpayPayments/{paymentIdentifier}

Sample Response Body

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

Response Parameters

• responseDetails, Code, subCode, subCode description, url - Refer to Response Details.
• paymentStatus - Status of the scheduled payment. Options include:
• scheduled – When bill payment is scheduled for the future.
• canceled – Customer cancelled the bill payment before the scheduled date.
• failed – Bill payment failed to process – example: customer does not have a sufficient balance to cover the payment, account rating, etc. If a bill payment is not made by the paymentDate, the paymentStatus will show as failed.
• processed – When bill payment is debited successfully on scheduled date and the check will go out to payee.
• inprocess – On the day when bill payment is in process of debit and issuing check.
• unapproved – Payment is not approved by the business.
• Note: This is a Fiserv status and does not apply to Green Dot, since we use the good fund payment model with Fiserv.

Retrieve List of Scheduled Payments

This endpoint is used to retrieve a list of all bill payments associated with an account, within a specified start and end payment date range. The default for the startPaymentDate is a year prior to the date of the request, and the default for the endPaymentDate is the date of the request.

The statusFilter supports the following bill payment types:

• All -- Returns all bill payments in the search results, including scheduled, failed and processed.
• Scheduled -- Only includes scheduled bill payments in the search results. Note: Future bill payments are listed in the “scheduled” bill pay type search results, but the paymentDate is in the future (after the day of the request).

API Call Structure

GET programs/{programCode}/accounts/{accountIdentifier}/billpayPayments?startingPaymentDate=2019-03- 15&endingPaymentDate=2019-04-03&statusFilter=all

Sample Request Body

{
   "startingPaymentDate":"2019-03-15T19:44:47.255Z",
   "endingPaymentDate":"2019-04-03T19:44:47.255Z",
   "statusFilter":"all"
}

Request Parameters

Response Message

If the GET request is successful, the following response message will be returned along with a 200 HTTP status code.

OK

If there are no bill payments associated with an account, it is due to one of the following reasons:

• User (customer) has not enrolled in GSS BillPay or
• User (customer) has enrolled, but has not made any payments

Then a successful response will be returned along with an empty payment list. The following response message will also be returned along with a 200 HTTP status code.

Empty Payment List

Note: To continue adding a payee, call addPayee or searchPayee and schedule a bill payment.

Sample Response Body

{
   "payments":[
      {
         "payeeIdentifier":"0b830092-e5d4-45b8-ad26-8a42c94ddd4e",
         "payeeName":"John Doe",
         "paymentIdentifier":"88830092-e5d4-45b8-ad26-8a42c94ddd4e",
         "paymentStatus":"scheduled”, //Enums: scheduled,processed,inprocess,unapproved, canceled,failed
         "amount": 100.00,
         "paymentDate": "2019-03-05T19:44:47.255Z",
         "confirmationNumber": "A3UJ8F13",
         "paymentEndDate": "2019-06-05T19:44:47.255Z", //optional
         "frequencyType": "oneTime" //Enums: oneTime, weekly, every2Weeks,every4Weeks,twiceAMonth, monthly,
		             every2Months, every3Months, every4Months, every6Months, annually
      } ],
  "responseDetails": [
      {
         "code": 0,
         "subCode": 0,
         "description": "string",
         "url": "string",
     } ]
}

Retrieve Bill Payment Details

This endpoint is used to retrieve details about a scheduled bill payment using the paymentIdentifier.

API Call Structure

GET programs/{programCode}/accounts/{accountIdentifier}/billpayPayments/{paymentIdentifier}

Sample Response Body

{
   "payments":{
      "payeeIdentifier":"0b830092-e5d4-45b8-ad26-8a42c94ddd4e",
      "payeeName":"Green Dot Prepaid Card",
      "paymentStatus":"scheduled",//scheduled,processed,inprocess,unapproved,canceled,
      "failedamount":100.00,
      "paymentDate":"2020-07-07T19:44:47.255Z",
      "deliveryDate":"2020-06-02T19:44:47.255Z",
      "paymentMemo":"2 wks recurring payment",
      "note":"2 wks recurring payment",
      "confirmationNumber":"QBWCH-73FC0",
      "paymentStartDate":"“2020-07-14T19":"44":47.255Z”,
      "paymentEndDate":"2020-06-05T19:44:47.255Z",
      "frequencyType":"every2Weeks",//weekly,every2Weeks,every4Weeks,
      //twiceAMonth,monthly,every2Months,every3Months,every4Months,every6Months,annually
   },
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"success",
         "url":"http://tbd"
      }
   ]
}

Response Parameters

Update Scheduled Bill Payment

This endpoint is used to update the scheduled bill payment using the paymentIdentifier.

API Call Structure

PUT programs/{programCode}/accounts/{accountIdentifier}/billpayPayments/{paymentIdentifier}

Things to Remember

• A one-time billPay schedule cannot be changed to a recurring billPay schedule by changing the frequencyType, because one time and recurring billpay are under different model schema.
• To change billPay schedules, the customer must delete the one-time billPay schedule and create a new recurring billPay schedule.
• The frequencyType for recurring billPay schedules cannot be changed to oneTime or the frequencyType that was previously set for the billPay schedule.
• oneTime cannot be updated to another frequencyType. Recurring frequencyType can be updated to another recurring frequencyType (i.e. weekly or every2weeks, etc.), except oneTime.

Sample Request Body

{
   "amount":100.00,
   "paymentDate":"2019-03-05T19:44:47.255Z",
   "paymentEndDate":"2019-06-05T19:44:47.255Z",
   "frequencyType":"oneTime",//weekly,every2Weeks,every4Weeks,twiceAMonth,
   //monthly,every2Months,every3Months,every4Months,every6Months,annually - Defaults to oneTime,
   //if not provided.
   "paymentMemo":"memo",
   "note":"note"
}

Sample Response Body

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

Appendices

Bill Payment Codes