Mailing Checks with PDF Attachments via OCW API

Guide: How to Mail Checks with PDF Attachments

Welcome! This simplified guide will walk you through the complete workflow: from creating a check record with advanced details to physically mailing it with a PDF attachment (like an invoice or receipt).

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.

Sandbox Base URL: https://test.onlinecheckwriter.com/api/v3
Sandbox Developer Panel: https://test.onlinecheckwriter.com/manage/developer/index

Ready for Production? When you're ready to go live, simply switch to the production environment:

Production Base URL: https://app.onlinecheckwriter.com/api/v3
Production Developer Panel: https://app.onlinecheckwriter.com/manage/developer/index

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 from the Developer Panel).

Step 1: Find Your Bank Account ID

You need a unique code for your bank account to tell the system where the funds are coming from.

ENDPOINT (GET)

https://test.onlinecheckwriter.com/api/v3/bankAccounts

RESPONSE EXAMPLE

{
  "success": true,
  "data": {
    "bankAccounts": [{
      "bankAccountId": "yd6LeMYmdQeE8Dx",
      "name": "Business Checking"
    }]
  }
}

Action: Copy the bankAccountId value for Step 3.

Step 2: Find Your Payee ID

This is the unique code for the person or company you are paying.

ENDPOINT (GET)

https://test.onlinecheckwriter.com/api/v3/payees

RESPONSE EXAMPLE

{
  "success": true,
  "data": {
    "payees": [{
      "payeeId": "Xw2lx48MdGMzWyD",
      "name": "Jane Doe"
    }]
  }
}

Action: Copy the payeeId for the next step.

Step 3: Create the Check Record (Advanced)

Create the check in our database. You can include advanced details like memos, serial numbers, or payment vouchers.

ENDPOINT (POST)

https://test.onlinecheckwriter.com/api/v3/checks

REQUEST BODY (JSON)

{
  "checks": [
    {
      "bankAccountId": "yd6LeMYmdQeE8Dx",
      "payeeId": "Xw2lx48MdGMzWyD",
      "amount": 100.00,
      "memo": "Invoice Payment",
      "serialNumber": "1001",
      "note": "Internal reference only",
      "accountNumber": "458756",
      "invoiceNumber": "2545",
      "voucher": {
        "voucherNumber": "1000",
        "memo": "Payment breakdown",
        "date": "2026-01-20",
        "voucherItems": [
          {
            "invoiceNumber": 858,
            "name": "Professional Services",
            "total": 100.00
          }
        ]
      }
    }
  ]
}

RESPONSE EXAMPLE

{
  "success": true,
  "data": {
    "checks": [{
      "checkId": "RJ6qGAm5lJGE1rD"
    }]
  }
}

Action: Copy the checkId. You must have this to attach your PDF in the next step.

Step 4: Attach Your PDF Document

Now, link your PDF document (like an invoice) to the check you just created.

How to upload your file:

In your API tool, change the Body format to form-data.
In the KEY column, type exactly: attachment.
Change the Key type from Text to File (check the dropdown menu).
Click 'Select Files' and pick your PDF.

ENDPOINT (POST)

https://test.onlinecheckwriter.com/api/v3/mailchecks/RJ6qGAm5lJGE1rD/attachments

RESPONSE EXAMPLE

{
  "success": false,
  "message": "Succesfully added",
  "data": {
    "mailAttachmentId": "OJapb4kkA4Y1Ewm"
  }
}

Step 5: Choose Your Shipping & Paper Quality

Use this request to see every available mailing option and paper type. You must pick one ID from each category for the final step.

ENDPOINT (GET)

https://test.onlinecheckwriter.com/api/v3/mailchecks/mailingOptions

FULL LIST OF OPTIONS (RESPONSE DATA)

{
  "success": true,
  "data": {
    "shippingTypes": [
      { "shippingTypeId": 1, "name": "First Class" },
      { "shippingTypeId": 3, "name": "First Class with Tracking" },
      { "shippingTypeId": 4, "name": "Priority Mail" },
      { "shippingTypeId": 5, "name": "Express Mail" },
      { "shippingTypeId": 11, "name": "Fedex 2 days Shipping" },
      { "shippingTypeId": 12, "name": "Fedex Standard Overnight" }
    ],
    "paperTypes": [
      { "paperTypeId": 7, "name": "Regular Check Paper" },
      { "paperTypeId": 8, "name": "Hollogram Check Paper" },
      { "paperTypeId": 9, "name": "Ultra Hollogram Check Paper" }
    ]
  }
}

Step 6: Trigger the Physical Mailing

The final step! This tells our facility to print and mail the check and attachment.

ENDPOINT (POST)

https://test.onlinecheckwriter.com/api/v3/mailchecks

REQUEST BODY (JSON)

{
  "mailChecks": [{
    "checkId": "RJ6qGAm5lJGE1rD",
    "shippingTypeId": 3,
    "paperTypeId": 7
  }]
}

RESPONSE EXAMPLE

{
  "success": true,
  "message": "successfully mailed"
}

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)

https://test.onlinecheckwriter.com/api/v3/checks/LRko4zvARn4bY7y

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

Done! Our facility has received your order and will begin processing the physical delivery.