Receiving ACH Payments

Unit allows you to receive ACH payments. For general information on the ACH network, we recommend the following series from Gusto: How ACH Works: a Developer's Perspective.

info

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

You may receive ACH payments (both Debit and Credit) into any deposit account. To do so, you may provide the routing number and account number to trusted third parties. These numbers are both attributes of any deposit account. Received ACH payments are processed automatically.

You can get notified by listening to the transaction.created webhook and inspecting the payload for a received ACH transaction.

Examples:

• Receiving an ACH Credit in the amount of $20 when the balance is $0 will automatically result in a balance increase. Two transactions will be created: one received ACH transaction and one associated fee transaction (if the fee is non-zero).
• Receiving an ACH Debit in the amount of $20 when the balance is $10 will automatically result in an ACH return to the originating side of the payment. No transactions will be created.

Received Payment Resource

A Received Payment resource is created when an incoming ACH is processed. The initial status and the lifecycle of the Received Payments may vary according to different factors that may lead to one of two final statuses: Completed or Returned

Some Received Payments are not completed immediately. This can happen when the Received ACH Credit is set to complete in a future date. In these cases, the funds will only become available (and the transaction will be created) on the completion date.

When this happens, a Received Payment resource is created, in a Pending status. You may provide the end customer with early access to those funds by implementing the Advance Received Payment capability.

The Received Payment resource can have the following statuses:

Status	Description
Pending	The received payment was created with a future completion date. Pending payments can be advanced.
Advanced	The received-payment was advanced by the client. Once the completion date arrives, the status will change to Completed and the client will be repaid.
PendingReview	The received payment is pending for a review by Unit.
MarkedForReturn	The received payment was rejected and is waiting to be returned to the originating bank. It is marked for return to indicate that the transaction has been unsuccessful and needs to be processed in the opposite direction.
Returned	The received payment was returned (see return reasons for more details).
Completed	The received payment was completed. This happens once the payment completion date arrives. If the payment was previously advanced, the client will automatically be repaid.

Get by Id

Get a received payment by id.

Verb	GET
Url	https://api.s.unit.sh/received-payments/{id}
Required Scope	received-payments
Timeout (Seconds)	5

Query Parameters

Name	Type	Default	Description
include	string	(empty)	Optional. A comma-separated list of related resources to include in the response. Related resources include: customer, account. See Getting Related Resources

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Received Payment	A ReceivedPayment resource.
included	Array of DepositAccount or Customer	Array of resources requested by the include query parameter.

curl -X GET 'https://api.s.unit.sh/received-payments/100' \
-H "Authorization: Bearer ${TOKEN}"

List

List received payments. Filtering, paging and sorting can be applied.

Verb	GET
Url	https://api.s.unit.sh/received-payments
Required Scope	received-payments
Timeout (Seconds)	5

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]	integer	0	Number of resources to skip. See Pagination.
filter[accountId]	string	(empty)	Optional. Filters the results by the specified account id.
filter[customerId]	string	(empty)	Optional. Filters the results by the specified customer id.
filter[since]	ISO Local Date string	(empty)	Optional. Filters before the specified date. e.g. 2021-06-01
filter[until]	ISO Local Date string	(empty)	Optional. Filters after the specified date. e.g. 2021-07-01
filter[status][]	ReceivedPayment Status (JSON)	(empty)	Optional. Filter Received Payments by ReceivedPayment Status. Usage example: filter[status][0]=Pending&filter[status][1]=Advanced. cant be stated with includeCompleted.
filter[fromAmount]	Integer	(empty)	Optional. Filters the Received Payment that have an amount that is higher or equal to the specified amount (in cents). e.g. 5000
filter[toAmount]	Integer	(empty)	Optional. Filters the Received Payment that have an amount that is lower or equal to the specified amount (in cents). e.g. 7000
filter[includeCompleted]	boolean	(empty)	Optional. Filter to include ReceivedPayment with Status 'Completed', default False. cant be stated with filter[status[]
filter[canBeReprocessed]	boolean	(empty)	Optional. If set to true, returns only Received Payments that can be reprocessed. If set to false only returns Received Payments that can’t be reprocessed.
filter[tags]	Tags (JSON)	(empty)	Optional. Filter received payments by Tags.
sort	string	sort=createdAt	Optional. Leave empty or provide sort=createdAt for ascending order. Provide sort=-createdAt (leading minus sign) for descending order.
include	string	(empty)	Optional. A comma-separated list of related resources to include in the response. Related resources include: customer, account. See Getting Related Resources

curl -X GET 'https://api.s.unit.sh/received-payments?page[limit]=20&page[offset]=10&filter[includeCompleted]=true' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Array of Received Payment	Array of received payment resources.
included	Array of DepositAccount or Customer or Transaction	Array of resources requested by the include query parameter.
meta	JSON object that contains pagination data	Pagination data includes offset, limit and total (estimated total items).

Example Response:

{
  "data": [
    {
      "type": "achReceivedPayment",
      "id": "1337",
      "attributes": {
        "createdAt": "2022-02-01T12:03:14.406Z",
        "status": "Pending",
        "wasAdvanced": false,
        "isAdvanceable": false,
        "direction": "Credit",
        "amount": 500000,
        "completionDate": "2020-07-30",
        "companyName": "UBER LTD",
        "counterpartyRoutingNumber": "051402372",
        "description": "Paycheck",
        "traceNumber": "123456789123456",
        "secCode": "PPD"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "account",
            "id": "163575"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "129528"
          }
        }
      }
    },
    {
      "type": "achReceivedPayment",
      "id": "1339",
      "attributes": {
        "createdAt": "2022-03-01T12:03:14.406Z",
        "status": "Completed",
        "wasAdvanced": true,
        "amount": 100000,
        "completionDate": "2020-07-30",
        "companyName": "UBER LTD",
        "counterpartyRoutingNumber": "051402372",
        "description": "Paycheck",
        "traceNumber": "123456789123456",
        "secCode": "PPD"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "account",
            "id": "163555"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "129522"
          }
        },
        "receivePaymentTransaction": {
          "data": {
            "type": "transaction",
            "id": "101"
          }
        },
        "paymentAdvanceTransaction": {
          "data": {
            "type": "transaction",
            "id": "202"
          }
        },
        "repayPaymentAdvanceTransaction": {
          "data": {
            "type": "transaction",
            "id": "890"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "limit": 100,
      "offset": 0
    }
  }
}

Update

Update a Received Payment.

Verb	PATCH
Url	https://api.s.unit.sh/received-payments/:id
Required Scope	received-payments-write
Timeout (Seconds)	5

Attributes

Name	Type	Description
tags	object	See Updating Tags.

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Received Payment	The updated Received Payment resource.

Update received payment:

curl -X PATCH 'https://api.s.unit.sh/received-payments/:id'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "achReceivedPayment",
    "attributes": {
      "tags": {
        "by": "Richard Hendricks",
        "id": "23033b64-38f8-4dbc-91a1-313ff0156d02"
      }
    }
  }
}'

Advance Received Payment

Advance a Received Payment.

note

In order to use this API, you must implement the Advance Received Payment capability. Only received payments that are in status Pending can be advanced.

Verb	POST
Url	https://api.s.unit.sh/received-payments/{id}/advance
Required Scope	received-payments-write
Timeout (Seconds)	5

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Received Payment	The advanced received payment.

curl -X POST 'https://api.s.unit.sh/received-payments/61212/advance' \
-H "Authorization: Bearer ${TOKEN}"

Reprocess Received Payment

Reprocess a Received ACH Debit Payment in case it was MarkedForReturn due to InsufficientFunds.

note

The reprocess functionality is disabled by default. If you would like to enable it, please contact Unit. Only received payments that are in status MarkedForReturn can be reprocessed.

Verb	POST
Url	https://api.s.unit.sh/received-payments/{id}/reprocess
Required Scope	received-payments-write
Timeout (Seconds)	5

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Received Payment	The reprocessed received payment.

curl -X POST 'https://api.s.unit.sh/received-payments/61212/reprocess' \
-H "Authorization: Bearer ${TOKEN}"