ACH Transactions

The ACH (automated clearing house) transactions endpoints allow creating and managing ACH payments.

These operations support initiating ACH debit and credit transactions, retrieving transaction details, and monitoring transaction status throughout processing. They also provide controls for managing transactions before settlement, such as placing transactions on hold, releasing holds, voiding pending transactions, or issuing refunds as needed.

The following is a typical Flute ACH workflow.

Authorizing the Payment
The customer authorizes the ACH payment. This includes obtaining NACHA-compliant authorization. NACHA (National Automated Clearing House Association) is the organization that governs the ACH payment network in the United States. It sets the rules and standards for ACH payments.

The customer provides the SEC (standard entry class) code for the payment method. This establishes the form of payment. It can be one of the following:

Online form (SEC code WEB)
Signed authorization (SEC code PPD)
Phone authorization (SEC code TEL)
Business payment (SEC code CCD)

And their personal information:

Name
Their bank's routing number
Their bank's account number and account type
Authorization confirmation

Creating the Payment
The method can include either a credit or debit transaction:
POST /pay-api/v1/transactions/ach/payment/credit.
POST /pay-api/v1/transactions/ach/payment

Submitting the Payment
Creating the ACH (automated clearing house) transaction also submits the request for processing.

Flute aggregates transactions and sends them to the ODFI (originating bank) in an ACH (automated clearing house) transaction batch. ACH (automated clearing house) transactions are typically not processed individually but rather in as a batch of transactions. That processing is done by the ACH network and batches may take up to two days to clear. Therefore, there may be a delay in processing ACH (automated clearing house) transaction requests. An individual ACH (automated clearing house) transaction may be requested for same day processing. Settlement in those cases may occur within hours. Check with the originating bank for specific policies and fees.

Statusing the Payment
Individual requests will always have an available status that can be checked. These will be noted with the Flute transaction creator type identifier.

A status check may be submitted at any time. Check the response field status or statusId.
POST {{baseURL}}/pay-api/v1/transactions/{{transactionId}}

Holding or Cancelling the Payment
After the ACH (automated clearing house) transaction request has been successfully submitted, the transaction by the put on hold or cancelled. A transaction on hold means the request will not be processed. That transaction must either be released to continue processing or cancelled.
POST {{baseURL}}/pay-api/v1/transactions/ach/{{transactionId}}/hold
POST {{baseURL}}/pay-api/v1/transactions/ach/{{transactionId}}/unhold

A transaction that is cancelled will be withdrawn from further processing. An ACH (automated clearing house) transaction request cannot be cancelled after it has been submitted to the ACH network. This is indicated by it's pending status.
POST {{baseURL}}/pay-api/v1/transactions/ach/{{transactionId}}/void

Settling the Payment
If the ACH (automated clearing house) transaction request is successful, it returns with a status of settled. The merchant receives funds in their settlement account. The ACH (automated clearing house) transaction is completed.

Unsuccessfully Completing the Payment
Banks can reject the payment with ACH return codes. Check the ACH return code for the specific reason.

Refunding the Payment
Refunds may be issued. The ACH (automated clearing house) transaction request must have successfully been resolved and settled.
POST {{baseURL}}/pay-api/v1/transactions/ach/{{transactionId}}/refund

Operations

Creates an ACH credit payment

Request

POST {{baseURL}}/pay-api/v1/transactions/ach/payment/credit

This endpoint creates a credit ACH (automated clearing house) transaction to transfer funds from the merchant to the customer.

It specifically transfers money from the sender's bank account to the recipient's account. This is used in credit operations, such as payouts or refunds without reference. A refund without reference (also called unreferenced refunds) are refunds issued without linking it back to original receipt.

The following is an example of the minimum call.

The endpoint call:

POST {{baseURL}}/pay-api/v1/transactions/ach/payment/credit

The endpoint request body:

{
  "paymentProcessorId": "4acafddf-68a7-4aeb-9778-87582d121307",
  "paymentMethodId": "55419052-670c-497b-a53d-43d21ef45e14",
  "amount": 123.45,
  "secCode": 3,
  "RequesterIpAddress": "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
}

See Also:
To create an ACH debit transaction, see POST /pay-api/v1/transactions/ach/payment

Security

Bearer

Bodyapplication/json

amountnumber, (double)required

Specifies the payment amount.

Example: 129.99

Example:129.99

paymentProcessorIdstring, (uuid)required

Specifies the ACHQ (ACH check) payment processor identifier.

We recommend using paymentMethodId instead of accountNumber.

Example: f4e41489-aea6-4279-b6f1-e1f9bffd5358

Example:"f4e41489-aea6-4279-b6f1-e1f9bffd5358"

accountNumberstring or null

Specifies the payment target's bank account number.

We recommend using paymentMethodId instead of accountNumber.

Example: 5413591081013511

Example:"5413591081013511"

routingNumberstring or null

Specifies the payment target's bank routing number.

Example: 026009593

Example:"026009593"

secCodeinteger, (int32)required

Specifies the SEC (standard entry class) code for the payment method.

Allowed values:

Type ID	Entry Type	Description
1	Web	Internet-initiated/mobile entries. Default value.
2	PPD	Prearranged payment and deposit entries.
3	CCD	Corporate credit or debit.
4	Telephone	Telephone-initiated entries.

Example: 1

Default:1

Example:1

requesterIPaddressstring, [ 1 .. 45 ] charactersrequired

Specifies the IP address of the end user.

This is an IPv4 or IPv6 address. This may be the customer, operator, or application responsible for submitting the transaction.

Examples:
192.168.1.1
2001:0db8:85a3:0000:0000:8a2e:0370:7334

Example:"192.168.1.1"

paymentMethodIdstring or null, (uuid)required

Identifies the customer payment method identifier.

Example: b6df8625-cd25-4123-b345-638aa7b5d011

Example:"b6df8625-cd25-4123-b345-638aa7b5d011"

customerIdstring or null, (uuid)

Specifies the customer identifier.

Example: 87d8e330-2878-4742-a86f-dbbb3bf522ac

Example:"87d8e330-2878-4742-a86f-dbbb3bf522ac"

isFasterProcessingboolean

Specifies ACH (automated clearing house) transaction has same day processing enabled.

Must be empty or null for card subscriptions.

If true, same day processing is enabled.
If false, same day processing is not enabled.

Example: false

Default:false

Example:false

taxIdstring or null

Specifies the customer's TIN (tax identifier).

Example: 98-7654321

Example:"98-7654321"

accountTypeinteger, (int32)

Identifies the account type.

Possible values:

Type ID	Account Type	Description
1	Checking	Checking
2	Savings	Savings

Example: 1

Example:1

accountHolderTypeinteger, (int32)

Identifies the account holder type.

Possible values:

Type ID	Account Type	Description
1	Business	Business
2	Personal	Personal

Example: 1

Example:1

billingAddressobject

Specifies an object defining the address.

shippingAddressobject

Specifies an object defining the address.

contactInfoobject

This group contains the customer's contact details.

curl -i -X POST \
  https://developer.flute.com/_mock/api-reference/pay-api/v1/transactions/ach/payment/credit \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "paymentProcessorId": "7a913ba9-724b-4020-8ef1-d3375291f59e",
    "paymentMethodId": "d6e6a259-6e7f-4a8b-9c0d-1e2f3a4b5c81",
    "accountNumber": null,
    "routingNumber": null,
    "customerId": null,
    "requesterIPaddress": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
    "amount": 123.45,
    "isFasterProcessing": true,
    "taxId": null,
    "accountHolderType": 1,
    "accountType": 1,
    "billingAddress": {
      "city": "Phoenix",
      "countryId": 1,
      "line1": "7429 Desert Mirage Lane",
      "line2": null,
      "postalCode": "85099",
      "stateName": "Arizona",
      "stateId": 4
    },
    "shippingAddress": {
      "city": "Phoenix",
      "countryId": 1,
      "line1": "7429 Desert Mirage Lane",
      "line2": "Office 7",
      "postalCode": "85099",
      "stateName": "Arizona",
      "stateId": 4
    },
    "contactInfo": {
      "firstName": "John",
      "lastName": "Smith",
      "companyName": "Flute",
      "email": "j.smith29f@example.com",
      "mobilePhoneNumber": null,
      "smsNotification": null
    },
    "secCode": 3
  }'

Responses

Bodyapplication/json

transactionIdstring, (uuid)

Indicates the transaction identifier.

Example: bf5a1dc7-57b7-4fec-ab09-52c47c1acaff

Example:"bf5a1dc7-57b7-4fec-ab09-52c47c1acaff"

typeIdinteger, (int32)

Indicates the Flute ACH (automated clearing house) transaction type code.

Example: 6

Example:6

typestring or null

Indicates the Flute ACH transaction type.

Example: CardAuthentication

Example:"CardAuthentication"

statusIdinteger, (int32)

Indicates the Flute ACH transaction status code.

Example: 1

Example:1

statusstring or null

Indicates the Flute ACH transaction status type.

Example: Authorized

Example:"Authorized"

responseDescriptionstring or null

Indicates a free-formed description regarding the transaction.

Example: Command Successful. Approved.

Example:"Command Successful. Approved."

responseCodestring or null

Indicates a response code regarding the transaction.

Example: 000

Example:"000"

processedAmountnumber, (double)

Indicates the transaction amount (in USD).

Example: 3500.00

Example:3500

Response

Valid parameters. Approved

{
  "processedAmount": 0,
  "transactionId": "5758166f-3608-4625-8dd6-04124a633581",
  "typeId": 12,
  "type": "AchRefund",
  "statusId": 23,
  "status": "ChargedBack",
  "responseDescription": "Command Successful. Approved.",
  "responseCode": "000"
}