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.
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 specific codes as described below:

DirectionCustomer TypeSupported SEC codes (ACH Origination)
CreditIndividual
Business
WEB (*default), PPD
CCD (default), PPD
DebitIndividual
Business
Not Supported
WEB (default), CCD
note

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

*Individuals who are Sole Proprietors will have their default SEC code set to CCD.

Dynamic Clearing Period (ACH Debit)

Dynamic Clearing Period enables you to set the amount of days it will take an Originated ACH debit to clear and funds to become available in a deposit account. When this feature is enabled, the value that is passed as clearingDaysOverride, will replace the default amount of clearing days as it is defined in the deposit product.

In order to enable the Dynamic Clearing Period feature, new definitions of maximum clearing days and minimum clearing days will need to be added to the deposit product so the clearingDaysOverride attribute will support values between the minimum clearing days and the maximum clearing days .

If a clearing days override is not specified when the ACH debit is created, the clearing period will be set to the default clearing period set in the deposit product.

The clearing period can be changed after the ACH debit resource has been created, as long as it is still in Pending or PendingReview status.

note

The dynamic clearing period 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 or ach-payments-write
Data TypeachPayment
Timeout (Seconds)60
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.
clearingDaysOverrideintegerOptional. See Dynamic Clearing Period

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 or ach-payments-write
Data TypeachPayment
Timeout (Seconds)60

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.
clearingDaysOverrideintegerOptional. See Dynamic Clearing Period

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 or ach-payments-write
Data TypeachPayment
Timeout (Seconds)60
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.
clearingDaysOverrideintegerOptional. See Dynamic Clearing Period

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.
clearingDaysOverrideintegerOnly supports ACH Payments with direction Debit in status PendingReview or Pending. See Dynamic Clearing Period
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"
},
"clearingDaysOverride": 3
}
}
}'

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.
SuspectedFraudUnit or the client suspects the payment may be fraudulent
ClientRequestClient requested Unit to cancel/reject the payment
NameMismatchThe counterparty name on the payment does not match the counterpaty name in the Plaid data
PlaidTokenErrorThere is an error retrieving Plaid data.
PlaidTokenExpiredThe plaid token expired. A new token will need to be linked
PlaidNotSupportedThe counterparty bank does not support Plaid