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.

note

ACH payment originations (both Debit and Credit) are subject to daily amount limits determined by the account's deposit product. 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

Originating a credit ACH payment to a counterparty whose account belongs to your organization will result in a Book Transaction.

ACH Statuses#

The ACH network operates in batches. When you originate an ACH payment, it will be created with a Pending status. You may track its progress using the status attribute or listening to relevant webhooks, such as payment.sent or payment.returned.

The possible status values are:

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.

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.

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": "depositAccount",          "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.

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": "depositAccount",          "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
counterpartyNamestringName of the person or company that owns the counterparty bank account.
plaidProcessorTokenstringSee Create Plaid processor token API
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.

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": "depositAccount",          "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.