Skip to main content

Overview

Payments in Unit represent requests to move funds that are initiated by the end customer. Payments are not final, and do not necessarily materialize into an actual movement of funds - they have a lifecycle that depends on the payment type.

Payments can be:

  • Rejected: Based on validity and risk checks, Unit has decided to reject the payment and not process it (e.g. crossed limits, insufficient funds).
  • Pending: Waiting to be processed or transmitted to the payment network.
  • Canceled: The payment was canceled by the client / end-customer before being sent to the network.
  • Pending Review: The payment is waiting to be manually reviewed, typically due to a high level of risk associated with that payment.
  • Clearing: In certain types of payments, once the funds are received by Unit, we hold on to them for a period, on your behalf, before releasing them to the end customer. Clearing is meant to minimize the risk of a costly return or fraud.
  • Sent: The payment has been fully processed.
  • Returned: The payment was processed but the network or the receiving bank returned the payment.

Sent payments result in a transaction being created.

Get Payment by Id

Get a payment by id.

VerbGET
Urlhttps://api.s.unit.sh/payments/{id}
Required Scopepayments
Timeout (Seconds)5

Query Parameters

NameTypeDefaultDescription
includestring(empty)Optional. A comma-separated list of related resources to include in the response. Related resources include: customer, account, transaction. See Getting Related Resources

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataOne of the following types (ACH Payment, Book Payment or Wire Payment)Payment resource.
includedArray of DepositAccount or Customer or TransactionArray of resources requested by the include query parameter.
curl -X GET 'https://api.s.unit.sh/payments/100' \
-H "Authorization: Bearer ${TOKEN}"

List Payments

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

VerbGET
Urlhttps://api.s.unit.sh/payments
Required Scopepayments
Timeout (Seconds)120

Query Parameters

NameTypeDefaultDescription
page[limit]integer100Optional. Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]integer0Optional. 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[counterpartyAccountId]string(empty)Optional. Filters the Payments by the account id of the specified counterparty.
filter[tags]Tags (JSON)(empty)Optional. Filter Payments by Tags.
filter[status][]ACH Status (JSON)(empty)Optional. Filter Payments by ACH Status. Usage example: filter[status][0]=Pending&filter[status][1]=PendingReview
filter[type][]string(empty)Optional. Filter Payments by Payment type. such as (AchPayment, BookPayment or WirePayment). Usage example: filter[type][0]=AchPayment&filter[type][1]=WirePayment
filter[direction][]string(empty)Optional. Filter Payments by direction (Debit, Credit). Usage example: filter[direction][0]=Debit
filter[since]RFC3339 Date string(empty)Optional. Filters the Payments that occurred after the specified date. e.g. 2020-01-13T16:01:19.346Z
filter[until]RFC3339 Date string(empty)Optional. Filters the Payments that occurred before the specified date. e.g. 2020-01-02T20:06:23.486Z
filter[fromAmount]Integer(empty)Optional. Filters the Payments 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 Payments that have an amount that is lower or equal to the specified amount (in cents). e.g. 7000
filter[recurringPaymentId]string(empty)Optional. Filters the results by the specified recurring payment id.
filter[feature][]string(empty)Optional. Filter Payments by Payment feature (SameDay, RecurringPayment). Usage example: filter[feature][0]=SameDay
sortstringsort=-createdAtOptional. Leave empty or provide sort=createdAt for ascending order. Provide sort=-createdAt (leading minus sign) for descending order.
includestring(empty)Optional. A comma-separated list of related resources to include in the response. Related resources include: customer, account, transaction. See Getting Related Resources
curl -X GET 'https://api.s.unit.sh/payments?page[limit]=20&page[offset]=10&filter[status][]=Pending&filter[status][]=Clearing' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataArray of Payments (ACH Payment, Book Payment or Wire Payment)Array of payment resources.
includedArray of DepositAccount or Customer or TransactionArray of resources requested by the include query parameter.
metaJSON object that contains pagination dataPagination data includes offset, limit and total (estimated total items).
Example Response:
{
"data": [
{
"type": "achPayment",
"id": "50",
"attributes": {
"createdAt": "2020-01-13T16:01:19.346Z",
"status": "Pending",
"counterparty": {
"routingNumber": "812345678",
"accountNumber": "12345569",
"accountType": "Checking",
"name": "Jane Doe"
},
"description": "Funding",
"direction": "Credit",
"amount": 10000
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "555"
}
},
"customer": {
"data": {
"type": "individualCustomer",
"id": "99823"
}
},
"counterparty": {
"data": {
"type": "counterparty",
"id": "4567"
}
},
"transaction": {
"data": {
"type": "transaction",
"id": "4003"
}
}
}
}
],
"meta": {
"pagination": {
"total": 1,
"limit": 100,
"offset": 0
}
}
}

Create Bulk Payment

Bulk payments can contain multiple payment creation requests from different types (ACH, Book, Wire).

caution

It is highly recommended to attach to each payment creation request an idempotency key. This will ensure no creation duplication.

note

Bulk is an asynchronous process. The immediate response will be the bulkId (generated by Unit). Once all payments creations in bulk are finished a bulkPayments.finished webhook event is sent by Unit. If not supplied, Unit will generate idempotency key as bulkId indexInBulk combination.

VerbPOST
Urlhttps://api.s.unit.sh/payments/bulk
Required Scopepayments-write
Timeout (Seconds)5
Example Request:
curl -X POST 'https://api.s.unit.sh/payments/bulk'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": [
{
"type": "wirePayment",
"attributes": {
"amount": 200,
"direction": "Credit",
"description": "Wire payment",
"counterparty": {
"name": "April Oniel",
"routingNumber": "812345678",
"accountNumber": "1000000001",
"address": {
"street": "20 Ingram St",
"city": "Forest Hills",
"state": "CA",
"postalCode": "11375",
"country": "US"
}
},
"idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb9"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "10000"
}
}
}
},
{
"type": "bookPayment",
"attributes": {
"amount": 10000,
"description": "Funding",
"idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "10001"
}
},
"counterpartyAccount": {
"data": {
"type": "depositAccount",
"id": "10000"
}
}
}
}
]
}'

Response

Response is a JSON:API document.

Example Response:
{
"data": {
"type": "bulkPayments",
"attributes": {
"bulkId": "18"
}
}
}
|