APIs

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`

Suggestion

Check payment origination is not supported for joint or Org accounts.

Suggestion

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

amount

integer

The amount (in cents). Must be less than 100000000000

memoOptional

string

Optional. Check payment memo. This will be printed on the check (maximum of 40 characters)

sendDateOptional

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.

tagsOptional

object

Optional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).

Relationships

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

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

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.

Suggestion

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

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

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

When a Check Payment requires additional verification, its additionalVerificationStatus will be set to Required. In this case, a CheckPayment.additionalVerificationRequired event will be triggered.

To proceed with the Check Payment, you must obtain approval from the end customer and confirm it by calling the Approve Check Payment Additional Verification endpoint or, for users with sufficient permissions, directly through the dashboard. This action serves as evidence that the required verification was completed and that the customer authorized the Check Payment to continue.

Once the approval is successfully submitted, the additionalVerificationStatus will be updated to Approved, and a CheckPayment.additionalVerificationApproved event will be triggered.

If the Additional Verification was performed but the end customer did not approve the Check Payment, you should return the payment using the Return Check Payment endpoint.

Note

If additionalVerificationStatus is Required, the approval must be completed (via API or dashboard) before the returnCutoffTime, which occurs at 11:50 AM ET on the next calendar day. If not completed in time, the Check Payment will be automatically returned.

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

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

data

Check Payment

The canceled payment.

curl -X POST 'https://api.s.unit.sh/check-payments/63261/cancel'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'

Originate Check Payment (Mail Physical Check)​

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​

Originate Check Payment (Mail Physical Check)

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