Check Payment

Subscribers can enable their systems to let account holders send payments by check. Checks are funded by a FinancialAccount. Checks greater than $2,000 USD must have a signature of the Primary Authorized Person linked to the FinancialAccount.

Only checks greater than or equal to $2,000 require a signature.

Signatures must be saved in PNG or JPG format and attached to a FinancialAccount. High-level steps are:

1. Create a check payment upload session to attach the signature to a FinancialAccount.
2. Upload the signature to Highnote with either the Document Upload SDK or the Highnote GraphQL API.

To begin, create a check payment document upload session to associate a signature with a FinancialAccount.

Next, upload the signature to Hignote. Signatures can be uploaded to Highnote one of two ways:

• The Document Upload SDK lets users upload their own signature file.
• The Highnote GraphQL API can upload a signature if the file is already present.

If you use the Highnote GraphQL API, the document upload process consists of the following steps:

1. Optional - Generate a client token.
2. Start a document upload session to Highnote
3. Create a document upload link
4. Upload the signature with the upload link.
5. End the document upload session

Note: For compliance reasons, you must generate a client token to make requests directly from your client if you are not using a server or do not have access to one. See Client Tokens.

The Start mutation generates a session URL. Upload sessions expire 30 days from creation; and each session notifies you of any requirements your system needs to enforce to upload the file.

Use the following mutation to start a document upload session:

Note: Document upload links expire 5 minutes after creation. If the link expires, an error message is returned, and you must request a new link.

Each upload link created with this mutation represents a single upload file. If, for example, you are required to upload two signature files, you must create a unique link for each.

When creating upload links, the document upload session status transitions to PENDING. You can use the uploadURL field in the mutation's response to stream the document upload.

To create a document upload link, use the DOCUMENT_UPLOAD_SESSION_ID from the startDocumentUploadSession response for this mutation’s variable field:

After the signature has been uploaded, you can end the document upload session. When ending a session, the session status transitions to SUBMITTED and no other actions can be taken. If more documentation is required, a new session must be started to upload the additional documents.

Use the following mutation to end a document upload session:

Refer to the check image below to see how physical check items map to API fields.

To begin a check payment, call the initiatePhysicalCheckPayment mutation using a sufficiently funded FinancialAccount and a recipient’s name and an address (ideally, a validatedAddressTokenId).

Address Validation

Before initiating a check payment, Highnote recommends that you utilize the Address Validation service (below) to ensure the recipient’s address is correctly formatted and verified.

Steps are:

1. Call validateAddress to check if the check payment address is valid.
2. From the response, copy validatedAddressTokenId representing the validated address.
3. Call InitiatePhysicalCheckPayment with the response token Id.

Shipping Method

You can specify the type of check and the shipping method when initiating a check payment. The check funding process takes 2-3 business days to complete, in addition to the stated mailing times.

The following shipping methods are supported:

You can validate the check payment address using the validateAddress mutation. This mutation validates addresses using a CASS-certified service to ensure it is properly formatted to reduce possible shipping delays or returns.

The Highnote API returns an AddressValidationResult response with a validated address token, or an error message explaining why the address is invalid.

Use the following mutation to initiate a check payment with a validatedAddressTokenId:

While not recommended, you can use the following mutation to initiate a check payment with an unvalidated address.

To use a validated address instead, see Initiate physical check payment with validated address token (above).

Payments made by check follow an event lifecycle with the possible types outlined below. Your platform receives a notification event as each check payment transitions to a new type.

The Highnote transaction event and notification event for all check payment types is the CheckPaymentEvent.

Use the following mutations to query for one check payment or list multiple check payments.

Use the node query to query for a CheckPayment.

Use the FinancialAccount.checkPayments query to return a list of CheckPayments. The query can return all check-related fields including the check image.

The following image maps API fields to the physical check:

1. Business account holder legalBusinessName or Personal account holder familyName and givenName
2. amount : InitiatePhysicalCheckPaymentInput
3. recipient : InitiatePhysicalCheckPaymentInput
4. memo : InitiatePhysicalCheckPaymentInput
5. Uploaded signature