Skip to main content

Overview

Unit allows you to originate next day and same day ACH payments.

info

For more information on originating ACH payments, please refer to Unit's ACH Guide

In Unit, an ACH payment originates from a Deposit Account. The entity on the other side of the payment is called a Counterparty. A counterparty is a combination of routing number, account number, account type, and name.

Each ACH payment has a direction - either Debit or Credit. In the context of ACH payment origination, the directions work as follows:

  • Debit - the payment "pulls" funds from the counterparty account. The amount is credited to the originating deposit account on Unit. It may take several banking (business) days for the credit to be settled, depending on the settings for your organization.
  • Credit - the payment "pushes" funds to the counterparty account. The amount is debited from the originating deposit account immediately.

Originating an ACH payment supports Idempotency, to ensure that multiple identical requests will have the same effect as a single request.

ACH payment originations (both Debit and Credit) are subject to soft and hard daily amount limits determined by the account's deposit product. Once the Soft limit is exceeded, payments will automatically be submitted for manual review. Debit ACHs can only be manually approved if a balance check for the counterparty is successful. Once you exceed the account's total daily limit, payments will be created under the Rejected status code, and the relevant API responses will contain the exact reason. You may contact Unit to change the limits for an account or a group of accounts. See the Limits section for more information.

note

Some ACH payments will automatically be converted into Book Payments upon creation. These will be logged and appear as ACH on the account but function as book payments (e.g. status flows, limits, clearing times etc.), except for when both counterparties are customers of your organisation, in which case the payment will also be logged as a book payment.

ACH Statuses#

The ACH network operates in batches. When you originate an ACH payment, it will mostly be created with a Pending status. See note above for examples of when the status won't be Pending initially. You may track a payment's progress using the status attribute or listening to relevant webhooks, such as payment.sent or payment.returned.

The possible status values are listed below and you should be prepared to receive all statuses:

StatusDescription
PendingThe payment was created on the Unit ledger but was not yet delivered to the ACH network. Payments with Pending status may be canceled by the originator. When your clearing period is set to 0, the amount will be credited immediately when payment goes into Pending.
PendingReviewThe payment is pending review by Unit.
RejectedThe payment was rejected due to insufficient funds or exceeding daily ACH limits (see rejection reasons for more details)
Clearing(Debit only) The payment was sent but the deposit account was not credited yet.
SentThe payment was processed by the ACH network. This is the final state for successful payments.
CanceledThe payment was canceled.
ReturnedThe payment was processed but the network or the receiving bank returned the payment (see return reasons for more details)

Same-day ACH#

Same-day ACH enables your clients to send and receive funds using ACH the same day the payment is created. You can read more about same-day ACH in the relevant section of the Unit ACH guide.

note

The same day ACH functionality is disabled by default and is only available for specific use cases. If you would like to use same day ACH, please contact Unit.

Use a Custom Standard Entry Class (SEC) Code#

A Standard Entry Class (SEC) code is a mandatory three-letter code used in all ACH payments (originated and received) in order identify certain types of ACH payments.
The SEC Code generally indicates:

  • The nature of the transaction as consumer or corporate in nature. It indicates whether the funds transfer affects a consumer account or a corporate account at the RDFI (receiving depository financial institutions).
  • Whether the transaction is single-entry or recurring.
  • The specific computer record format that will be used to carry the payment and payment-related information relevant to the application.

The use of Custom Standard Entry Class (SEC) Code is currently limited to ACH Credit and specific codes as described below:

Customer TypeSupported SEC codes (ACH Origination)
IndividualWEB (default), PPD
BusinessCCD (default), PPD
note

The custom SEC code functionality is disabled by default. If you would like to enable it, please contact Unit.

Create ACH payment to inline Counterparty#

Originates an ACH payment to a counterparty which is specified inline (vs to a linked Counterparty Resource).

VerbPOST
Urlhttps://api.s.unit.sh/payments
Required Scopepayments-write
Data TypeachPayment
Timeout (Seconds)5
note

Originating ACH debits requires capturing the authorization of the account owner and therefore originating ACH debits to inline counterparties is not allowed by default. If your use case requires this capability, please contact Unit.

Attributes#

NameTypeDescription
amountintegerThe amount (in cents).
directionstringThe direction in which the funds flow.
counterpartyCounterpartyThe party on the other side of the ACH payment.
descriptionstringPayment description (maximum of 10 characters), also known as Company Entry Description, this will show up on statement of the counterparty.
addendastringOptional, additional payment description (maximum of 80 characters), not all institutions present that.
idempotencyKeystringOptional. See Idempotency.
tagsobjectOptional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).
sameDaybooleanOptional, default is false. See Same Day ACH.
secCodestringOptional. See Use a custom SEC Code.

Relationships#

NameTypeDescription
accountJSON:API RelationshipThe Deposit Account originating the payment.
Example Request:
curl -X POST 'https://api.s.unit.sh/payments'-H 'Content-Type: application/vnd.api+json'-H 'Authorization: Bearer ${TOKEN}'--data-raw '{  "data": {    "type": "achPayment",    "attributes": {      "amount": 10000,      "direction": "Credit",      "counterparty": {        "routingNumber": "812345673",        "accountNumber": "12345569",        "accountType": "Checking",        "name": "Jane Doe"      },      "description": "Funding"    },    "relationships": {      "account": {        "data": {          "type": "account",          "id": "555"        }      }    }  }}'

Response#

Response is a JSON:API document.

Example Response:
{  "data": {    "type": "achPayment",    "id": "50",    "attributes": {      "createdAt": "2020-01-13T16:01:19.346Z",      "status": "Pending",      "reason": null,      "counterparty": {        "routingNumber": "812345673",        "accountNumber": "12345569",        "accountType": "Checking",        "name": "Jane Doe"      },      "description": "Funding",      "direction": "Credit",      "amount": 10000,      "tags": {        "purpose": "internal"      }    },    "relationships": {      "account": {        "data": {          "type": "depositAccount",          "id": "555"        }      },      "customer": {        "data": {          "type": "individualCustomer",          "id": "99823"        }      }    }  }}

Create ACH payment to linked Counterparty#

Originates an ACH payment to a Counterparty. The counterparty should be created separately through Create Counterparty.

VerbPOST
Urlhttps://api.s.unit.sh/payments
Required Scopepayments-write-counterparty or payments-write
Data TypeachPayment
Timeout (Seconds)5

Attributes#

NameTypeDescription
amountintegerThe amount (in cents).
directionstringThe direction in which the funds flow.
descriptionstringPayment description (maximum of 10 characters), also known as Company Entry Description, this will show up on statement of the counterparty.
addendastringOptional, additional payment description (maximum of 80 characters), not all institutions present that.
idempotencyKeystringOptional. See Idempotency.
tagsobjectOptional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).
verifyCounterpartyBalancebooleanOptional, default is false. Verify the counterparty balance, if balance verification fails the payment will be rejected with reason set to CounterpartyInsufficientFunds.
sameDaybooleanOptional, default is false. See Same Day ACH.
secCodestringOptional. See Use a custom SEC Code.

Relationships#

NameTypeDescription
accountJSON:API RelationshipThe Deposit Account originating the payment.
counterpartyJSON:API RelationshipThe Counterparty the payment to be made to.
Example Request:
curl -X POST 'https://api.s.unit.sh/payments'-H 'Content-Type: application/vnd.api+json'-H 'Authorization: Bearer ${TOKEN}'--data-raw '{  "data": {    "type": "achPayment",    "attributes": {      "amount": 10000,      "direction": "Credit",      "description": "Funding"    },    "relationships": {      "account": {        "data": {          "type": "account",          "id": "555"        }      },      "counterparty": {        "data": {          "type": "counterparty",          "id": "4567"        }      }    }  }}'

Response#

Response is a JSON:API document.

Example Response:
{  "data": {    "type": "achPayment",    "id": "50",    "attributes": {      "createdAt": "2020-01-13T16:01:19.346Z",      "status": "Pending",      "reason": null,      "counterparty": {        "routingNumber": "812345678",        "accountNumber": "12345569",        "accountType": "Checking",        "name": "Jane Doe"      },      "description": "Funding",      "direction": "Credit",      "amount": 10000,      "tags": {        "purpose": "internal"      }    },    "relationships": {      "account": {        "data": {          "type": "depositAccount",          "id": "555"        }      },      "customer": {        "data": {          "type": "individualCustomer",          "id": "99823"        }      },      "counterparty": {        "data": {          "type": "counterparty",          "id": "4567"        }      }    }  }}

Create ACH payment with Plaid token#

Originates an ACH payment to a counterparty which is verified by Plaid.

info

For more information on using Plaid, please read Unit's Plaid partnership guide

VerbPOST
Urlhttps://api.s.unit.sh/payments
Required Scopepayments-write or payments-write-ach-debit
Data TypeachPayment
Timeout (Seconds)5
note

You can use scope payments-write-ach-debit only with ACH Debit payments.

Attributes#

NameTypeDescription
amountintegerThe amount (in cents)
directionstringThe direction in which the funds flow
descriptionstringPayment description (maximum of 10 characters), also known as Company Entry Description, this will show up on statement of the counterparty.
addendastringOptional, additional payment description (maximum of 80 characters), not all institutions present that.
idempotencyKeystringOptional. See idempotency
counterpartyNamestringOptional. Name of the person or company that owns the counterparty bank account.
plaidProcessorTokenstringSee Create Plaid processor token API
tagsobjectOptional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).
verifyCounterpartyBalancebooleanOptional, default is false. Verify the counterparty balance, if balance verification fails the payment will be rejected with reason set to CounterpartyInsufficientFunds.
sameDaybooleanOptional, default is false. See Same Day ACH.
secCodestringOptional. See Use a custom SEC Code.

Relationships#

NameTypeDescription
accountJSON:API RelationshipThe Deposit Account originating the payment
Example Request:
curl -X POST 'https://api.s.unit.sh/payments'-H 'Content-Type: application/vnd.api+json'-H 'Authorization: Bearer ${TOKEN}'--data-raw '{  "data": {    "type": "achPayment",    "attributes": {      "amount": 10000,      "direction": "Debit",      "plaidProcessorToken": "processor-5a62q307-ww0a-6737-f6db-pole26004556",      "description": "Funding"    },    "relationships": {      "account": {        "data": {          "type": "account",          "id": "555"        }      }    }  }}'

Response#

Response is a JSON:API document.

201 Created#

FieldTypeDescription
dataPaymentThe target resource after the operation was completed.

408 Request Timeout#

The request to Plaid has timed-out, probably because of a technical issue with the counterparty bank. You might want to retry the request without the verifyCounterpartyBalance flag.

Example Response:
{  "data": {    "type": "achPayment",    "id": "50",    "attributes": {      "createdAt": "2020-01-13T16:01:19.346Z",      "status": "Pending",      "reason": null,      "counterparty": {        "routingNumber": "812345673",        "accountNumber": "12345569",        "accountType": "Checking",        "name": "Jane Doe"      },      "description": "Funding",      "direction": "Credit",      "amount": 10000,      "tags": {        "purpose": "internal"      }    },    "relationships": {      "account": {        "data": {          "type": "depositAccount",          "id": "555"        }      },      "customer": {        "data": {          "type": "individualCustomer",          "id": "99823"        }      }    }  }}

Update ACH Payment#

Update an ACH Payment.

VerbPATCH
Urlhttps://api.s.unit.sh/payments/:paymentId
Required Scopepayments-write
Timeout (Seconds)5

Attributes#

NameTypeDescription
tagsobjectSee Updating Tags.
Update an ACH payment:
curl -X PATCH 'https://api.s.unit.sh/payments/:paymentId'-H 'Content-Type: application/vnd.api+json'-H 'Authorization: Bearer ${TOKEN}'--data-raw '{  "data": {    "type": "achPayment",    "attributes": {      "tags": {        "by": null,        "uuid": "83033b64-38f8-4dbc-91a1-313ff0156d02"      }    }  }}'

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataAchPaymentThe updated ACH payment resource.

Cancel ACH Payment#

Cancels a previously processed ACH payment. Only payments with status Pending or PendingReview can be canceled.

VerbPOST
Urlhttps://api.s.unit.sh/payments/{paymentId}/cancel
Required Scopepayments-write
Timeout (Seconds)5

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataACH PaymentThe canceled payment.
curl -X POST 'https://api.s.unit.sh/payments/61212/cancel' \-H "Authorization: Bearer ${TOKEN}"

Possible ACH rejection Reasons#

When creating an ACH payment, it may be rejected immediately due to the following reasons:

ReasonDescription
InsufficientFundsA credit payment to a counterparty was rejected due to account not having sufficient funds to cover the transaction.
DailyACHCreditLimitExceededThe credit payment amount exceeds the total daily ACH limit set by Unit.
DailyACHDebitLimitExceededThe debit payment amount exceeds the total daily ACH limit set by Unit.
MonthlyACHCreditLimitExceededThe credit payment amount exceeds the total monthly ACH limit set by Unit.
MonthlyACHDebitLimitExceededThe debit payment amount exceeds the total monthly ACH limit set by Unit.
CounterpartyInsufficientFundsA debit payment was rejected due to insufficient funds of the counterparty.
PlaidBalanceUnavailable(Plaid only) Unable to determine the balance of the counterparty.
PlaidLoginRequired(Plaid only) The Plaid Link authentication has become invalid and requires re-login. See this guide on re-initializing Plaid Link.
PlaidInvalidProduct or PlaidUnsupportedBank(Plaid only) The Plaid integration is not available. Please contact Unit.
PlaidInternalError(Plaid only) An error occurred while establishing a connection with Plaid. Please contact Unit.