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 ResourceSome received payments are not completed immediately. This typically happens when the received ACH credit is set to complete in a future date. In those 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. |
Advanced | The received-payment was advanced from Pending . once the payment is processed it will change to Completed . |
Completed | The received-payment was completed and processed. This an happen if settlementDate arrived or other reasons. an Advanced received payment will be repaid. |
Returned | The received payment was returned (see returnReason for more details) |
Get by Id#
Get a received payment by id.
Verb | GET |
Url | https://api.s.unit.sh/received-payments/{id} |
Required Scope | received-payments |
#
Query ParametersName | 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 |
#
ResponseResponse is a JSON:API document.
#
200 OKField | 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 |
#
Query ParametersName | 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[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[includeCompleted] | boolean | (empty) | Optional. Filter to include ReceivedPayment with Status 'Completed', default False. cant be stated with filter[status[] |
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}"
#
ResponseResponse is a JSON:API document.
#
200 OKField | 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 (total items). |
{ "data": [ { "type": "achReceivedPayment", "id": "1337", "attributes": { "createdAt": "2022-02-01T12:03:14.406Z", "status": "Pending", "wasAdvanced": false, "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 |
#
AttributesName | Type | Description |
---|---|---|
tags | object | See Updating Tags. |
#
ResponseResponse is a JSON:API document.
#
200 OKField | Type | Description |
---|---|---|
data | ReceivedPayment | The updated ReceivedPayment resource. |
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 |
#
ResponseResponse is a JSON:API document.
#
200 OKField | 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}"