Payment Imports

A payment import turns a spreadsheet into payments in one batch. You upload the file, Payment Labs validates every row and tells you what each row will do, and you then decide whether to create the payments. Use an import when the payouts already live in a spreadsheet; when your system creates payments one by one, call Create Payment instead.

Before you start

• You have a batch. The batch supplies the default payment category and tax jurisdiction for rows that leave them empty.
• Imports need the Write permission; reading them needs any payout role.
• The payments an import creates are DRAFT. Finishing an import does not submit them.

The file format

• CSV (text/csv) or Excel .xlsx (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet). Only the first sheet of an Excel file is read.
• One header row, then one row per payment. Rows above the header are ignored: the header is the first row that contains both an email column and an amount column. You can keep instructions or comments above it.
• Header names must be spelled exactly as listed below (letter case included). Spaces around them are ignored. Columns with other names are ignored.

If you connected QuickBooks or Xero, the import also accepts their classification columns, which are passed to that integration:

A minimal CSV:

Email Address,Amount,Payee Reference ID,Payment Reference ID,Payee Message
[email protected],250.00,user-1001,invoice-4471,October royalties
[email protected],1200.50,user-1002,invoice-4472,October royalties

The Payment Labs dashboard offers the same template for download from the batch import screen.

Step 1: Create the import

curl -X POST https://api-sandbox.paymentlabs.io/batches/B-01JDA1B2C3D4E5F6G7H8J9K0M1/imports \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "fileName": "october-royalties.csv", "fileMimeType": "text/csv" }'

Create Import returns 201:

{
  "importId": "I-01JDA5E6F7G8H9J0K1M2N3P4Q5",
  "fileUploadUrl": "https://..."
}

The import is created. Both fields are required, and fileMimeType must be one of the two types above.

Step 2: Upload the file

Send the file with an HTTP PUT to fileUploadUrl. Do not add your Authorization header: the URL carries its own signature.

curl -X PUT "$FILE_UPLOAD_URL" \
  -H "Content-Type: text/csv" \
  --data-binary @october-royalties.csv

The upload URL is valid for one hour. An import whose file is never uploaded is removed after a few hours.

Step 3: Wait for validation

Payment Labs starts reading the file as soon as it arrives. Poll Get Import every few seconds until status is no longer processing:

entries on the import counts rows: total, validated (rows checked so far, valid or not), failed, and processed once finishing has created payments.

To list every import of a batch, call Get Batch Imports.

Step 4: Review the rows

Get Import Rows returns the rows, 100 per page by default. When the response has nextPage, pass it as exclusiveStartId to read the next page; it is absent on the last page. totalCount is the number of rows in the file.

{
  "totalCount": 2,
  "currentCount": 2,
  "items": [
    {
      "importId": "I-01JDA5E6F7G8H9J0K1M2N3P4Q5",
      "batchId": "B-01JDA1B2C3D4E5F6G7H8J9K0M1",
      "paymentId": "P-01JDA6F7G8H9J0K1M2N3P4Q5R6",
      "payeeEmail": "[email protected]",
      "payeeReferenceId": "user-1001",
      "amount": { "value": 250, "currency": "USD", "formattedValue": "$250.00", "digits": 2, "wholeValue": 25000 },
      "valid": true,
      "userAction": "NO_CHANGE"
    },
    {
      "importId": "I-01JDA5E6F7G8H9J0K1M2N3P4Q5",
      "batchId": "B-01JDA1B2C3D4E5F6G7H8J9K0M1",
      "payeeEmail": "kenji.mori@example",
      "valid": false,
      "error": { "payeeEmail": [{ "code": "INVALID_EMAIL", "message": "..." }] }
    }
  ]
}

• valid tells you whether the row will become a payment.
• error maps each field to the problems found in it.
• userAction tells you what the row does to the payee: NO_CHANGE, NEW_PAYEE, EMAIL_CHANGED or REFERENCE_CHANGED. Check every EMAIL_CHANGED and REFERENCE_CHANGED row before you finish; see Payee Reference IDs.
• paymentId is the ID the payment will have once it is created.
• expenseAccountName, className and locationName repeat the QuickBooks category, class and location you wrote in the row, as typed. A name your QuickBooks company does not have is reported under the same key in error, but the row stays valid: the payment is created and you can classify it later.

Common row errors: a missing or invalid email or amount, an Account that is not one of your ledger accounts (or is missing when you have several), a jurisdiction or category that is unknown or not enabled, a payee email and reference ID that belong to different payees, and the same reference ID used with two different emails in the file (INCONSISTENT_REFERENCE_ID).

Step 5: Finish the import

Finish Import creates the payments. It returns 202 and the import moves to finishing, then finished.

{ "errorHandling": "importValid" }

The new payments are DRAFT. Submit them like any other payment, for example all at once with Submit Batch. See Creating and Submitting Payments.

Delete an import

Delete Import discards an import that has not been finished: one in created, ready, processed_with_errors or processing_failed. It returns 204. It creates and deletes no payments.

Errors and edge cases

Next steps

• Creating and Submitting Payments
• Payment Statuses