ACH Transfers

ACH transfers move funds between your Increase account and any other account accessible by the Automated Clearing House (ACH).

The ACH Transfer object
{ "account_id": "account_in71c4amph0vgo2qllky", "account_number": "987654321", "acknowledgement": { "acknowledged_at": "2020-01-31T23:59:59Z" }, "addenda": null, "amount": 100, "approval": { "approved_at": "2020-01-31T23:59:59Z", "approved_by": null }, "cancellation": null, "company_descriptive_date": null, "company_discretionary_data": null, "company_entry_description": null, "company_id": "1234987601", "company_name": "National Phonograph Company", "created_at": "2020-01-31T23:59:59Z", "created_by": { "category": "user", "user": { "email": "user@example.com" } }, "currency": "USD", "destination_account_holder": "business", "external_account_id": "external_account_ukk55lr923a3ac0pp7iv", "funding": "checking", "id": "ach_transfer_uoxatyh3lt5evrsdvo7q", "idempotency_key": null, "inbound_funds_hold": null, "individual_id": null, "individual_name": "Ian Crease", "network": "ach", "notifications_of_change": [], "pending_transaction_id": null, "preferred_effective_date": { "date": null, "settlement_schedule": "same_day" }, "return": null, "routing_number": "101050001", "settlement": null, "standard_entry_class_code": "corporate_credit_or_debit", "statement_descriptor": "Statement descriptor", "status": "returned", "submission": { "effective_date": "2020-01-31", "expected_funds_settlement_at": "2020-02-03T13:30:00Z", "expected_settlement_schedule": "future_dated", "submitted_at": "2020-01-31T23:59:59Z", "trace_number": "058349238292834" }, "transaction_id": "transaction_uyrp7fld2ium70oa7oi", "type": "ach_transfer" }
Attributes
account_id
string

The Account to which the transfer belongs.

account_number
string

The destination account number.

acknowledgement
dictionary
Nullable

After the transfer is acknowledged by FedACH, this will contain supplemental details. The Federal Reserve sends an acknowledgement message for each file that Increase submits.

addenda
dictionary
Nullable

Additional information that will be sent to the recipient.

amount
integer

The transfer amount in USD cents. A positive amount indicates a credit transfer pushing funds to the receiving account. A negative amount indicates a debit transfer pulling funds from the receiving account.

approval
dictionary
Nullable

If your account requires approvals for transfers and the transfer was approved, this will contain details of the approval.

cancellation
dictionary
Nullable

If your account requires approvals for transfers and the transfer was not approved, this will contain details of the cancellation.

company_descriptive_date
string
Nullable

The description of the date of the transfer.

company_discretionary_data
string
Nullable

The data you chose to associate with the transfer.

company_entry_description
string
Nullable

The description of the transfer you set to be shown to the recipient.

company_id
string

The company ID associated with the transfer.

company_name
string
Nullable

The name by which the recipient knows you.

created_at
string

The ISO 8601 date and time at which the transfer was created.

created_by
dictionary
Nullable

What object created the transfer, either via the API or the dashboard.

currency
enum

The ISO 4217 code for the transfer's currency. For ACH transfers this is always equal to usd.

destination_account_holder
enum

The type of entity that owns the account to which the ACH Transfer is being sent.

external_account_id
string
Nullable

The identifier of the External Account the transfer was made to, if any.

funding
enum

The type of the account to which the transfer will be sent.

id
string

The ACH transfer's identifier.

idempotency_key
string
Nullable

The idempotency key you chose for this object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about idempotency.

inbound_funds_hold
dictionary
Nullable

Increase will sometimes hold the funds for ACH debit transfers. If funds are held, this sub-object will contain details of the hold.

individual_id
string
Nullable

Your identifier for the transfer recipient.

individual_name
string
Nullable

The name of the transfer recipient. This value is information and not verified by the recipient's bank.

network
string

The transfer's network.

notifications_of_change
array

If the receiving bank accepts the transfer but notifies that future transfers should use different details, this will contain those details.

pending_transaction_id
string
Nullable

The ID for the pending transaction representing the transfer. A pending transaction is created when the transfer requires approval by someone else in your organization.

preferred_effective_date
dictionary

Configuration for how the effective date of the transfer will be set. This determines same-day vs future-dated settlement timing. If not set, defaults to a settlement_schedule of same_day. If set, exactly one of the child attributes must be set.

return
dictionary
Nullable

If your transfer is returned, this will contain details of the return.

routing_number
string

The American Bankers' Association (ABA) Routing Transit Number (RTN).

settlement
dictionary
Nullable

A subhash containing information about when and how the transfer settled at the Federal Reserve.

standard_entry_class_code
enum

The Standard Entry Class (SEC) code to use for the transfer.

statement_descriptor
string

The descriptor that will show on the recipient's bank statement.

status
enum

The lifecycle status of the transfer.

submission
dictionary
Nullable

After the transfer is submitted to FedACH, this will contain supplemental details. Increase batches transfers and submits a file to the Federal Reserve roughly every 30 minutes. The Federal Reserve processes ACH transfers during weekdays according to their posted schedule.

transaction_id
string
Nullable

The ID for the transaction funding the transfer.

type
string

A constant representing the object's type. For this resource it will always be ach_transfer.

List ACH Transfers
curl \ --url "${INCREASE_URL}/ach_transfers?account_id=account_in71c4amph0vgo2qllky" \ -H "Authorization: Bearer ${INCREASE_API_KEY}"
Parameters
cursor
string

Return the page of entries after this one.

limit
integer

Limit the size of the list that is returned. The default (and maximum) is 100 objects.

account_id
string

Filter ACH Transfers to those that originated from the specified Account.

external_account_id
string

Filter ACH Transfers to those made to the specified External Account.

idempotency_key
string

Filter records to the one with the specified idempotency_key you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about idempotency.

200 character maximum
status.in
array of strings

Return results whose value is in the provided list. For GET requests, this should be encoded as a comma-delimited string, such as ?in=one,two,three.

created_at.after
string

Return results after this ISO 8601 timestamp.

created_at.before
string

Return results before this ISO 8601 timestamp.

created_at.on_or_after
string

Return results on or after this ISO 8601 timestamp.

created_at.on_or_before
string

Return results on or before this ISO 8601 timestamp.

Create an ACH Transfer
curl -X "POST" \ --url "${INCREASE_URL}/ach_transfers" \ -H "Authorization: Bearer ${INCREASE_API_KEY}" \ -H "Content-Type: application/json" \ -d $'{ "account_id": "account_in71c4amph0vgo2qllky", "account_number": "987654321", "amount": 100, "routing_number": "101050001", "statement_descriptor": "New ACH transfer" }'
Parameters
account_id
string
Required

The Increase identifier for the account that will send the transfer.

account_number
string

The account number for the destination account.

17 character maximum
addenda
dictionary

Additional information that will be sent to the recipient. This is included in the transfer data sent to the receiving bank.

amount
integer
Required

The transfer amount in USD cents. A positive amount originates a credit transfer pushing funds to the receiving account. A negative amount originates a debit transfer pulling funds from the receiving account.

company_descriptive_date
string

The description of the date of the transfer, usually in the format YYMMDD. This is included in the transfer data sent to the receiving bank.

6 character maximum
company_discretionary_data
string

The data you choose to associate with the transfer. This is included in the transfer data sent to the receiving bank.

20 character maximum
company_entry_description
string

A description of the transfer. This is included in the transfer data sent to the receiving bank.

10 character maximum
company_name
string

The name by which the recipient knows you. This is included in the transfer data sent to the receiving bank.

16 character maximum
destination_account_holder
enum

The type of entity that owns the account to which the ACH Transfer is being sent.

external_account_id
string

The ID of an External Account to initiate a transfer to. If this parameter is provided, account_number, routing_number, and funding must be absent.

funding
enum

The type of the account to which the transfer will be sent.

individual_id
string

Your identifier for the transfer recipient.

15 character maximum
individual_name
string

The name of the transfer recipient. This value is informational and not verified by the recipient's bank.

22 character maximum
preferred_effective_date
dictionary

Configuration for how the effective date of the transfer will be set. This determines same-day vs future-dated settlement timing. If not set, defaults to a settlement_schedule of same_day. If set, exactly one of the child attributes must be set.

require_approval
boolean

Whether the transfer requires explicit approval via the dashboard or API.

routing_number
string

The American Bankers' Association (ABA) Routing Transit Number (RTN) for the destination account.

9 character maximum
standard_entry_class_code
enum

The Standard Entry Class (SEC) code to use for the transfer.

statement_descriptor
string
Required

A description you choose to give the transfer. This will be saved with the transfer details, displayed in the dashboard, and returned by the API. If individual_name and company_name are not explicitly set by this API, the statement_descriptor will be sent in those fields to the receiving bank to help the customer recognize the transfer. You are highly encouraged to pass individual_name and company_name instead of relying on this fallback.

200 character maximum
transaction_timing
enum

The timing of the transaction.

Retrieve an ACH Transfer
curl \ --url "${INCREASE_URL}/ach_transfers/ach_transfer_uoxatyh3lt5evrsdvo7q" \ -H "Authorization: Bearer ${INCREASE_API_KEY}"
Parameters
ach_transfer_id
string
Required

The identifier of the ACH Transfer.

Approve an ACH Transfer

Approves an ACH Transfer in a pending_approval state.

curl -X "POST" \ --url "${INCREASE_URL}/ach_transfers/ach_transfer_uoxatyh3lt5evrsdvo7q/approve" \ -H "Authorization: Bearer ${INCREASE_API_KEY}"
Parameters
ach_transfer_id
string
Required

The identifier of the ACH Transfer to approve.

Cancel a pending ACH Transfer

Cancels an ACH Transfer in a pending_approval state.

curl -X "POST" \ --url "${INCREASE_URL}/ach_transfers/ach_transfer_uoxatyh3lt5evrsdvo7q/cancel" \ -H "Authorization: Bearer ${INCREASE_API_KEY}"
Parameters
ach_transfer_id
string
Required

The identifier of the pending ACH Transfer to cancel.

Sandbox: Acknowledge an ACH Transfer

Simulates the acknowledgement of an ACH Transfer by the Federal Reserve. This transfer must first have a status of submitted . In production, the Federal Reserve generally acknowledges submitted ACH files within 30 minutes. Since sandbox ACH Transfers are not submitted to the Federal Reserve, this endpoint allows you to skip that delay and add the acknowledgment subresource to the ACH Transfer.

curl -X "POST" \ --url "${INCREASE_URL}/simulations/ach_transfers/ach_transfer_uoxatyh3lt5evrsdvo7q/acknowledge" \ -H "Authorization: Bearer ${INCREASE_API_KEY}"
Parameters
ach_transfer_id
string
Required

The identifier of the ACH Transfer you wish to become acknowledged.

Sandbox: Create a Notification of Change for an ACH Transfer

Simulates receiving a Notification of Change for an ACH Transfer.

curl -X "POST" \ --url "${INCREASE_URL}/simulations/ach_transfers/ach_transfer_uoxatyh3lt5evrsdvo7q/create_notification_of_change" \ -H "Authorization: Bearer ${INCREASE_API_KEY}" \ -H "Content-Type: application/json" \ -d $'{ "change_code": "incorrect_routing_number", "corrected_data": "123456789" }'
Parameters
ach_transfer_id
string
Required

The identifier of the ACH Transfer you wish to create a notification of change for.

change_code
enum
Required

The reason for the notification of change.

corrected_data
string
Required

The corrected data for the notification of change (e.g., a new routing number).

200 character maximum
Sandbox: Return an ACH Transfer

Simulates the return of an ACH Transfer by the Federal Reserve due to an error condition. This will also create a Transaction to account for the returned funds. This transfer must first have a status of submitted.

curl -X "POST" \ --url "${INCREASE_URL}/simulations/ach_transfers/ach_transfer_uoxatyh3lt5evrsdvo7q/return" \ -H "Authorization: Bearer ${INCREASE_API_KEY}" \ -H "Content-Type: application/json" \ -d $'{}'
Parameters
ach_transfer_id
string
Required

The identifier of the ACH Transfer you wish to return.

reason
enum

The reason why the Federal Reserve or destination bank returned this transfer. Defaults to no_account.

Sandbox: Settle an ACH Transfer

Simulates the settlement of an ACH Transfer by the Federal Reserve. This transfer must first have a status of pending_submission or submitted. For convenience, if the transfer is in status: pending_submission, the simulation will also submit the transfer. Without this simulation the transfer will eventually settle on its own following the same Federal Reserve timeline as in production.

curl -X "POST" \ --url "${INCREASE_URL}/simulations/ach_transfers/ach_transfer_uoxatyh3lt5evrsdvo7q/settle" \ -H "Authorization: Bearer ${INCREASE_API_KEY}"
Parameters
ach_transfer_id
string
Required

The identifier of the ACH Transfer you wish to become settled.

Sandbox: Submit an ACH Transfer

Simulates the submission of an ACH Transfer to the Federal Reserve. This transfer must first have a status of pending_approval or pending_submission. In production, Increase submits ACH Transfers to the Federal Reserve three times per day on weekdays. Since sandbox ACH Transfers are not submitted to the Federal Reserve, this endpoint allows you to skip that delay and transition the ACH Transfer to a status of submitted.

curl -X "POST" \ --url "${INCREASE_URL}/simulations/ach_transfers/ach_transfer_uoxatyh3lt5evrsdvo7q/submit" \ -H "Authorization: Bearer ${INCREASE_API_KEY}"
Parameters
ach_transfer_id
string
Required

The identifier of the ACH Transfer you wish to submit.