Send Paper Check Payment

📘

API Refs

• Production: Send Paper Check
• Staging: Send Paper Check

Request body

Response body

Example

1. Get list of insured's addresses Request with userId = 1;
2. Get list of insured's addresses Response:
   JSON

   [
     {
       "address1": "11 Birch Hill Street",
       "address2": "Apt. 123",
       "city": "Bronx",
       "postalCode": "10023",
       "state": "NY",
       "phone": "123-456-7890",
       "alias": "Home"
     }
   ]

3. Send Paper Check Transfer Request:
   JSON

   {
     "recipientEmail": "[email protected]",
     "amount": 12.34,
     "memo": "Test memo",
     "alias": "Home",
     "mailType": "Mail",
     "attachments": [
       {
         "fileName": "claim-letter.pdf",
         "content": "JVBERi0xLjQKJ..."
       }
     ]
   }

4. Send Paper Check Transfer Response:
   JSON

   {
     "id": 1,
     "transactionId": "a444aa44-aaa4-4a4a-aaaa-a44a44444a44",
     "amount": 12.34,
     "createdAt": "2023-08-09T15:00:00.000Z",
     "customerId": 1,
     "customerName": "John Smith",
     "merchantName": "Jake Merchant",
     "fee": "9.00",
     "feeDeductFrom": "sender",
     "status": "Preparing to mail",
     "type": "Paper Check: USPS First-Class (3-5 days)",
     "memo": "Test memo",
     "attachments": [
       {
         "id": 45,
         "fileName": "claim-letter.pdf",
         "size": 48213,
         "downloadUrl": "/api/public/payments/1/attachments/45"
       }
     ]
   }

Description

❗️

You can send Paper check transfers only for your insureds. If you want to send Paper check transfer for non insured, go to Send pending payment

📘

Where to get insured's email?

You can get list of all created insureds. Go to Get list of all insureds

📘

Where to get address alias

You can get all existing addresses with their alias for any you insured. Go to Get list of insured's addresses for more information about it.

When accepting a pending payment as a paper check, you must always indicate the alias of the address of the insured to whom the paper check will be sent.

If the transaction is successfully created, the pending payment status will change to Preparing to mail.

Such a payment has the following statuses:

• Preparing to mail;
• Mailing soon;
• Rejected;
• Resubmitted: Preparing to mail again;
• Canceled;
• Mailed.

Attachments

You can include up to 5 PDFs with a paper check. They're printed and mailed in the same envelope as the check, after the check page. Each file must be a readable PDF of 5 MB or less, and the file name must end in .pdf.

If any attachment can't be prepared for mailing, the whole request fails with a 400 and no check is sent. Nothing is charged, so you can fix the file and send the request again.

The response and Get payment by Id list the stored files under attachments. To download one, call its downloadUrl with the same Authorization header you use for other requests.

Response codes

Error response body

All error responses return the following structure:

{
    "statusCode": 403,
    "code": "PAYMENT_4033",
    "message": "Check payments are not configured for this account",
    "timestamp": "2026-03-06T00:00:00.000Z",
    "path": "/api/public/payments/send-check"
}

Validation error (400)

  {
    "statusCode": 400,
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "timestamp": "2026-03-06T00:00:00.000Z",
    "path": "/api/public/payments/send-check",
    "errors": [
      {
        "field": "mailType",
        "message": "mailType must be one of: FedEx, Mail, USPSFirst, USPSTrack"
      }
    ]
  }

Attachment error (400)

When a file passes validation but can't be mailed, message names the file and what to fix:

  {
    "statusCode": 400,
    "code": "ERROR",
    "message": "claim-letter.pdf is larger than 5 MB",
    "timestamp": "2026-03-06T00:00:00.000Z",
    "path": "/api/public/payments/send-check"
  }

Provider error (502)

When Checkflo returns an error processing the check:

  {
    "statusCode": 502,
    "code": "PAYMENT_5021",
    "message": "Failed to send check",
    "timestamp": "2026-03-06T00:00:00.000Z",
    "path": "/api/public/payments/send-check",
    "provider": {
      "provider": "checkflo",
      "providerCode": "5",
      "providerMessage": "Failed to send check"
    }
  }