Checkissuing API Documentation

Upload Payments

You can use this API method to upload a payment file containing multiple payments.

You POST the file as you would a standard HTTP POST file upload, as if it were posted via an html form with an enctype of multipart/form-data and a FILE input type field.

Files are in a CSV format and must contain headers that match our payment field's keys as the first line.

Sandbox Endpoint

Parameters

Parameter	Type	Required	Default	Description
paymentscsv	File	Yes	N/A	The csv file to upload, uploaded as a standard HTTP POST file upload
funding_source_id	Int	Conditional	N/A	The id of the bank account/funding source the payments in this file should be drawn on. Required unless every payment row specifies its own funding source within the file (rows may each name a different funding source). When provided, it is used for any row that does not name one. Every payment must resolve to a valid funding source or the file cannot be confirmed.
upld_ins	File	No	N/A	Either a single PDF file or a zip file of PDF files. Used to bulk add inserts to the payments in the file. If a single PDF is uploaded it is applied to all payments in the file, if a zip file is provided payments are matched to inserts using the 'Insert' column in the file which should contain the appropriate PDF's filename
upld_ins_opts	Str	No	N/A	A string specifying print options for inserts uploaded along w/ the payment file. Possible values are: bw_simplex, bw_duplex, color_simplex, color_duplex. This tells us to print them in black and white or color and simplex or duplex accordingly.
return_envelope_id	Int	No	No return envelope	The return envelope to include with each payment in the file. The id of an active, client-owned return envelope. Omit, pass null, or pass 0 for no return envelope. A per-row `return_envelope_id` column in the CSV overrides this global value.
format_id	Int	No	N/A	Used to specify the format of a file if needed. Only required when the format cannot be auto detected (file does not have headers or headers do not match fields). Currently these formats are created using the 'Upload Payments' functionality in the client portal.
ignore_file_confirmation	Bool	No	true	Controls the guard that blocks a new upload when the funding source still has a previously uploaded file that has not yet been confirmed or discarded. Defaults to `true`, which bypasses that requirement and uploads the new file anyway, leaving the earlier file pending. Send a falsey value (`0`, `false`, `no`, or `off`) to enforce the guard and reject the upload while an unresolved file exists.

Upload failure semantics

Insert ZIP preflight is atomic. Archive save, safe-extraction, empty-archive, and PDF validation failures use top-level status: 0 and errors; file and file_id are null, payments is empty, and no payments or inserts from that request are retained. CSV-to-ZIP filename association is checked after the CSV batch is staged, so a missing row filename also returns top-level status: 0 and creates no payments or inserts, but may return the staged file/file_id batch metadata.

After preflight succeeds, validation problems produced while creating an individual payment are recorded under file.errors, keyed by payment id. Those row-level errors do not become top-level upload errors: the created payment remains in payments and top-level status can still be 1. Integrations must inspect both top-level errors and file.errors.

Sample Response

{
          "status": 1,
          "errors": [],
          "error_message": "",
          "file": {
              "id": "2317",
              "client_id": "337",
              "user_id": "411",
              "account_id": "205",
              "logo_id": null,
              "insert_id": null,
              "uploaded_ts": "2022-01-30 21:07:35",
              "processed_ts": "2022-01-30 20:07:35",
              "confirmed_ts": null,
              "orig_fname": "testpayments.csv",
              "num_payments": "2",
              "payment_total": "1.50",
              "errors": [],
              "processed": "1",
              "confirmed": "0",
              "payment_ids": [
                  "480774",
                  "480775"
              ]
          },
          "file_id": "2317",
          "payments": {
              "480774": {
                  "id": "480774",
                  "client_id": "337",
                  "user_id": "411",
                  "account_id": "205",
                  "file_id": "2317",
                  "status_id": "1",
                  "postage_id": "1",
                  "payee_name": "Example Recipient",
                  "payee_address": "1600 Amphitheatre Pkwy|Mountain View, CA 94043",
                  "amount": "1.00",
                  "metadata": [],
                  "return_envelope_id": null,
                  "mail_class": null,
                  "mail_class_reason": null,
                  "sheet_count": null,
                  "check_sheet_count": 0,
                  "insert_sheet_count": 0,
                  "computed_weight_oz": null,
                  "large_envelope": 0
              }
          }
      }

Mail Profile Response Fields