Skip to main content

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.

note

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:

StatusDescription
NewA request to originate a check payment has been registered and is being processed.
RejectedSee rejectReason for further details. The most common reason for a check payment to be rejected is an unsuccessful validation of the counterparty's address.
PendingThe check payment is pending submission and will be sent to the printers at the next cutoff time.
CanceledThe originated check payment was canceled. This can only be done while check payment is in Pending status, and cannot be undone.
PendingCancellationa 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)
InProductionCutoff time has passed. The check payment has been sent to the printers and can no longer be updated or canceled.
InDeliveryThe check payment has been accepted by the mail service and is en route. see deliveryStatus for further tracking information.
DeliveredThe check payment was delivered.
ReturnedToSenderThe check payment could not be delivered and has been returned to the sender.
PendingReviewThe check payment is pending review by Unit.
ProcessedThe check payment was processed and the deposit account was debited.
MarkedForReturnThe 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.
ReturnedThe 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

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 ReasonDescription
NotSufficientFundsAccount has insufficient funds
UncollectedFundsHoldFunds are present in the account but are on hold
StopPaymentA matching Stop Payment request was identified and a Check Payment was returned
ClosedAccountAccount is closed
UnableToLocateAccountMatching account not found
FrozenOrBlockedAccountAccount is Frozen or Check Payment is not enabled for client or Check Payment not enabled on Deposit Product
StaleDatedThe date on the check is too far in the past
PostDatedThe date on the check is in the future
NotValidCheckOrCashItemThe item is not a valid check
AlteredOrFictitiousThe check has been altered or tampered with (e.g. the amount or recipient has been changed)
UnableToProcessThe check cannot be processed (e.g. information may be missing from the check)
ItemExceedsDollarLimitDaily and/or monthly Check Payment limits have been crossed
NotAuthorizedThe check is not authorized (e.g. a fake check)
ReferToMaker
UnusableImageThe check image quality is poor, unusable, or has multiple checks included
DuplicatePresentmentThe 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.

info

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 StatusDescription
MailedThe check has been handed off to and accepted by the mail service.
InLocalAreaThe check payment is being processed at the destination facility. . This is the final delivery status for checks sent to P.O boxes.
DeliveredThe check payment has been delivered to its destination.
ReroutedThe check payment has been re-routed.
ReturnedToSenderThe 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

VerbPOST
Urlhttps://api.s.unit.sh/check-payments
Required Scopecheck-payments-write
Data TypecheckPayment
Timeout (Seconds)5
info

Check payment origination is not supported for joint accounts.

info

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

NameTypeDescription
amountintegerThe amount (in cents). Must be less than 100000000000
memostringOptional. Check payment memo. This will be printed on the check (maximum of 40 characters)
sendDateRFC3339 Date stringOptional. Date only (e.g. 2022-06-23). The date the check should be sent at. Up to 180 days in the future. If left null or in the past, will default to today.
counterpartyCounterpartyThe payee's details . street and street2 combined may contain up to 50 characters. country must be "US".
DescriptionstringAn internal description (maximum of 255 characters). This will not be printed on the check.
idempotencyKeystringSee Idempotency.
tagsobjectOptional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).

Relationships

NameTypeDescription
accountJSON:API RelationshipThe Deposit Account originating the payment.
customerJSON:API RelationshipLink to the customer the the check will be signed by.
Example Request:
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.

Example Response:
{
"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.

VerbGET
Urlhttps://api.s.unit.sh/check-payments/{id}
Required Scopecheck-payments
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
dataCheck PaymentCheckPayment resource.
includedArray of DepositAccount or Customer or TransactionArray 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.

VerbGET
Urlhttps://api.s.unit.sh/check-payments
Required Scopecheck-payments
Timeout (Seconds)5

Query Parameters

NameTypeDefaultDescription
page[limit]integer100Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]integer0Number 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.
sortstringsort=-createdAtOptional. 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).
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/check-payments?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataArray of Check PaymentArray of check 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 (total items).
Example Response:
{
"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.

VerbGET
Urlhttps://api.s.unit.sh/check-payments/{id}/front
Required Scopecheck-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.

VerbGET
Urlhttps://api.s.unit.sh/check-payments/{id}/back
Required Scopecheck-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 returnCuttoffTime, the Check Payment status will be set to MarkedForReturn. A CheckPayment.markedForReturn event is raised when the request is completed successfully.

info

If the Check Payment was Processed, a Returned Check Payment Transaction will be created.

VerbPOST
Urlhttps://api.s.unit.sh/check-payments/:checkPaymentId/return
Required Scopecheck-payments-write
Data TypecheckPaymentReturn
Timeout (Seconds)5

Attributes

NameTypeDescription
reasonstringThe reason for returning the Check Payment. See valid reasons for Check Payment returns list.

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataCheck PaymentCheckPayment 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.

note

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.

VerbPOST
Urlhttps://api.s.unit.sh/check-payments/:checkPaymentId/approve
Required Scopecheck-payments-write
Data TypeadditionalVerification
Timeout (Seconds)5

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataCheck PaymentCheckPayment 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.

VerbPOST
Urlhttps://api.s.unit.sh/check-payments/{checkPaymentId}/cancel
Required Scopecheck-payments-write
Timeout (Seconds)5

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataCheck PaymentThe canceled payment.
curl -X POST 'https://api.s.unit.sh/check-payments/63261/cancel' \
-H "Authorization: Bearer ${TOKEN}"