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 Request Body

{ 
"name": "Green Dot Prepaid Card"
}

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"
      }
   ]
}

Response Parameters

Field	Description
responseDetails	See Response Details.
code, subCode	See Response Details.
description, url, payees	See Response Details.
name	String value. Example: Green Dot Prepaid Card
merchantZipRequired	Boolean value. Default value is false. If this value is true, the zip is required when calling the addPayee endpoint
merchantId	String value. Identifying number for the merchant. Example: 12345
address1	Optional string value. If the merchant has an address on file, then this field will be available.
address2	Optional string value
city	Optional string value. Example: Pasadena
state	Optional string value. Example: CA
zip	Optional string value. Example: 91107
country	Optional string value. Example: USA
phoneNumber	Optional string value. This will be the merchant payee’s phone number. Example: 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"
}

Request Parameters – Person Payee Type

Field	Description
payeeType	Required string value for the payee type (i.e. person or merchant)
name	Required string value for the name of the payee. Example: John Doe Must be 3- 32 characters
nickName	Optional string value. Example: John
address1	Required for a person payee type. Example: 101 Main St. Note: The full address is required for the person payee type. Must be 1-40 characters.
address2	Optional string value. Example: #202 Must be 0-40 characters.
city	Required and must be 1-32 characters. Example: Pasadena
state	Required and must be 2 letters only. Example: CA
zip	Required and can either be in 5-digit format or in full zip format of “12345- 6789”
country	Required Example: USA
accountNumber	Optional string value for the person payee type that must be 1-32 characters, if provided. Example: 12345678
phoneNumber	Required when merchant information is not provided, except when the payee is from a captured image. If the payee to be added is from a captured image, then the phoneNumber is optional. Must be a valid phone number based on the North American numbering plan (i.e. area code cannot begin with a 0 or 1). Must be 10 digits and may contain a period, dash, or space between the numbers at the appropriate placement. Note: International codes are not supported at this time. Example: 234-555-1212
email	Optional string value for the payee’s email address. Example: [email protected]
merchantId	Optional string value that is returned from the searchPayee endpoint for a merchant. This is required if the payeeType is merchant.

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",

Request Parameters – Merchant Payee Type

Field	Description
payeeType	Required string value for the payee type (i.e. person or merchant).
name	Required and must be 3-32 characters. Example: Green Dot Prepaid Card
nickName	Optional string value. Example: GD Card
address1	Optional and must be 1-40 characters. Example: 1234 Acme Blvd
address2	Optional and must be 0-40 characters. Example: #202
city	Optional and must be 1-32 characters. Example: Pasadena
state	Optional and must be 2 letters only. Example: CA
zip	Can either be in five-digit format or in full zip format of “12345-6789”. It is only required for merchant payee types if the merchantZipRequired flag is true in the searchPayee response. Example: 91107
country	Optional string value. Example: USA
accountNumber	Required. Example: 1234567890
phoneNumber	Optional and must be a valid phone number with 10 digits. May contain a period, dash, or space between the numbers at the appropriate placement. The area code cannot begin with a 0 or 1. Example: 800-456-7890 Note: International codes are not supported at this time.
email	Optional string value for the payee’s email address. Example: [email protected]
merchantId	Required string value that is returned from the searchPayee endpoint for a merchant. Example: 12345

Sample Request Body

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

Response Parameters

Field	Description
responseDetails,code	See Response Details.
subCode, description	See Response Details.
url	See Response Details.
payeeIdentifier payeeStatus	String unique identifier that is assigned to each new payee. String value for the payee’s status (i.e. active or inactive)

Update Existing Payee Information

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]"
}

Request Parameters – Person Payee Type

Field	Description
payeeType	Required field. May be a person or a merchant
name	Required string value. Example: John Doe
nickName	Optional string value. Example: John
address1	Optional field containing the payee’s address. The full address is required if the payeeType is person. Example: 101 Main St
address2	Optional field. Example: #202
city	Optional field. Example: Pasadena
state	Optional field. Example: CA
zip	Optional field. Example: 91107
country	Optional field. Example: USA
accountNumber	Optional field. Example: 12345678
phoneNumber	Optional field. May contain a period, dash, or space between the numbers at the appropriate placement. The area code cannot begin with a 0 or 1. Example: 800- 123-4455 Note: International codes are not supported at this time
email	Optional field. Example: [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]", 
}

Request Parameters – Merchant Payee Type

Field	Description
payeeType	Required field. Payee type can be a person or a merchant.
name	Required string value. Example: Green Dot Prepaid Card
nickName	Optional field. Example: GD Card
address1	Optional field when payee type is merchant. Example: 1234 Acme Blvd
address2	Optional field. Example: #202
city	Optional field when payee type is merchant. Example: Pasadena
state	Optional field when payee type is merchant. Example: CA
zip	Conditional field. If the payee type is merchant and the required merchant zip is true in the search payee response, then this field is required.
country	Optional field when payee type is a merchant. Example: USA
accountNumber	Required field if payeeType is a merchant. Example: 1234567890
phoneNumber	Optional field when payeeType is a merchant. May contain a period, dash, or space between the numbers at the appropriate placement. The area code cannot begin with a 0 or 1. Example: 800-456-7890 Note: International codes are not supported at this time.
email	Optional field. Example: [email protected]

Sample Request Body

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

Response Parameters

Field	Description
responseDetails,description,url,code,subCode	See Response Details

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

Field	Description
responseDetails,code,subCode,description,url	See Response Details
payeeStatus	String value for the status of the payee. Status options are active or inactive.

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

Field	Description
responseDetails,code,subCode,description,url	See Response Details
payees	Value that contains the payees’ information.
payeeIdentifier	Required field. Unique identifier for a payee. Each new payee is assigned one
payeeStatus	Required status of a payee. Status options are active or inactive.
payeeType	Required field that can be either a person or merchant
name	Required field containing the name of the payee. Example: John Doe
nickName	Optional field. Example: John
address1	Optional field if payee type is a merchant. Note: The full address is required if payeeType is a person. Example: 101 Main St.
address2	Optional field. Example: #202
city	Optional unless payeeType is a person.
state	Optional unless payeeType is a person. Must be 2 characters
zip	Optional unless payeeType is a person. Note: If zip4 is available, it should be 5 digits or in the full zip format of “12345-6789”.
country	Optional unless payeeType is a person.
accountNumber	Optional if payeeType is a person. Required if a merchant. Example: 12345678
phoneNumber	Required if payeeType is a person. Example: 8001234455. Note: International codes are not supported at this time.
email	Optional field. Example: [email protected]

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

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

Code	subCode	Description
4050	1352	Payment denied—per use limit exceeded

Request Parameters

Parameter	Description
Bill payment	There is no limit to the number of bill payments that can be scheduled daily, weekly, monthly, or in total. A payment can be scheduled up to a year in the future.
amount	Must be in decimal format, up to 2 decimal places (i.e. 1234.56), and it must be more than 0. There is no limit to the amount a bill can be.
paymentDate	The paymentDate is provided by the client and it is the date that the account will be debited. It should be in the format YYYY-MM-DD. If an invalid paymentDate is entered, the client will receive a 04036 error code. See Bill Payment Codes for details. Currently, there is not a recommendation function if an invalid date is entered. Note: The paymentDate cannot be in the past (before the request) or on the day of the request. It must also, be a business day (Monday – Friday) and not a banking holiday.
paymentEndDate	• This is an optional field. • It is not required if the frequencyType is oneTime. Note: frequencyType can be oneTime or recurring. • The paymentEndDate can be null if the recurring billPay schedule has no ending date. • If the recurring billPay schedule has an ending date, then the paymentEndDate should be the same date.

{
   "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

Field	Description
payeeIdentifier	Unique identifier for a payee. Each new payee is assigned one.
amount	Amount of scheduled bill payment. Example: 1000
paymentDate	Date (UTC) of scheduled bill payment. Example: 2019-03-05T19:44:47.255Z
paymentEndDate	Optional and is the date (UTC) the recurring scheduled billpay ends
paymentMemo	Memo on scheduled payment check. Example: rent for Mar 2019
note	Note entered by the customer for the scheduled payment. Example: rent for Mar 2019
frequencyType	Required field that indicates if the billPay is one time or recurring. Enums: One-Time BillPay: •oneTime Recuring BillPay: •weekly •every2Weeks •every4Weeks •twiceAMonth •monthly •every2Months •every3Months •every4Months •every6Months •annually - Defaults to oneTime if not provided

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

Field	Description
responseDetails,Code,subCode,subCode description,url	See Response Details
paymentStatus	Status of the scheduled payment. Status options are: • scheduled – when billpayment is scheduled for the future • canceled – Customer cancelled the billpayment before schedule date • failed – Bill payment failed to process – example: customer does not have a enough 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 billpayment is debited successfully on scheduled date and check will go out to payee • inprocess – on the day when billpayment 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.
paymentIdentifier	Unique identifier for the scheduled payment. Each new scheduled bill payment is assigned a paymentIdentifier.
confirmationNumber	Returned to customer for confirmation of scheduled payment. Example: P6Q4QTVWLJ

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

Field	Description
startingPaymentDate	Optional. If this date is not provided in the request, it will default to a year prior to the date of the request. Note: This allows historical bill payments to be retrieved for up to a year.
endingPaymentDate	Optional. If not provided, it will default to the date of the request. Note: This allows historical bill payments to be retrieved up to the day of the request. The endingPaymentDate should be greater than the startingPaymentDate
statusFilter	Required. Options are all or scheduled

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

Field	Description
responseDetails, code, subCode, description, url payment	See Response Details The billpay properties are wrapped inside of this payment object.
payeeIdentifier,	Unique identifier for a payee. Each new payee is assigned one.
paymentStatus	Status of a scheduled bill payment. Status options are: • scheduled: Bill payment will be paid on the scheduled date, based on available funds. • canceled: Bill payment has been cancelled by the user or by the agent, through the billPay portal. • failed: 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. • processed: Payment was processed successfully. The check will be sent to the payee by the delivery date. • inProcess: Bill payment is processing. Status is changed to processed, once the check is sent out. • 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
amount	The amount of a scheduled bill payment. It is in decimal format and must be larger than 0. Example: 100.00
paymentDate	The scheduled payment date.
deliveryDate	The deliveryDate is provided by Fiserv and it is the date the bill payment is expected to be delivered by. Fiserv calculates this date based on the paymentDate and it is usually, 5 business days after the paymentDate
paymentMemo	Memo on the scheduled payment check
note	Note added by the customer to the scheduled payment.
confirmationNumber	Confirmation number of the scheduled bill payment.
paymentEndDate	Optional field containing the date the recurring scheduled billpay ends. NOTE: This field does not apply to one-time billPay
frequencyType	Required field that indicates if the billPay is one time or recurring. Enums: • One-time billPay: o oneTime • Recuring billPay: o weekly o every2Weeks o every4Weeks o twiceAMonth o monthly o every2Months o every3Months o every4Months o every6Months o annually - Defaults to oneTime if not provided

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

HTTP Status Code	Description	Client Treatment
400	BillPay internal Header or requestId Missing	Contact Partner Support if the issue persists.
500	cannot get subscriber management header	Contact Partner Support if the issue persists.
400	customer is not enrolled to BillPay yet	Contact Partner Support if the issue persists.
500	cannot get payment management header	Contact Partner Support if the issue persists.
404	Cannot locate Payee with the payeeIdentifier	Correct the invalid payeeIdentifier
400	payeeToken is missing	Contact Partner Support if the issue persists.
400	Invalid startDate or endDate in GetPaymentList	Correct startDate/endDate.
404	BillPaySchedule does not exist for given paymentIdentifier	Correct the invalid paymentIdentifier.
404	Cannot locate payeeIdentifier with the payeeToken	Contact Partner Support if the issue persists.
400	Invalid input value on URI	Correct entity value in URI.
500	BillPay General System Error	Contact Partner Support if the issue persists.
500	Call to vendor timed out	Contact Partner Support if the issue persists.
500	Vendor service is unavailable	Contact Partner Support if the issue persists.
400	Missing customer information in the request	Contact Partner Support if the issue persists.
500	Missing customer bank account information in the request	Contact Partner Support if the issue persists.
400	The bankAccountType provided was invalid	Contact Partner Support if the issue persists.
400	enrollSubscriber returned null response	Contact Partner Support if the issue persists.
400	enrollSubscriber returned a failed response	Contact Partner Support if the issue persists.
400	The bankAccountType is missing	Contact Partner Support if the issue persists.
400	searchPayee failed	Contact Partner Support if the issue persists.
400	addPayee failed	Contact Partner Support if the issue persists.
400	Active payee already exists	Contact Partner Support if the issue persists.
400	addPayee account schema failed	Contact Partner Support if the issue persists.
400	merchantId for Merchant payee cannot be empty	Supply merchantId.
400	Address or phone number for Person payee cannot be empty in AddPayee	Correct address/phone number.
400	UpdatePayee failed	Contact Partner Support if the issue persists.
400	UpdatePayee account schema failed	Contact Partner Support if the issue persists.
400	Address or phone number for Person payee cannot be empty in UpdatePayee	Correct address/phone number.
400	DeletePayee failed	Contact Partner Support if the issue persists.
400	AddPayments returned a failed or empty response	Contact Partner Support if the issue persists.
400	PaymentModify returned a failed or empty response	Contact Partner Support if the issue persists.
400	Delete payment request failed	Contact Partner Support if the issue persists.
404	Payment could not be found for the given AccountIdentifier	Correct paymentIdentifier.
400	GetPaymentDetails returned a failed or empty response	Contact Partner Support if the issue persists.
400	GetAllPayments failed	Contact Partner Support if the issue persists.
400	Invalid parameter	Required parameter is not provided, or input value is invalid, or the format/range is incorrect.
400	Missing required field	Provide required field as indicated.
400	Field syntax invalid	Correct the field containing the invalid syntax.
500	User ID does not match sponsor ID	Contact Partner Support if the issue persists.
400	Payee already exists	Payee already exists.
400	Invalid ZIP Code	Zip is 5 digits or 10 digits in format -11111-2222.
500	Sponsor does not exist	Contact Partner Support if the issue persists.
500	Subscriber does not exist	Contact Partner Support if the issue persists.
400	No data returned due to subscriber status	Contact Partner Support if the issue persists.
500	Not Authorized	Contact Partner Support if the issue persists.
500	General server error	Contact Partner Support if the issue persists.
400	Subscriber account number is invalid	Contact Partner Support if the issue persists.
400	Address line 1 is invalid	Correct address line 1.
400	City name is invalid	Correct the city.
400	State code is invalid	State must be 2 characters long.
404	Payee ID is invalid	PayeeID should exist and be in GUID format.
400	Payee status is inactive and operation cannot continue	This operation cannot be honored.
400	Invalid Customer Account data	Contact Partner Support if the issue persists.
400	No payments scheduledcheck individual PaymentResponses for details	The payment(s) passed input validation. Check the response for details.
400	Payment date is too early	Payment date must be after the current date.
400	Duplicate payment	Cannot schedule a payment with the same payee, amount, and date as another payment.
400	Payment amount is missing or invalid	Correct the payment amount.
400	Payment amount exceeds maximum allowed	Resubmit with a smaller payment amount.
400	Payment date is missing or invalid	Correct the payment date.
400	Invalid e-bill ID received	Contact Partner Support if the issue persists.
400	Payee is inactive	Payee must be active.
404	Payee is not found	Resubmit with a valid payee.
404	Payee ID is missing or invalid	Resubmit with a valid Payee ID.
400	Possible duplicate payment	Cannot schedule a payment with the same payee, amount, and date as another payment.
500	Duplicate bank account found	Contact Partner Support if the issue persists.
500	Bank account missing or invalid	Contact Partner Support if the issue persists.
400	Payment amount is less than the minimum	Amount must be larger than 0.
400	Payment date is too late	Resubmit the payment with an earlier date. Payments cannot be scheduled more than a year in the future.
400	Payment denieddaily limit exceeded	The limit is exceeded.
400	Did not add payment notes	Contact Partner Support if the issue persists.
500	Bank account not confirmed	Contact Partner Support if the issue persists.
400	Payment date is not a processing date	Change the payment date to a business date that is not a non-banking holiday.
400	No payments scheduled due to validation errorscheck individual PaymentResponses for details	Correct one or more errors associated with an individual payment's input.
400	Payment deniedrisk check failed	This operation cannot be honored.
404	payment cannot be found	Correct the paymentIdentifier.
400	Cannot modify or cancel payment	This operation cannot be honored.
404	Payment not found. Check Transaction ID.	Correct the paymentIdentifier.
400	Too many payments requested	Too many payments were requested, and the page size will be limited in the GetPaymentList.
400	Invalid input for add payment	Correct the payment input.