Skip to content

Check Printing

This service offers check printing services.

Endpoint or Section Action
/check/print Create a check to be printed
/check/get/:checkId Get the details of a specified check
Possible cFiCheckStatus Values Description of possible cFiCheckStatus values
/check/query Query details of up to 20 checks
/check/void Request to void an existing check
/check/list List checks by search criteria
Webhooks Information about optional webhookUrls

Request method and URL

POST /check/print

Description

This endpoint creates a check to be printed. The check details are stored in the connectFi database and then sent to the bank to be printed. The /check/print endpoint supports idempotency and will not accept requests with duplicate reference IDs.

The check is printed on a standard trifold check stock and mailed via USPS_FirstClass in a #10 double pane envelope. Checks are typically delivered within 7-10 days of mailing. The SLA on checks being mailed is 2 business days.

A dynamic logo can be added to the top left corner of the check (the URL link to the image would need to be included in the request using the "logo" property.)

The /check/print endpoint supports idempotency and will not accept requests with duplicate reference IDs. The external reference ID included in the request body is how connectFi controls for duplicate check-printing requests. It is important to note that checks submitted with unique reference IDs will not be considered duplicates, even if there are other properties with identical values. For example, the following requests are not considered duplicates even though they refer to the same check data. 

{
    "reference": "EXT_REFERENCE_ID1", //Different reference IDS
    "checkAttributes": {
        "amount": 11.13, //same amount
        "returnAddress": { //same return address details
            "addressLine1": "Platform Name, ATTN: Employee",
            "addressLine2": "100 Unicorn St",
            "addressLine3": "San Francisco, CA 12345"
        },
        "payerName": "Jim Payer", //same
        "payerAddress": { //same payer address details
            "addressLine1": "3700 Loon Rd",
            "city": "Minneapolis",
            "state": "MN",
            "postalCode": "12345-1234"
        },
        "payeeName": "ABC123abc Energy", //same
        "payeeAddress": { //same payee address details
            "addressLine1": "123 Some Road",
            "city": "Minneapolis",
            "state": "MN",
            "postalCode": "12345"
        },
        "platformNumber": "+1 (555) 666-7777", //same
        "memo": "Both of these checks will print with two separate serial numbers"
    },
    "webhookUrl": "https://webhookexample.testsite/9ec56257-5190-40a5-abc3-43f757b1234abc"
}
{
    "reference": "EXT_REFERENCE_ID2", //Different reference IDS
    "checkAttributes": {
        "amount": 11.13, //same amount
        "returnAddress": {
            //same return address details
        },
        "payerName": "Jim Payer", //same
        "payerAddress": {
            //same payer address details
        },
        "payeeName": "ABC123abc Energy", //same
        "payeeAddress": {
            //same payee address details
        },
        "platformNumber": "+1 (555) 666-7777", //same
        "memo": "Both of these checks will print with two separate serial numbers"
    },
    "webhookUrl": "https://webhookexample.testsite/9ec56257-5190-40a5-abc3-43f757b1234abc"
}
Required Properties Description Schema Example Values
reference An external reference in your system (1-32 alphanumeric characters) string, regex pattern: "^[0-9a-zA-Z_]+$" "extChkRef274"
checkAttributes An object containing all of the applicable check attributes object see checkAttributes Object below
Optional Properties Description Schema Example Values
webhookUrl URL which will be called after the check request. If you specify a webhookUrl in the /check/print request, the system will perform a callback to your webhookUrl every time the check status changes. Refer to Webhooks for the callback format. string "http://somewebhook.something/something?asd=123"

checkAttributes Object

Required Properties Description Schema Example Values
amount The requested check amount number > 0 11.13
currency A three character ISO alphabetic code to identify the currency string, regex pattern: "^[A-Z]{3}$" "USD"
returnAddress An object containing the return address object see returnAddress Object below
payerName Name of the payer (1-50 characters) string "Jim Payer"
payerAddress An object containing the payer address object see address Object below
payeeName Name of the payee (1-50 characters) string "Xcel Energy"
payeeAddress An object containing the payee address object see address Object below
platformNumber Platform Company's customer service telephone number (1-50 characters) string "+1 (234) 567-8901"
Optional Properties Description Schema Example Values
memo Check memo (1-45 characters) string "Check for electricity payment"
logo URL to image file – leave blank if no logo image should be printed. For best results, use .png format. Alternative logo formats include .jpg and .tiff (1-500 characters) string "http://link_to_logo_image.com"
attachmentCount The number of attachments included in the attachments array number 1
attachments An array of URL(s) to image file(s) such as a pack list. Leave blank if no attachments are needed. string "http://link_to_attachment_image.com"

returnAddress Object

Required Properties Description Schema Example Values
addressLine1 Line 1 of the return address (1-50 characters) string "Platform Name, ATTN: Employee"
Optional Properties Description Schema Example Values
addressLine2 Line 2 of the return address, do not include if not applicable (1-50 characters) string "100 Unicorn St"
addressLine3 Line 3 of the return address, do not include if not applicable (1-50 characters) string "San Francisco, CA 12345"

address Object

Required Properties Description Schema Example Values
addressLine1 Line 1 of the address (1-50 characters) string "3700 Loon Rd"
city City of addressee (1-50 characters) string "Minneapolis"
state State of addressee (1-50 characters) string "MN"
postalCode Postal code of addressee (1-10 digits) string "12345"
Optional Properties Description Schema Example Values
addressLine2 Line 2 of the address, do not include if not applicable (1-50 characters) string "Suite ABC123"
addressLine3 Line 3 of the address, do not include if not applicable (1-50 characters) string "c/o John Testman"

Request headers

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body example 

{
    "reference": "extChkRef274", //external reference ID
    "checkAttributes": {
        "amount": 11.13,
        "currency": "USD",
        "returnAddress": {
            "addressLine1": "Platform Name, ATTN: Employee",
            "addressLine2": "100 Unicorn St",
            "addressLine3": "San Francisco, CA 12345"
        },
        "payerName": "Jim Payer",
        "payerAddress": {
            "addressLine1": "3700 Loon Rd",
            "city": "Minneapolis",
            "state": "MN",
            "postalCode": "12345"
        },
        "payeeName": "Xcel Energy",
        "payeeAddress": {
            "addressLine1": "414 Nicollet Mall",
            "city": "Minneapolis",
            "state": "MN",
            "postalCode": "12345"
        },
        "platformNumber": "+1 (234) 567-8901",
        "memo": "Electricity payment"
    },
    "webhookUrl": "https://webhook.site/9ec56257-5190-40a5-abc3-43f757b6430f"
}

Possible responses

200 (HTTP response status code) -- Request to print check is accepted. A connectFi ID is assigned to the check.

{
    "code": "0", //Success
    "data": {
        "cFiCheckId": "chk_5x4Sr0qO9R7hXIYIjw4ylG", //check ID in connectFi
        "reference": "extChkRef453", //external reference ID in your system
        "serial": "102", //serial number of the check (assigned by Paygears)
        "amount": 11.13,
        "currency": "USD",
        "cFiAggregatorId": "evolve", //platform aggregator ID in connectFi
        "cFiCheckStatus": "Processing", //current status of the check in connectFi
        "initVoid": false, //true if a request to void the check has been initialized
        "webhookUrl": "https://webhook.site/9ec56257-5190-40a5-abc3-43f757b6430f",
        "dtsCreatedAt": "2023-04-05T19:18:56.471Z"
    },
    "requestId": "b5bacb10d3e611edae63c5641e0050b8"
}

400 (HTTP response status code) -- Reference already exists

In this example, a request was attempted with a reference ID that is already associated with an existing check. You cannot have duplicate reference IDs.

{
    "requestId": "4c7fcc306f7311ee8ff83020a7305d12",
    "code": "referenceExists",
    "context": {
        "entityId": "chk_77xNPblShEOAPiAY09y2Do",
        "reference": "extChkRef599"
    },
    "message": "Reference already exists."
}

400 (HTTP response status code) -- Must have required property 'reference'

In this example, a required property was not included in the request.

{
    "requestId": "5d0b2e006f7311ee8ff83020a7305d12",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/required",
            "keyword": "required",
            "params": {
                "missingProperty": "reference"
            },
            "message": "must have required property 'reference'"
        }
    ]
}

400 (HTTP response status code) -- Character limit was exceeded for a property

{
    "requestId": "3e7fea70d3e711edae63c5641e0050b8",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "/checkAttributes/payeeAddress/postalCode",
            "schemaPath": "#/properties/postalCode/maxLength",
            "keyword": "maxLength",
            "params": {
                "limit": 10
            },
            "message": "must NOT have more than 10 characters"
        }
    ]
}

400 (HTTP response status code) -- Aggregator doesn't have settlementAccountForCheckPrint attribute.

{
    "requestId": "13851b0020af11eea8ea56da8a866870",
    "code": "checkSettlementAccountForCheckPrint",
    "context": {
        "cFiAggregatorId": "evolve"
    },
    "message": "Aggregator doesn't have settlementAccountForCheckPrint attribute."
}

Back to Top

Get Check

Request method and URL

GET /check/get/:checkId

Description

A request to this endpoint retrieves the details of a specified check. The cFiCheckId of the desired check should be passed as a path parameter.

Request headers

{
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body None

Possible responses

200 (HTTP response status code) -- Success, the details of the specified check are returned

{
    "code": "0", //Success
    "data": {
        "cFiCheckId": "chk_5x4Sr0qO9R7hXIYIjw4ylG", //check ID in connectFi
        "reference": "extChkRef453", //external reference ID
        "serial": "102", //serial number of the check
        "amount": 11.13,
        "currency": "USD",
        "cFiAggregatorId": "evolve", //Platform/Aggregator ID in connectFi
        "cFiCheckStatus": "Processing", //current check status in connectFi
        "initVoid": false, //true if a request to void the check has been initialized and immediate cancellation was not possible (request to print was already sent to bank and request to void must also be sent to bank)
        "voidReason": "Lost the check",
        "webhookUrl": "https://webhook.site/9ec56257-5190-40a5-abc3-43f757b6430f",
        "dtsCancelled": "2023-07-11T18:38:35.145Z",
        "dtsCreatedAt": "2023-04-05T19:18:56.471Z"
    },
    "requestId": "7e9455b0d3e711edae63c5641e0050b8"
}

Back to Top

Possible cFiCheckStatus Values

cFiCheckStatus (connectFi Status) Meaning
Processing A request to print the check has been initialized and is processing.
Sent The file containing the check requests (prints and voids) has been sent to the bank.
Complete The bank received the request to print the check and it has been printed and/or sent to automail.
Cancelled The check was cancelled (voided). If a check is voided before the original request is sent to the bank, then the status will automatically update to "Cancelled" and will not be sent to the bank or the check printer. If the check is voided after the original request to print is sent to the bank, then the status will not update to "Cancelled" until confirmation is received from the bank that the voided check was successfully cancelled.
Declined The check was rejected by automail.
InBank The bank has received the check request.
Unknown The bank returned an unknown status that must be manually reviewed. Contact support.
boStatus (Back Office Status) Meaning
Rejected by AutoMail There was an issue with the check, such as address, city, or state does not match
Cancelled Check request was sent to the bank, but user decided they do not want it to be sent out (voided after bank received check request)
Sent to AutoMail The check has been sent to the check printer
Printed The check printer has printed the check
Not Printed The check has been sent to the check printer, but has not been printed
Received Check printer has received the check data, still pending printing

Back to Top

Void a Check

Request method and URL

POST /check/void

Description

Requests to the /check/void endpoint will update the status of the check in the connectFi database and will send a notification to the bank that the specified check has been voided.

If the check is voided before the original request is sent to the bank, the cFiCheckStatus will update to "Cancelled" and will not be sent to the bank for printing. If the original request to print the check has already been sent to the bank, then the check will be printed, mailed, and delivered as usual. However, when the check is presented for payment, the bank will see the status of the check as voided. Therefore, no payment will be issued for the voided check.

Required Properties Description Schema Example Values
cFiCheckId The check ID in connectFi string "chk_43NVpa5x9qTmW0GOyLMScQ"
Optional Properties Description Schema Example Values
reason The reason why the check is being voided string "The check was lost."

Request headers

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body example

{
    "cFiCheckId": "chk_43NVpa5x9qTmW0GOyLMScQ", //check ID in connectFi
    "reason": "Lost the check"
}

Possible responses

200 (HTTP response status code) -- Success, the void has started processing

{
    "code": "0", //Success
    "data": {
        "cFiCheckId": "chk_4Hu9AA89hIDNfJhgvbQAfM", //check ID in connectFi
        "reference": "extChkRef443", //external reference ID in your system
        "serial": "8", //serial number of the check
        "cFiAggregatorId": "evolve", //Platform/Aggregator ID in connectFi
        "cFiCheckStatus": "InBank", //current check status in connectFi
        "cFiVoidStatus": "Processing", //current status of the void request in connectFi
        "boStatus": "Sent to Automail", //current check status in the back office
        "boStatusDate": "2023-3-31T15:48:46.1133333",
        "boDatePrinted": "2023-3-31T00:00:00", //date that the check was printed
        "boTracking": "64165468656789", //back office tracking number
        "initVoid": true, //true if a request to void the check has been initialized
        "voidReason": "Lost the check", //description of the reason the check is to be voided
        "dtsSent": "2023-03-31T18:50:34.202Z",
        "dtsVoidInitiated": "2023-04-03T16:53:48.670Z",
        "dtsCreatedAt": "2023-03-31T18:48:18.900Z"
    },
    "requestId": "1aba99d0d24011eda20e29883d152412"
}

200 (HTTP response status code) -- Success, the check was cancelled before it was sent to the bank

{
    "code": "0", //Success
    "data": {
        "cFiCheckId": "chk_5x4Sr0qO9R7hXIYIjw4ylG", //check ID in connectFi
        "reference": "extChkRef453", //external reference ID in your system
        "serial": "102", //serial number of the check
        "amount": 11.13,
        "currency": "USD",
        "cFiAggregatorId": "evolve", //Platform/Aggregator ID in connectFi
        "cFiCheckStatus": "Cancelled", //current check status in connectFi
        "initVoid": false, //check was cancelled (voided) before sending to bank so void request to bank is not required
        "voidReason": "Lost the check", //description of the reason the check is to be voided
        "webhookUrl": "https://webhook.site/9ec56257-5190-40a5-abc3-43f757b6430f",
        "dtsCancelled": "2023-04-05T19:44:13.174Z",
        "dtsCreatedAt": "2023-04-05T19:18:56.471Z"
    },
    "requestId": "3dd6aac0d3ea11edae63c5641e0050b8"
}

400 (HTTP response status code) -- Duplicate Void Error

This check was already voided. The current status of the check will be included with the error message.

{
    "requestId": "64b970906f7711ee8ff83020a7305d12",
    "code": "duplicateVoidError",
    "context": {
        "cFiCheckId": "chk_3cjSsIGwCA0kLComplete2",
        "cFiCheckStatus": "Complete",
        "cFiVoidStatus": "Processing"
    },
    "message": "Request to void or cancel check has already been initiated."
}

400 (HTTP response status code) -- Cannot be voided due to current cFiCheckStatus

In this example, the check was cancelled in a previous request before sending to bank. Check can only be voided if the current cFiCheckStatus is "Sent", "InBank", "Complete", or "Processing".

{
    "requestId": "19dc8da06f7711ee8ff83020a7305d12",
    "code": "cannotVoidError",
    "context": {
        "cFiCheckStatus": "Cancelled"
    },
    "message": "Сan not void."
}

400 (HTTP response status code) -- Missing required property

{
    "requestId": "799a22c06f7711ee8ff83020a7305d12",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/required",
            "keyword": "required",
            "params": {
                "missingProperty": "cFiCheckId"
            },
            "message": "must have required property 'cFiCheckId'"
        }
    ]
}

400 (HTTP response status code) -- Check not found

{
    "requestId": "8d0c50d06f7711ee8ff83020a7305d12",
    "code": "checkNotFound",
    "context": {
        "cFiCheckId": "chk_3cjSsIGwCA0kLe2"
    },
    "message": "Check not found."
}

Back to Top

Query Check Status

Request method and URL

POST /check/query

Description

The status of up to 20 checks may be requested at a time (either using the "references" array or the "cFiCheckIds" array, but not both). The array that you include may not be an empty array.

The system will return only the checks it could locate. Unknown IDs will be ignored and if no IDs are recognized, an empty array is returned with success code "0".

If the same ID is requested multiple times in the "сFiCheckIds" or "references" array, the response will only return one object in the data array corresponding to that ID, regardless of how many times it was listed in the request array.

If more than 20 elements are listed in the request array (either "сFiCheckIds" array or the "references" array), an error will be thrown even if the IDs are not unique. For example, if the cFiCheckId "chk_DdwNMecgMe96AW0xRNOBO" is listed 21 times in the request array, the request will fail even though technically only one unique ID was requested.

Either "cFiCheckIds": [...] should be used or "references": [...], but not both. You cannot combine both types of IDs into a single request.

Required Properties Description Schema Example Values
cFiCheckIds Array of check IDs from the connectFi system obtained when each check was initialized Array ["chk_DdwNMecgMe96AW0xRNOBO", "chk_1wwKuQ5x8Z0UqEUZYAFa76", ...]

OR

Required Properties Description Schema Example Values
references Array of external IDs from your system that you entered when initializing the checks Array ["extChkRef287", "extChkRef286", ...]

Request headers

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body examples

Request body (using connectFi check IDs):

{
    "cFiCheckIds": ["chk_DdwNMecgMe96AW0xRNOBO", "chk_1wwKuQ5x8Z0UqEUZYAFa76"]
}

Request body (using external system references):

{
    "references": ["extChkRef287", "extChkRef286"]
}

Possible responses

200 (HTTP response status code) -- Success, check statuses are returned

Both request body examples above will return the same two check entities, although not necessarily in the same order. 

{
    "code": "0", //Success
    "data": [
        {
            "cFiCheckId": "chk_1wwKuQ5x8Z0UqEUZYAFa76", //check ID in connectFi
            "reference": "extChkRef287", //external reference ID
            "serial": "12", //check serial number generated by PayGears
            "amount": 11.13,
            "currency": "USD",
            "cFiAggregatorId": "evolve", //Platform/Aggregator ID in connectFi
            "cFiCheckStatus": "Sent", //current status of check
            "initVoid": false, //true if a request to void the check has been initialized and immediate cancellation was not possible (request to print was already sent to bank and request to void must also be sent to bank)
            "webhookUrl": "https://webhook.site/9ec56257-5190-40a5-abc3-43f757b6430f",
            "dtsSent": "2023-02-15T18:05:10.085Z",
            "dtsCreatedAt": "2023-02-15T18:04:31.245Z",
        },
        {
            "cFiCheckId": "chk_DdwNMecgMe96AW0xRNOBO", //check ID in connectFi
            "reference": "extChkRef286", //external reference ID
            "serial": "11", //check serial number generated by PayGears
            "amount": 9.43,
            "currency": "USD",
            "cFiAggregatorId": "evolve", //Platform/Aggregator ID in connectFi
            "cFiCheckStatus": "Cancelled", //current status of check
            "cFiVoidStatus": "Sent", //current status of the void request in connectFi
            "initVoid": true, //true if a request to void the check has been initialized and immediate cancellation was not possible (request to print was already sent to bank and request to void must also be sent to bank)
            "voidReason": "Lost the check", //description of the reason the check is to be voided      
            "webhookUrl": "https://webhook.site/9ec56257-5190-40a5-abc3-43f757b6430f",
            "dtsSent": "2023-03-31T18:50:34.202Z",
            "dtsVoidInitiated": "2023-04-03T16:53:48.670Z",
            "dtsCreatedAt": "2023-02-15T17:49:23.075Z",
        }
    ],
    "requestId": "b2f63e1020ac11eea5dd56da8a86665c"
}

200 (HTTP response status code) -- Success, сFiCheckIds/references requested do not exist

In this example, the request was successful but the requested check IDs do not exist in connectFi.

{
    "code": "0",
    "data": [],
    "requestId": "2375fc7020ad11eea5dd56da8a86665c"
}

400 (HTTP response status code) -- The check filter cannot have both references and cFiCheckIds.

In this example, the references array property and the cFiCheckIds array property were both included. Only one of these properties is allowed in a single query request. 

{
    "requestId": "e2e6032020ad11eea5dd56da8a86665c",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/oneOf/0/additionalProperties",
            "keyword": "additionalProperties",
            "params": {
                "additionalProperty": "references"
            },
            "message": "must NOT have additional properties"
        },
        {
            "instancePath": "",
            "schemaPath": "#/oneOf/1/additionalProperties",
            "keyword": "additionalProperties",
            "params": {
                "additionalProperty": "cFiCheckIds"
            },
            "message": "must NOT have additional properties"
        },
        {
            "instancePath": "",
            "schemaPath": "#/oneOf",
            "keyword": "oneOf",
            "params": {
                "passingSchemas": null
            },
            "message": "must match exactly one schema in oneOf"
        }
    ]
}

400 (HTTP response status code) -- Array ("references" or "cFiCheckIds") must NOT have fewer than 1 items

In this example, the references array property or the cFiCheckIds array property did not contain at least 1 ID. This error will be thrown if the ID array used (either references or cFiCheckIds) is empty. 

{
    "requestId": "c7f2b880d3f311edae63c5641e0050b8",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "/cFiCheckIds",
            "schemaPath": "#/oneOf/0/properties/cFiCheckIds/minItems",
            "keyword": "minItems",
            "params": {
                "limit": 1
            },
            "message": "must NOT have fewer than 1 items"
        },
        {
            "instancePath": "",
            "schemaPath": "#/oneOf/1/required",
            "keyword": "required",
            "params": {
                "missingProperty": "references"
            },
            "message": "must have required property 'references'"
        },
        {
            "instancePath": "",
            "schemaPath": "#/oneOf",
            "keyword": "oneOf",
            "params": {
                "passingSchemas": null
            },
            "message": "must match exactly one schema in oneOf"
        }
    ]
}

400 (HTTP response status code) -- Must not have fewer than 1 characters

In this example, the array included in the request body contained at least one empty string, "". Each cFiCheckId/reference ID must have between 1 and 32 characters.

{
    "requestId": "c7f2b880d3f311edae63c5641e0050b8",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "/cFiCheckIds/2",
            "schemaPath": "check-printing#/definitions/id/minLength",
            "keyword": "minLength",
            "params": {
                "limit": 1
            },
            "message": "must NOT have fewer than 1 characters"
        },
        {
            "instancePath": "",
            "schemaPath": "#/oneOf/1/required",
            "keyword": "required",
            "params": {
                "missingProperty": "references"
            },
            "message": "must have required property 'references'"
        },
        {
            "instancePath": "",
            "schemaPath": "#/oneOf",
            "keyword": "oneOf",
            "params": {
                "passingSchemas": null
            },
            "message": "must match exactly one schema in oneOf"
        }
    ]
}

400 (HTTP response status code) -- Must not have more than 20 items

In this example, more than 20 reference IDs were included in the "references" array property in the request body. You may not include more than 20 reference IDs or cFiCheckIds in a single request (even if they are not unique IDs). 

{
    "requestId": "c7f2b880d3f311edae63c5641e0050b8",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/oneOf/0/required",
            "keyword": "required",
            "params": {
                "missingProperty": "cFiCheckIds"
            },
            "message": "must have required property 'cFiCheckIds'"
        },
        {
            "instancePath": "/references",
            "schemaPath": "#/oneOf/1/properties/references/maxItems",
            "keyword": "maxItems",
            "params": {
                "limit": 20
            },
            "message": "must NOT have more than 20 items"
        },
        {
            "instancePath": "",
            "schemaPath": "#/oneOf",
            "keyword": "oneOf",
            "params": {
                "passingSchemas": null
            },
            "message": "must match exactly one schema in oneOf"
        }
    ]
}

Back to Top

List Checks

Request method and URL:

POST /check/list

Description:

This endpoint will list checks that match the desired search criteria. Search criteria may be a specific cFiCheckId, an array of cFiCheckIds, an external reference ID, a date range, a check status value, a void status value, or a combination of criteria. You may also specify a maximum number of records to return using the numberOfRecords property (up to 1000) and you may specify a number of records to skip using the skipRecords property. Combine the numberOfRecords property with the skipRecords property to make displaying transaction lists in batches easy. For example, if you want to list checks in batches of 150, you can set numberOfRecords to 150 and skipRecords to 0 in the first request. Then, increase skipRecords by 150 in each subsequent request to return the next batch and so on.

When making a request, if the number of checks matching the criteria is greater than the numberOfRecords maximum requested, the response body will indicate that there are additional checks ("more": true).

If no properties are included, an unfiltered check list will be returned (up to a maximum of 1000).

Optional Properties Description Schema Example Values
cFiCheckId Check ID from the connectFi system obtained when the check was initialized, nullable string, regex pattern: "^[0-9a-zA-Z_]+$" "evolve_13c261GGqsFL1yElgKBrnS"
cFiCheckIds An array of check IDs from the connectFi system obtained when the checks were initialized, nullable array ["evolve_13c261GGqsFL1yElgKBrnS", ... ]
reference The external reference for the check in your system (1-32 alphanumeric characters), nullable string, regex pattern: "^[0-9a-zA-Z]+$" "externalTrnId2314"
dateCreateFrom A beginning date in ISO Date format, if using a date range to list checks, nullable string "2023-05-10T12:46:31.578Z"
dateCreateTo An ending date in ISO Date format, if using a date range to list checks, nullable string "2023-05-13T12:46:31.578Z"
status The desired status for which to search, nullable string "Processing", "Sent", "Complete", "Cancelled", "Declined", "InBank", or "Unknown"
voidStatus The desired void status for which to search, nullable string "Processing", "Sent", or "Complete"
numberOfRecords The maximum number of desired records to return, nullable integer <=1000 850
skipRecords The number of records to skip when returning results, nullable integer 25

Request headers:

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body examples:

Request body (using connectFi check ID)

{
    "cFiCheckId": "evolve_13c261GGqsFL1yElgKBrnS"
}

Request body (using external system references)

{
    "reference": "extTrnBill218"
}

Request body (using a date range)

{
    "dateCreateFrom": "2023-05-01T14:27:33.684Z",
    "dateCreateTo": "2023-05-12T14:27:33.684Z"
}

Request body (using a combination of desired search criteria)

{
    "dateCreateFrom": "2023-04-01T14:27:33.684Z", //beginning of requested date range
    "dateCreateTo": "2023-06-24T18:57:25.957Z", //end of requested date range
    "status": "Initiated", //will only return transactions with an "Initiated" status
    "numberOfRecords": 15, //will return up to a maximum of 15 records
    "skipRecords": 1 //will skip the first transaction found
}

Possible responses:

200 (HTTP response status code) -- Success, Checks that meet the search criteria will be returned.

{
    "code": "0", //Success
    "data": {
        "total": {
            "skipRecords": 1,
            "numberOfRecords": 4,
            "more": true
        },
        "items": [
            {
                "cFiCheckId": "chk_42IH7umyXdBfU216Gtu2G4", //transaction ID in connectFi
                "reference": "extChkRef493", //external reference from your system
                "serial": "125",
                "cFiCheckStatus": "Processing", //current check status
                "amount": 11.13,
                "currency": "USD",
                "dtsCreatedAt": "2023-06-12T17:35:27.165Z"
            },
            {
                "cFiCheckId": "chk_7lJEriaC6sQcuKb8S8zFRK", //transaction ID in connectFi
                "reference": "extChkRef490", //external reference from your system
                "serial": "124",
                "cFiCheckStatus": "Processing", //current check status
                "amount": 11.13,
                "currency": "USD",
                "dtsCreatedAt": "2023-06-12T17:31:19.943Z"
            },
            {
                "cFiCheckId": "chk_74qX0bHGKfDDYxKl434vPG", //transaction ID in connectFi
                "reference": "extChkRef478", //external reference from your system
                "serial": "123",
                "cFiCheckStatus": "Processing", //current check status
                "amount": 11.13,
                "currency": "USD",
                "dtsCreatedAt": "2023-06-12T17:31:04.564Z"
            },
            {
                "cFiCheckId": "chk_7knJskC20piqs38IqSfCOU", //transaction ID in connectFi
                "reference": "extChkRef477", //external reference from your system
                "serial": "122",
                "cFiCheckStatus": "Processing", //current check status
                "amount": 11.13,
                "dtsCreatedAt": "2023-05-23T21:15:27.795Z"
            }
        ]
    },
    "requestId": "924954901f5311ee993f56da8a861940"
}

200 (HTTP response status code) -- Success, no checks that meet the search criteria were found.

Note: If the dateCreateTo date is before the dateCreateFrom date, you will receive the same response. Check to make sure the date range is valid if no checks meet your criteria when checks are expected.

{
    "code": "0",
    "data": {
        "total": {
            "skipRecords": 2,
            "numberOfRecords": 0,
            "more": false
        },
        "items": []
    },
    "requestId": "85f558b0f0e111ed9bc156da8a861818"
}

400 (HTTP response status code) -- numberOfRecords field greater than 1000

In this example, the number of maximum records requested was greater than 1000.

{
    "requestId": "b8e0350020a811eea8ea56da8a866870",
    "code": "greaterNumberOfRecords",
    "context": {
        "maxNumberOfRecords": 1000
    },
    "message": "The numberOfRecords field is greater than the request limit"
}

400 (HTTP response status code) -- Must be equal to one of the allowed values

In this example, an invalid status value was requested.

{
    "requestId": "e520a32020a811eea8ea56da8a866870",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "/status",
            "schemaPath": "#/properties/status/enum",
            "keyword": "enum",
            "params": {
                "allowedValues": [
                    "Processing",
                    "Sent",
                    "Complete",
                    "Cancelled",
                    "Declined",
                    "InBank",
                    "Unknown"
                ]
            },
            "message": "must be equal to one of the allowed values"
        }
    ]
}

Back to Top

Webhooks

Description

If you specify a webhook URL in the /check/print endpoint request, every time a check status changes, the system will make a single POST call to the specified URL with the following body:

Example 1

{
    "cFiCheckId": "chk_6VzsVo0j8JAC1JYTCZ2EN6", //check ID in connectFi
    "reference": "extChkRef459", //external reference ID
    "serial": "107", //Check serial number
    "amount": 11.13,
    "currency": "USD",
    "cFiAggregatorId": "evolve", //Platform/Aggregator ID in connectFi
    "cFiCheckStatus": "Sent", //current check status in connectFi
    "initVoid": false, //true if a request to void the check has been initialized and immediate cancellation was not possible (request to print was already sent to bank and request to void must also be sent to bank)
    "webhookUrl": "https://webhook.site/9ec56257-5190-40a5-abc3-43f757b6430f",
    "dtsSent": "2023-04-06T15:08:40.193Z", //date the check entity was sent to the bank
    "dtsCreatedAt": "2023-04-06T15:08:29.824Z" //date the check entity was created in the database
}

Example 2

{
    "cFiCheckId": "chk_4v9MPr1yHGQOFpPXtwIXUo", //check ID in connectFi
    "reference": "extChkRef455", //external reference ID
    "serial": "103", //Check serial number
    "amount": 11.13,
    "currency": "USD",
    "cFiAggregatorId": "evolve", //Platform/Aggregator ID in connectFi
    "cFiCheckStatus": "InBank", //current check status in connectFi
    "boStatus": "Received", //current check status in the back office
    "boStatusDate": "2023-3-31T15:48:46.1133333",
    "boDatePrinted": "2023-3-31T00:00:00", //date that the check was printed
    "boTracking": "8416846157", //back office tracking number
    "initVoid": false, //true if a request to void the check has been initialized and immediate cancellation was not possible (request to print was already sent to bank and request to void must also be sent to bank)
    "webhookUrl": "http://somewebhook.something/something?asd=123",
    "dtsSent": "2023-04-06T14:32:40.969Z", //date the check entity was sent to the bank
    "dtsCreatedAt": "2023-04-06T14:30:28.606Z" //date the check entity was created in the database
}

Back to Top