ACH API Endpoints

Transfer Funds To/From External Account

This endpoint only allows the creation of an ACH Out or ACH Pull transfer, to move funds to and from an external bank account. Daily limits can be configured for ACH Out transfers. However, daily limits are not mandatory for ACH Out. Note: For achOut and achPull transfers, Green Dot is the Originating Depository Financial Institution (ODFI).

When a valid ACH transfer is requested, an ACH transfer webhook will always be published unless there is a system failure. Refer to ACH Return Codes for details. Transaction Webhooks contain information on when the achOut or achPull is posted to the account. However, a Transaction webhook may not always be published. Refer to Event Type: Transactions for details.

API Call Structure

POST /programs/{programCode}/transfers/ach

Request Body

{
   "transferIdentifier":"string",
   "transferType":"string",
   "currency":"string",
   "transferRoute":{
      "transactionAmount":0,
      "deliveryType":"string",
      "sourceTransferEndpoint":{
         "transferEndpointType":"string",
         "accountIdentifier":"string"
      },
      "targetTransferEndpoint":{
         "encryptedBankAccount":{
            "version":"string",
            "ephemeralPublicKey":"string",
            "publicKeyHash":"string",
            "data":"string"
         }
      },
      "recurringType":"string",
      "------ Options":"S” or “R"
   },
   "fraudData":{      
   }
}

Request Parameters

Sample Unencrypted Bank Account Data Parameters

Note: Transfers ACH-Out and ACH-Pull are required to include the following:

Note: When executing a POST /programs/{programCode}/transfers/ach request where the transferType is “achOut”, the following limits will be enforced for ACH Out transfers. Consult with your onboarding liaison to confirm your limits.

When one of the limits above is exceeded, the following code/sub-code will be returned.

Note: If the customer’s balance is below the minimum threshold then they will be allowed to transfer out the remaining balance.

Response Message

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

Created

Sample Response Body

{
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"operation is successful",
         "url":"http://tbd"
      }
   ],
   "transfer":{
      "transferIdentifier":" 9f78abe3-f19a-4b2d-b653-f47450d66abf",
      "transferStatus":"completed"
   },
   "accounts":[
      {
         "accountIdentifier":"0b830092-e5d4-45b8-ad26-8a42c94ddd4c",
         "purses":[
            {
               "purseIdentifier":"562a27ec-6cae-4459-a522-be94b4570f78",
               "purseType":"primary",
               "availableBalance":12.0,
               "ledgerBalance":12.0,
               "availableBalanceAsOfDateTime":"2018-09-11T19:22:33.469Z",
               "ledgerBalanceAsOfDateTime":"2018-09-11T19:22:33.469Z"
            }
         ]
      }
   ],
   "fraudData":{     
   }
}

Response Parameters

ACH Availability

Note: The above times are in PT.

Expected Delivery Date/Time (EDD)

Note: Delivery Type does not apply to ACH Out. It only applies to ACH pull when the credit will be funded to BaaS accounts.

NACHA guidelines

• Per NACHA guidelines, Green Dot is required to do the following:
  • Include an RDFI indicator within the NACHA file, for partners who submit recurring ACH transfers.
  • Provide external banks with the successful bank account verification method and date when debit authorizations are requested.
  • Provide supporting evidence that the customer (user) authorized the ACH transfer.
• To meet these guidelines, Partners will now need to provide an optional recurringType for all ACH Transfers. Options for the recurringType are:
  • “R” for Recurring Payment
  • “S” for Single Payment (one-time payment).
• If the recurringType is provided and does not contain one of these options, the following error will be received:
  • HTTP Status: 400
  • Code: 600
  • Description: Invalid value provided for .
• If the recurringType is not provided the system will treat it as a one-time payment.

Sample Request Body

{
   "transferIdentifier":"string",
   "transferType":"achOut",
   "currency":"USD",
   "transferRoute":{
      "transactionAmount":5,
      "sourceTransferEndpoint":{
         "transferEndpointType":"account",
         "accountIdentifier":"0b830092-e5d4-45b8-ad26-8a42c94ddd4c"
      },
      "targetTransferEndpoint":{
         "encryptedBankAccount":{
            "version":"string",
            "ephemeralPublicKey":"string",
            "publicKeyHash":"string",
            "data":"string"
         }
      },
      "recurringType":""
   },
   "fraudData":{      
   }
}

ACH Notification of Change (NOC)

Green Dot needs to be able to process ACH Notification of Change (NOC) requests received from the Federal Reserve (Fed). An ACH NOC is created by a Receiving Depository Financial Institution (RDFI) to notify the Originating Depository Financial Institution (ODFI) that the account information included in the ACH is incorrect and needs to be changed.

When ACH NOC requests are received from the Fed, subsequent ACH transfer requests using the incorrect account number or routing number included in the ACH requests will be declined.

Note: Partners can be configured to receive NOC Alert webhook notifications when a NOC is received for their program. See Event Type: NOC Alert for details.

Sample achPull Request Body (Account with a NOC Return Code)

{
   "transferIdentifier":"8aac3be4-b190-4d97-9b31-d5211cdb58d7",
   "transferType":"achPull",
   "currency":"USD",
   "transferRoute":{
      "transactionAmount":10,
      "sourceTransferEndpoint":{
         "transferEndpointType":"account",
         "accountIdentifier":"407da696-4141-410d-9674-d466626f788a"
      },
      "targetTransferEndpoint":{
         "encryptedBankAccount":{
            "version":"EC_v1",
            "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAESot1Hj2OHD4AW9jZ39EW95SodW0Tgxg25c2omHC4tPzf+KWKNN81Gzw8K1ObbXbhaPDQqF3/okCKsBeKsdIHEg==",
            "publicKeyHash":"1YPiscLswrzhpxDdW2LvYTwKmzImy922OQ5HMcmoL9E=",
            "data":"IyHe0snwpL7kCx73YKND/ITLS4o2fCsA7xjGpWRCkEl/3XDgva4nzA6je17f73zUYrX3zfnJkKdnyFUVfZCVWPv5Sy9fodKwRcNhBouskBpxHSAwt8stZz6LvXGGOxLqzDuEG3b8Oz6ouNJA60qA5XqWDu/Wbdf1sElsWwk/S6vfxfuECbJQZP6U6FqD8SUS5QLJ87h3cOJ/RGlJrzk0vyqSHtT0enrDHzbvWLjOSIN3IQ=="
         }
      },
      "recurringType":""
   },
   "fraudData":{      
   }
}

Sample achOut Request Body (Account with a NOC Return Code)

{
   "transferIdentifier":"9d61b996-fb2c-4c51-8cb8-bfb34739f15a",
   "transferType":"achOut",
   "currency":"USD",
   "transferRoute":{
      "transactionAmount":10,
      "sourceTransferEndpoint":{
         "transferEndpointType":"account",
         "accountIdentifier":"0b7725b9-5dfc-4972-a465-ab8f889d16a0"
      },
      "targetTransferEndpoint":{
         "encryptedBankAccount":{
            "version":"EC_v1",
            "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEFNGxyj9sLVL/JoGXyeZlseahA3nFWnFgNT/Er13EpHRVXgIg+H+B8F0AP13oyz5aAobyiZ1bHP6vq5qO0hTzUA==",
            "publicKeyHash":"1YPiscLswrzhpxDdW2LvYTwKmzImy922OQ5HMcmoL9E=",           
            "data":"hqw0qkuVY8O7f6sCbxU2MoyShvRAXGqKlbT57FoZ0Y0TZkay0BTsvjrmkUb3w3VCa573Ih//2f//mfBOhH6I/AL7/Vj6ZXnQ/IspM8hrGXfHCX2TsGyTHJ1ElwcJ0WTT1aDGTFWNon+b+LJz6eQUdt185P+7SopAQKhSrdXxNuE3w9ctZyu2FKZK7SL970wHpchlo3RcQ0QK+jtl2vZUmWp/H2gt6Ex6V21p0MQ8zcExDg=="
         }
      },
      "recurringType":""
   },
   "fraudData":{
      
   }
}

Sample Response

{
   "transfer":{
      
   },
   "responseDetails":[
      {
         "code":3,
         "subCode":216,
         "description":"The transfer was initiated by an account that has previously received a NOC return. Corrected account information must be submitted.",
         "url":"http://tbd"
      }
   ]
}

Response Codes

🚧

Transfers for “Restricted” and “Closed” accounts are never allowed for inbound transfers. Outbound transfers on “Restricted” accounts, are not allowed unless there is a spend down or customer Initiated spend down involved. Outbound transfers for “Closed” Accounts may or may not be allowed depending on product or program specific rules.

Obtain ACH Delivery Date for ACH Pull Transfers

This endpoint allows retrieval of the achDeliveryDate (expected funding date and time) for ACH Pull transfers only.

API Call Structure

Endpoint: GET /deliveryDate?achTransferType={TransferType}&scheduleDate={ScheduleDate}&achDeliveryType={AchDeliveryType} (ACH Pull Only)

GET …/deliveryDate?achTransferType={TransferType}&scheduleDate={ScheduleDate}&achDeliveryType={Ach DeliveryType}

How it Works

• Call GET: …/deliveryDate?achTransferType={TransferType}&scheduleDate={ScheduleDate}&achDeliveryTyp e={AchDeliveryType}
• Include the:
  • Request date
  • Request time
  • Program code
  • Delivery Type (optional)
  • Schedule Date (optional)
• The achDeliveryDate (expected funding date and time) of the ACH Pull transfer will be returned.

Sample Response Body

{
   "achDeliveryDate":"2020-06-24T07:00:00Z",
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Response Codes

List Transfers for an Account

This endpoint allows the retrieval of a list of transfers for an account.

Note: The maximum number of transfers in a list is 180 per request.

API Call Structure

GET /programs/{programCode}/accounts/(accountIdentifier}/achTransfers

Sample Response Body

{
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"operation is successful",
         "url":" http://tbd"
      }
   ],
   "totalRecordCount":1,
   "transfers":[
      {
         "achTransferType":"achPull",
         "transferIdentifier":"4b830092-e5d4-45b8-ad26-8a42c94aaa2a",
         "accountIdentifier":"9b830092-e5d4-45b8-ad26-8a42c94ccc2c",
         "submissionDateTime":"2019-01-03T21:02:45.260Z",
         "transactionAmount":5,
         "achTransferStatus":"pending",
         "expectedDeliveryDate":"2020-06-24T17:07:00.028Z",
         "bankAccountType":"checking",
         "institutionName":"GDot Bank",
         "last4BankAccountNumber":"*************9999"
      }
   ]

If the GET request includes an invalid scheduleDate, the following response message is returned along with a 400 HTTP status code.

"transfer":{
   
},
"responseDetails":[
   {
      "code":400,
      "subCode":0,
      "description":"Invalid ACH Schedule Date.",
      "url":"http://tbd"
   }
]
}

Response Parameters

Filtering ACH Transfers

ACH transfers can be filtered based on the following ACH Transfer Statuses, so specific ACH transfers can be viewed by the Partner.

Valid ACH Transfer Statuses

If GET /achTransfers is called and the status provided is one or more of the valid ACH Transfer Statuses (listed above), then the response will contain the ACH transfers within the selected (or defaulted) date range that have an ACH Transfer Status that matches one of the statuses that was provided in the call.

Sample Response Body Snippets

Filtered by pending

"transfers": [{

"achTransferType": "achPull",

"transferIdentifier": "4434898b-d201-4634-be23-41e77587aa95",
"accountIdentifier": "78b41a0a-88ca-4386-82dd-33f9f30f818e",
"submissionDateTime": "2020-05-14T22:26:13.773Z",
"transactionAmount": 2.2300,
"achTransferStatus": "pending"
 "expectedDeliveryDate": "2020-06-24T17:07:00.028Z",
 "bankAccountType": "checking",
 "institutionName": "GDot Bank",
 "last4BankAccountNumber": "*************9999"

}],

Filtered by sent

"transfers":[
   {
      "achTransferType":"achPull",
      "transferIdentifier":"2eb154fb-291a-4faa-aaf6-73479b055c0d",
      "accountIdentifier":"d1f2c754-0802-4048-b1a0-8309b3b35202",
      "submissionDateTime":"2020-05-14T03:07:54.077Z",
      "transactionAmount":2.2300,
      "achTransferStatus":"sent""expectedDeliveryDate":"2020-06-24T17:07:00.028Z",
      "bankAccountType":"checking",
      "institutionName":"GDot Bank",
      "last4BankAccountNumber":"*************9999"
   }
],

Filtered by multiple statuses

"transfers":[
   {
      "achTransferType":"achOut",
      "transferIdentifier":"08ce2c74-7cd5-4706-9414-857b60b85e81",
      "accountIdentifier":"38c33ebb-a83c-4cd1-a8a4-4a420e553112",
      "submissionDateTime":"2020-02-25T23:11:06.310Z",
      "transactionAmount":5.0000,
      "achTransferStatus":"failed"
   },
   {
      "achTransferType":"achOut",
      "transferIdentifier":"872fab86-c394-455a-ab80-7284c1b2d827",
      "accountIdentifier":"e802b9be-781c-4112-8c18-3d27e9e1fc95",
      "submissionDateTime":"2020-05-15T18:31:45.527Z",
      "transactionAmount":5.0000,
      "achTransferStatus":"pending"
   }
],

Appendices

Direct Deposit Rules

📘

When both debits and credits are allowed, there will not be a return code.

ACH Categories

ACH Return Codes