Overview

The Check Payment resource represents a check written by a customer that has been deposited in a bank and received by Unit for cashing.

This resource becomes available either when a check payment is originated through the Unit API or after a check is written using Unit Deposit Account details (routing number and account number), deposited at a bank, and then received by Unit. Once a Check Payment is successfully processed (status: Processed ), 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 (Mail Physical Check)

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

info

Check payment origination is not supported for joint or Org 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 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.

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