ACH API Endpoints

Create New ACH Transfer

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.

📘

This API is affected by Joint Accounts as applicable. For Joint Account scenarios, there is an added request validation. When transfer type is achPull / achOut for joint accounts, userIdentifier field is required, if missing this property will get error response.

API Call Structure

POST /programs/{programCode}/transfers/ach

ACH Limits

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.

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 <property name here>.
• If the recurringType is not provided the system will treat it as a one-time payment.

ACH Joint Account Scenario

For ACH Joint Account scenarios, there is an added request validation. When transfer type is achPull / achOut for joint accounts, the userIdentifier field is required,. If missing, this property will get error response.

Route Parameters

Headers

Request Sample

{
  "transferIdentifier": "43445b58-87d5-4932-a49e-9910ab0f51b0",
  "userIdentifier": "6F40110D-99B3-4091-8F7F-05AEBBC229D8", // Optional for Individual Accounts and REQUIRED for Joint Accounts
  "transferType": "achOut",
  "currency": "USD",
  "transferRoute": {
    "transactionAmount": 5.1,
    "sourceTransferEndpoint": {
      "transferEndpointType": "account",
      "accountIdentifier": "fd7767c1-76e3-445a-a6a5-4e9492777e69"
    },
    "targetTransferEndpoint": {
      "encryptedBankAccount": {
        "version": "EC_v1",
        "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcD",
        "publicKeyHash": "kMhnzB6afrTdRvVFjhOQ5kjUTrPKvkygSCZQXQzNHYo=",
        "data": ""
      }
    },
    "recurringType": "",
    "bankAccountVerificationMethod": "",
    "businessThirdPartyACH": true
  },
  "fraudData": {}
}

Webhook

ACH Transfer Joint Account Webhook

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.

📘

Partners can be configured to receive NOC Alert webhook notifications when a NOC is received for their program.

See ACH NOC Alert Webhook 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.

Get ACH Delivery Date

Retrieves the expected funding date and time (achDeliveryDate) for ACH Pull transfers. Requires transfer type, optional schedule date, and delivery type. Returns the expected funding date for the transfer.

API Call Structure

GET /programs/{programCode}/DeliveryDate

Get ACH Transfers

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

Appendices

Direct Deposit Rules

📘

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

ACH Categories

ACH Return Codes