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:

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

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.

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 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

Verb	`POST`
Url	`https://api.s.unit.sh/check-payments`
Required Scope	`check-payments-write`
Data Type	`checkPayment`
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

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 should be sent at. 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.

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.

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 (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.

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.

info

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.

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.

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}"

Overview

Check Payment Statuses​

Check Payment Return Reasons​

Check Payment Delivery Status​

Originate Check Payment​

Attributes​

Relationships​

Response​

Get by Id​

Query Parameters​

Response​

200 OK​

List​

Query Parameters​

Response​

200 OK​

Get front image by Id​

Response​

200 OK / 302 Found​

Get back image by Id​

Response​

200 OK / 302 Found​

Return Check Payment​

Attributes​

Response​

200 OK​

Approve Check Payment Additional Verification​

Response​

200 OK​

Cancel Check Payment​

Response​

200 OK​

Check Payment Statuses

Check Payment Return Reasons

Check Payment Delivery Status

Originate Check Payment

Attributes

Relationships

Response

Get by Id

Query Parameters

Response

200 OK

List

Query Parameters

Response

200 OK

Get front image by Id

Response

200 OK / 302 Found

Get back image by Id

Response

200 OK / 302 Found

Return Check Payment

Attributes

Response

200 OK

Approve Check Payment Additional Verification

Response

200 OK

Cancel Check Payment

Response

200 OK