Overview
The Check Payment resource represents a written check that was deposited in a BOFD (Bank of First Deposit) and received by Unit over Check21 services.
The Check Payment resource will become available either when originating a check payment with the Unit API or after a check was written with Unit Deposit Account details (routing number and account number), deposited at a bank, and then received by Unit.
Once Check Payment is processed successfully (Processed
status), a CheckPaymentTransaction
is created and the Deposit Account is debited.
Check Payments are not enabled by default. Please contact Unit if you would like to enable this functionality.
Check Payment Statuses
When a check payment resource is created it will be created with one of the following statuses Processed
, PendingReview
, MarkedForReturn
, or New
if it originated in Unit.
A checkPayment created webhook event will be fired for incoming check payments.
You may track its progress using the status
attribute or listening to relevant webhooks.
The possible status values are:
Status | Description |
---|---|
New | A request to originate a check payment has been registered and is being processed. |
Rejected | See rejectReason for further details. The most common reason for a check payment to be rejected is an unsuccessful validation of the counterparty's address. |
Pending | The check payment is pending submission and will be sent to the printers at the next cutoff time. |
Canceled | The originated check payment was canceled. This can only be done while check payment is in Pending status, and cannot be undone. |
PendingCancellation | a cancellation has been requested and is pending for a result. If the cancellation fails, the check will either return to Pending , or, if cut-off time has past, the check will transition directly into the next phase (most commonly InProduction ) |
InProduction | Cutoff time has passed. The check payment has been sent to the printers and can no longer be updated or canceled. |
InDelivery | The check payment has been accepted by the mail service and is en route. see deliveryStatus for further tracking information. |
Delivered | The check payment was delivered. |
ReturnedToSender | The check payment could not be delivered and has been returned to the sender. |
PendingReview | The check payment is pending review by Unit. |
Processed | The check payment was processed and the deposit account was debited. |
MarkedForReturn | The check payment was marked for return (see the return reason for more details). It will go into Returned next. If the check payment was already Processed , a ReturnedCheckPaymentTransaction be created to credit back the account. |
Returned | The check payment was returned (see the return reason for more details). |
Check Payment Return Reasons
Below is a list of some of the more common return reasons.
Note that only some of the reasons can be used to initiate a return using the Return Check Payment Endpoint. see the full list for more details.
Return Reason | Description |
---|---|
NotSufficientFunds | Account has insufficient funds |
UncollectedFundsHold | Funds are present in the account but are on hold |
StopPayment | A matching Stop Payment request was identified and a Check Payment was returned |
ClosedAccount | Account is closed |
UnableToLocateAccount | Matching account not found |
FrozenOrBlockedAccount | Account is Frozen or Check Payment is not enabled for client or Check Payment not enabled on Deposit Product |
StaleDated | The date on the check is too far in the past |
PostDated | The date on the check is in the future |
NotValidCheckOrCashItem | The item is not a valid check |
AlteredOrFictitious | The check has been altered or tampered with (e.g. the amount or recipient has been changed) |
UnableToProcess | The check cannot be processed (e.g. information may be missing from the check) |
ItemExceedsDollarLimit | Daily and/or monthly Check Payment limits have been crossed |
NotAuthorized | The check is not authorized (e.g. a fake check) |
ReferToMaker | |
UnusableImage | The check image quality is poor, unusable, or has multiple checks included |
DuplicatePresentment | The check has already been deposited in the past |
WarrantyBreach | |
UnauthorizedWarrantyBreach |
Check Payment Delivery Status
DeliveryStatus is used to track the progress of the check payment's delivery.
Following production, all check payments are sent from the printers to the mail service.
As a check travels to its destination in the mail stream, any time it is scanned will yield an update to the deliveryStatus
, alongside a CheckPayment.deliveryStatusChanged event.
Note that Unit does not have any control over the accuracy of scans or their availability. If one or more of the delivery status updates was not available, the corresponding events and statuses will be skipped as well.
You should be able to expect to start seeing your first delivery status update appear within 3 business days after the check's sendAt
.
Delivery Status | Description |
---|---|
Mailed | The check has been handed off to and accepted by the mail service. |
InLocalArea | The check payment is being processed at the destination facility. . This is the final delivery status for checks sent to P.O boxes. |
Delivered | The check payment has been delivered to its destination. |
Rerouted | The check payment has been re-routed. |
ReturnedToSender | The check payment could not be delivered and is being returned to the customer's address. No more tracking information will be available past this event. |
Originate Check Payment
Creates a physical check. The check will be printed and mailed to the US recipient specified in the request. Originated check payments can be set to be sent immediately or scheduled for a future date.
Verb | POST |
Url | https://api.s.unit.sh/check-payments |
Required Scope | check-payments-write |
Data Type | checkPayment |
Timeout (Seconds) | 5 |
Check payment origination is not supported for joint or Org accounts.
The check payment sender details will be sent with the customer details in our records. In order to fit on the printed check, the customer name
must be 40 characters or less, street
and street2
combined must be 50 characters or less. Signatures take take values from the customer's name
(individual) or officer
name (business) and can contain up to 30 characters. Longer values will be truncated past the maximum length.
Attributes
Name | Type | Description |
---|---|---|
amount | integer | The amount (in cents). Must be less than 100000000000 |
memo | string | Optional. Check payment memo. This will be printed on the check (maximum of 40 characters) |
sendDate | RFC3339 Date string | Optional. Date only (e.g. 2022-06-23). The date the check will be submitted to the processor. Up to 180 days in the future. If left null or in the past, will default to today. |
counterparty | Counterparty | The payee's details . street and street2 combined may contain up to 50 characters. country must be "US". |
Description | string | An internal description (maximum of 255 characters). This will not be printed on the check. |
idempotencyKey | string | See Idempotency. |
tags | object | Optional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance). |
Relationships
Name | Type | Description |
---|---|---|
account | JSON:API Relationship | The Deposit Account originating the payment. |
customer | JSON:API Relationship | Link to the customer the the check will be signed by. |
curl -X POST 'https://api.s.unit.sh/check-payments'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "checkPayment",
"attributes": {
"counterparty": {
"name": "April Oneil",
"address": {
"street": "20 Ingram St",
"city": "Forest Hills",
"state": "CA",
"postalCode": "11375",
"country": "US"
}
},
"amount": 1000,
"idempotencyKey": "asdfghjkl",
"description": "October paycheck",
"memo": "October paycheck"
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "123456"
}
},
"customer": {
"data": {
"type": "customer",
"id": "5678"
}
}
}
}
}'
Response
Response is a JSON:API document.
{
"data": {
"type": "checkPayment",
"id": "10000",
"status": "New",
"accountId": "100001",
"attributes": {
"amount": 100,
"sendAt": "2023-09-10T12:50:00.704Z",
"counterparty": {
"name": "John Doe",
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303"
}
}
}
}
}
Get by Id
Get a check payment by id.
Verb | GET |
Url | https://api.s.unit.sh/check-payments/{id} |
Required Scope | check-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 , transaction . See Getting Related Resources |
Response
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Check Payment | CheckPayment resource. |
included | Array of DepositAccount or Customer or Transaction | Array of resources requested by the include query parameter. |
curl -X GET 'https://api.s.unit.sh/check-payments/100' \
-H "Authorization: Bearer ${TOKEN}"
List
List check payments resources. Filtering, paging and sorting can be applied.
Verb | GET |
Url | https://api.s.unit.sh/check-payments |
Required Scope | check-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[tags] | Tags (JSON) | (empty) | Optional. Filter check 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. |
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][] | string | (empty) | Optional. Filter by status (New , Pending , Canceled ,Rejected , InDelivery , InProduction ,Delivered , ReturnedToSender , Pending , Processed , PendingReview ,MarkedForReturn , Returned , `). Usage example: filter[status][0]=Processed |
filter[fromAmount] | Integer | (empty) | Optional. Filters the Check 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 Check Payment that have an amount that is lower or equal to the specified amount (in cents). e.g. 7000 |
filter[checkNumber] | String | (empty) | Optional. Filter Check Payments by check number (trimming leading zeros). |
include | string | (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/check-payments?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"
Response
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Array of Check Payment | Array of check 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). |
{
"data": [
{
"type": "checkPayment",
"id": "1",
"attributes": {
"createdAt": "2023-02-21T00:3:03.704Z",
"updatedAt": "2023-02-21T00:31:03.704Z",
"amount": 10000,
"sendAt": "2023-02-21T12:50:00.704Z",
"description": "Check Payment | 0322",
"status": "Processed",
"deliveryStatus": "Delivered",
"trackedAt": "2023-02-23T11:31:03.704Z",
"postalCode": "94303",
"checkNumber": "0322",
"onUsAuxiliary": "0322",
"onUs": "864800000002/",
"counterparty": {
"name": "John Doe",
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303"
}
},
"counterpartyRoutingNumber": "051402372",
"returnCutoffTime": "2023-03-23T15:50:00.000Z",
"additionalVerificationStatus": "Required"
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "10002"
}
},
"customer": {
"data": {
"type": "customer",
"id": "10005"
}
},
"customers": {
"data": [
{
"type": "customer",
"id": "10001"
}
]
}
}
},
{
"type": "checkPayment",
"id": "3",
"attributes": {
"createdAt": "2023-02-22T00:31:03.704Z",
"updatedAt": "2023-03-22T00:39:03.704Z",
"amount": 10000,
"sendAt": "2023-02-22T12:50:00.704Z",
"description": "Check Payment | 0323",
"status": "Processed",
"deliveryStatus": "Delivered",
"trackedAt": "2023-02-24T11:31:03.704Z",
"postalCode": "94303",
"checkNumber": "0322",
"onUsAuxiliary": "0322",
"onUs": "864800000002/",
"counterparty": {
"name": "John Doe",
"address": {
"street": "5230 Newell Rd",
"city": "Palo Alto",
"state": "CA",
"postalCode": "94303"
}
},
"counterpartyRoutingNumber": "051402372",
"returnCutoffTime": "2023-03-22T12:50:00.000Z",
"additionalVerificationStatus": "Required"
},
"relationships": {
"account": {
"data": {
"type": "account",
"id": "10002"
}
},
"customer": {
"data": {
"type": "customer",
"id": "10005"
}
},
"customers": {
"data": [
{
"type": "customer",
"id": "10001"
}
]
},
"transaction": {
"data": {
"type": "transaction",
"id": "7"
}
}
}
}
]
}
Get front image by Id
Get a check payment front image by check payment id.
Verb | GET |
Url | https://api.s.unit.sh/check-payments/{id}/front |
Required Scope | check-payments |
Timeout (Seconds) | 5 |
Response
Response is an IMAGE:PNG file.
200 OK / 302 Found
Client should support following redirects
curl -X GET 'https://api.s.unit.sh/check-payments/100/front' \
-H "Authorization: Bearer ${TOKEN}"
Get back image by Id
Get a check payment back image by check payment ID.
Verb | GET |
Url | https://api.s.unit.sh/check-payments/{id}/back |
Required Scope | check-payments |
Timeout (Seconds) | 5 |
Response
Response is an IMAGE:PNG file.
200 OK / 302 Found
Client should support following redirects
curl -X GET 'https://api.s.unit.sh/check-payments/100/back' \
-H "Authorization: Bearer ${TOKEN}"
Return Check Payment
Create a return as long as it happens before the returnCutoffTime
, the Check Payment status will be set to MarkedForReturn
. A CheckPayment.markedForReturn event is raised when the request is completed successfully.
If the Check Payment was Processed
, a Returned Check Payment Transaction will be created.
Verb | POST |
Url | https://api.s.unit.sh/check-payments/:checkPaymentId/return |
Required Scope | check-payments-write |
Data Type | checkPaymentReturn |
Timeout (Seconds) | 5 |
Attributes
Name | Type | Description |
---|---|---|
reason | string | The reason for returning the Check Payment. See valid reasons for Check Payment returns list. |
Response
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Check Payment | CheckPayment resource. |
curl -X POST 'https://api.s.unit.sh/check-payments/1000/return'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "checkPaymentReturn",
"attributes": {
"reason": "StopPayment"
}
}
}'
Approve Check Payment Additional Verification
Needs to be used when additionalVerificationStatus
is Required
in order to approve the Check Payment. When additional verification is required a CheckPayment.additionalVerificationRequired event will be raised
Serves as an evidence that an additional verification was performed and an approval was captured from the end customer to continue processing this Check Payment.
The additionalVerificationStatus
will be changed to Approved
and a CheckPayment.additionalVerificationApproved event is raised when the call was successful.
If approval is not received by the time we reach the ReturnCutoffTime
and the additionalVerificationStatus
is Required
the Check Payment will be automatically returned.
If the additional verification was performed and the end customer did not approve the Check Payment, you should use the Return Check Payment Endpoint.
Verb | POST |
Url | https://api.s.unit.sh/check-payments/:checkPaymentId/approve |
Required Scope | check-payments-write |
Data Type | additionalVerification |
Timeout (Seconds) | 5 |
Response
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Check Payment | CheckPayment resource. |
curl -X POST 'https://api.s.unit.sh/check-payments/1000/approve'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "additionalVerification"
}
}'
Cancel Check Payment
Cancels a previously processed check payment. Only check payments in status Pending
can be canceled. If cancelation was successful, the check status will change to Canceled
and a checkPayment.canceled will be fired.
Verb | POST |
Url | https://api.s.unit.sh/check-payments/{checkPaymentId}/cancel |
Required Scope | check-payments-write |
Timeout (Seconds) | 5 |
Response
Response is a JSON:API document.
200 OK
Field | Type | Description |
---|---|---|
data | Check Payment | The canceled payment. |
curl -X POST 'https://api.s.unit.sh/check-payments/63261/cancel' \
-H "Authorization: Bearer ${TOKEN}"