Guide: How to Create, Print and Mail Checks with Custom HTML Attachments
Welcome! This guide will show you how to create checks with custom HTML attachments (like paystubs, invoices, or receipts) and then either print them or mail them physically through our service.
Two Workflows Available:
- Path 1: Create + Print - Create a check with HTML stub, then download a printable PDF with your custom attachment
- Path 2: Create + Mail (All-in-One) - Create and physically mail a check with HTML stub attachment in a single API call
Important: About Sandbox vs Production
This article uses the Sandbox environment for all examples and testing. The Sandbox allows you to test the complete workflow without processing real payments or mailing actual documents.
Ready for Production? When you're ready to go live, simply switch to the production environment:
Prerequisites: Developer Panel Setup
Before making any API requests, you need to obtain your API key from the Developer Panel.
Task 1: Get Your API Key
Navigate to the Developer Panel and locate your API Key:
- Go to Sandbox Developer Panel:
https://test.onlinecheckwriter.com/manage/developer/index - Click on the "API Settings" tab
- Your API Key will be displayed (hidden with dots for security)
- Click the eye icon to reveal it, or click the copy icon to copy it directly
- Save this key securely - you'll need it for every API request
Security Warning: Keep your API key secure and never share it publicly. If you generate a new API key, your current key will be automatically revoked.
The Mandatory Step: Set Your Connection Headers
Before making any request, you must add these 3 headers in your API tool (like Postman). Without these, our system cannot verify your account:
- Content-Type:
application/json - Accept:
application/json - Authorization:
Bearer YOUR_API_TOKEN_HERE (Use the API key you copied from the Developer Panel)
Step 1: Get Your Bank Account ID
You need a unique identifier for your bank account. This tells the system which account the funds are coming from. Note: Unlike the regular check creation process, you do not need a payee ID for this workflow - you'll provide the recipient's information directly in the request body.
ENDPOINT (GET)
RESPONSE EXAMPLE
{
"success": true,
"data": {
"meta": {
"total": 3,
"currentPage": 1,
"perPage": 10
},
"bankAccounts": [
{
"bankAccountId": "O7rWQ8Gpny7NjD0ZzpM",
"name": "AB COMPANY API Updated",
"nickName": "API Updated Test Account",
"accountNumber": "8425122",
"isVerified": true,
"bankId": "v1byeVNZ1leOQgr",
"addressLine1": "111 North Hill Street API Updated",
"city": "Los Angeles",
"state": "CA",
"zip": "90012"
}
]
}
}
Action: Copy the bankAccountId value. You'll use this in the next steps.
Path 1: Create Check + Print with HTML Attachment
This workflow allows you to create a check with a custom HTML stub attachment and download a printable PDF. Perfect for self-printing or record-keeping.
Step 2A: Create Check with HTML Stub
Create a check record in the system with your custom HTML content embedded. The HTML stub can be a paystub, invoice, receipt, or any formatted document.
About the HTML Stub:
The htmlStub field accepts a complete HTML document as a string. You can include:
- Inline CSS styles
- Google Fonts or external fonts
- Tables, divs, and formatted content
- Custom layouts and designs
Important: All HTML must be properly escaped (quotes as \") to be valid JSON.
ENDPOINT (POST)
REQUEST BODY (JSON)
{
"source": {
"accountType": "bankaccount",
"accountId": "O7rWQ8Gpny7NjD0ZzpM"
},
"destination": {
"name": "John Myres",
"company": "Tyler Payment Technologist",
"address1": "5007 richmond rd",
"address2": "",
"city": "Tyler",
"state": "TX",
"zip": "75701",
"phone": "9032457713",
"email": "
support@onlinecheckwriter.com"
},
"payment_details": {
"amount": 90.3,
"memo": "for game",
"note": "Note For Internal Purpose",
"referenceID": "12",
"issueDate": "2024-07-01",
"htmlStub": "...YOUR HTML CONTENT HERE..."
}
}
RESPONSE EXAMPLE
{
"success": true,
"message": "Successfully Sent",
"data": {
"checkId": "0Kmz473QVR4LOM2"
}
}
Action: Copy the checkId from the response. You'll need this to print the check in the next step.
Step 3A: Print Check with HTML Attachment
Now that your check is created, request a printable PDF that includes both the check and your HTML stub attachment.
ENDPOINT (POST)
REQUEST BODY (JSON)
{
"paperType": 1,
"checkId": ["0Kmz473QVR4LOM2"]
}
RESPONSE EXAMPLE
Success! The response contains a direct download link to your PDF. This PDF includes both the check and your HTML stub attachment. The link is valid for 5 minutes.
Paper Type Options:
- 1 - Standard white paper (8.5" x 11")
- 2 - Check paper (pre-printed check stock)
Path 2: Create and Mail Check with HTML Attachment (All-in-One)
This workflow allows you to create a check with HTML stub and physically mail it in a single API call. Our facility will print and mail the check with your custom attachment.
Step 2B: Get Mailing Options
Before mailing, you need to choose a shipping method and paper quality. This endpoint shows all available options with their costs.
ENDPOINT (GET)
RESPONSE EXAMPLE (PARTIAL)
{
"success": true,
"data": {
"shippingTypes": [
{
"shippingTypeId": 1,
"name": "First Class",
"amount": "1.25"
},
{
"shippingTypeId": 3,
"name": "First Class with Tracking 7.50",
"amount": "7.50"
},
{
"shippingTypeId": 4,
"name": "Priority Mail USPS 12.99",
"amount": "12.99"
},
{
"shippingTypeId": 12,
"name": "Fedex Overnight 03.30 PM Standard",
"amount": "31.99"
}
],
"paperTypes": [
{
"paperTypeId": 7,
"name": "Regular Check Paper",
"amount": "0.00"
},
{
"paperTypeId": 8,
"name": "Hollogram Check Paper",
"amount": "0.50"
},
{
"paperTypeId": 9,
"name": "Ultra Hollogram Check Paper",
"amount": "0.99"
}
],
"attachment": [
{
"informTypeId": 19,
"name": "Attachment",
"amount": "1.00"
}
]
}
}
Action: Choose a shippingTypeId for your mailing needs. The attachment fee ($1.00) is automatically added when you include an HTML stub.
Step 3B: Create and Mail Check with HTML Stub
This single endpoint creates the check and sends it to our mailing facility. The check will be printed with your HTML stub attachment and physically mailed to the recipient.
Important: Make sure the recipient's address is complete and accurate. Once submitted, the mailing process cannot be reversed.
ENDPOINT (POST)
REQUEST BODY (JSON)
{
"source": {
"accountType": "bankaccount",
"accountId": "O7rWQ8Gpny7NjD0ZzpM"
},
"destination": {
"name": "John Myres",
"company": "Tyler Payment Technologist",
"address1": "5007 richmond rd",
"address2": "",
"city": "Tyler",
"state": "TX",
"zip": "75701",
"phone": "9032457713",
"email": "
support@onlinecheckwriter.com",
"shippingTypeId": 1
},
"payment_details": {
"amount": 984,
"memo": "for game",
"note": "Note For Internal Purpose",
"issueDate": "2024-07-01",
"htmlStub": "...YOUR HTML CONTENT HERE..."
}
}
RESPONSE EXAMPLE
{
"success": true,
"message": "Successfully Sent",
"data": {
"checkId": "LRko4zvARn4bY7y"
}
}
Done! Our facility has received your check and will begin processing. The check with your HTML stub attachment will be printed and mailed to the recipient.
Step 4: Check the Status of Your Check
After creating or mailing your check, you can track its status using the check ID. This endpoint provides detailed information about the check's current state and history.
ENDPOINT (GET)
RESPONSE EXAMPLE
{
"success": true,
"data": {
"checkId": "LRko4zvARn4bY7y",
"serialNumber": "91006",
"amount": "984.00",
"amountInWord": " nine hundred eighty four ",
"date": "2024-07-01",
"status": 4,
"memo": "for game",
"bankAccount": {
"bankAccountId": "rWQ8Gpny7NjD0Zz",
"name": "AB COMPANY API Updated"
},
"payee": {
"payeeId": "7rLdjv37qQ4JEz6",
"name": "John Myres"
},
"checkStatus": {
"status": 4,
"description": "Printing",
"shippingTypeId": 3,
"shippingTypeName": "First Class with Tracking 7.50",
"trackingNumber": null
},
"checkStatements": [
{
"status": "printing",
"date": "01/23/2026",
"time": "11:38 am"
},
{
"status": "created",
"date": "01/23/2026",
"time": "11:38 am"
}
]
}
}
The response includes the current status, shipping details (if mailed), and a complete history timeline in the checkStatements array.
Check Status Code Reference
Here are all possible status codes you may receive when checking your check status:
| Status Code | Description | Meaning |
|---|
| 0 | Created | Check has been created but not yet processed |
| 1 | Printed | Check has been marked as printed (self-print or print-to-PDF) |
| 2 | Void | Check has been voided and cannot be used |
| 4 | Printing | Check is being processed for physical mailing (print facility) |
| 7 | Mailed | Check has been physically mailed via postal service |
| 11 | Refunded | Mailing fee has been refunded |
| 500 | Emailed | Check has been sent via email |
| 501 | Emailed and Viewed | Email check has been opened by recipient |
| 504 | Emailed and Tried to Print | Recipient attempted to print the emailed check |
| 505 | Emailed and Printed | Recipient successfully printed the emailed check |
| 807 | Mailed and Voided | Check was mailed but has been voided afterward |
Common HTTP Status Codes
When making API requests, you may encounter these HTTP status codes:
| Status Code | Description |
|---|
| 200 | Success - Request completed successfully |
| 201 | Created - Resource created successfully |
| 400 | Bad Request - Invalid request format or missing required fields |
| 401 | Unauthorized - Invalid or missing API key |
| 404 | Not Found - Requested resource doesn't exist |
| 422 | Unprocessable Entity - Request validation failed |
| 500 | Server Error - Internal server error occurred |
Summary
You've learned how to create checks with custom HTML attachments using two different workflows:
Quick Workflow Reference:
For Printing (Path 1):
- Get Bank Account ID
- Create check with HTML stub →
/quickpay/check - Print check with attachment →
/checks/print-with-attachment
For Mailing (Path 2):
- Get Bank Account ID
- Get Mailing Options →
/mailchecks/mailingOptions - Create and mail check →
/quickpay/mailcheck
Need Help?
If you have questions or need assistance with the API: