Batch

Upload a CSV of transactions and let the gateway process them asynchronously. Download the results when the batch completes.

The batch endpoints let you upload a CSV file of transactions, check on processing status, and download a results CSV once the batch completes. Typical uses are nightly billing runs, migrating historical data, and any bulk charge that does not warrant individual API calls.

Request format

The uploaded file must meet these rules:

The first row is a header with the field names below. Columns can be in any order, and only some are required.
Each value is wrapped in double quotes. Values themselves must not contain quotes.
Fields are separated by commas.
Each row ends with a newline (\n).

"transaction_type","amount","cc_number","cc_expiration"
"sale","100","4111111111111111","12/25"

A sample CSV is available at batch_example.csv.

Building the CSV in a spreadsheet

When creating the file in Excel or Numbers you do not need to type the double quotes yourself — the export will add them. You may, however, need to force numeric cells to text format so that leading zeros and long card numbers survive the export. Save the file as CSV.

Valid fields

Field	Required	Description
`transaction_type`	required	One of `sale`, `authorize`, `credit`.
`cc_number`	required for card	Card number, digits only.
`cc_expiration`	required for card	Expiration date, `MM/YY`.
`cc_cvc`	optional	CVC — required only if your account enforces it.
`ach_account_number`	required for ACH	Bank account number.
`ach_routing_number`	required for ACH	Bank routing number.
`ach_account_type`	required for ACH	`checking` or `savings`.
`ach_sec_code`	required for ACH	SEC code: `WEB`, `CCD`, or `PPD`.
`customer_id`	required if vaulted	Customer vault ID to charge.
`payment_method_type`	optional	`card` or `ach`, when pairing with `payment_method_id`.
`payment_method_id`	optional	The specific vault payment method to charge.
`amount`	required	Amount in cents. $1.00 is `100`.
`base_amount`	optional	Alternative to `amount`. The gateway adds surcharge and tax to this value before processing.
`surcharge`	optional	Surcharge amount in cents — included in `amount`.
`shipping_amount`	optional	Shipping amount, included in `amount`.
`tax_amount`	optional	Tax amount, included in `amount`.
`discount_amount`	optional	Discount amount, included in `amount`.
`surcharge_exempt`	optional	`true` or `false`. Exempt this row from any configured surcharge.
`order_id`	optional	Up to 17 alphanumeric characters.
`description`	optional	Up to 100 alphanumeric characters.
`po_number`	optional	Up to 17 alphanumeric characters.
`tax_exempt`	optional	`true` or `false`. Default `false`.
`email_address`	optional	Tagged onto the transaction. No email is sent automatically.
`email_receipt`	optional	`true` or `false` — sends a receipt if `true`.
`processor_id`	optional	Override your default processor for this row.
`billing_*`	optional	Billing address fields: `first_name`, `last_name`, `company`, `address_line_1`, `address_line_2`, `city`, `state`, `postal_code`, `country`, `phone`, `fax`, `email`.
`shipping_*`	optional	Shipping address fields — same shape as billing.

Response format

The downloaded results file is also CSV, with one row per input transaction. Columns include the basics (id, amount, status), the billing/shipping that was sent in, and processor-side details like response_code, processor_response_code, processor_response_text, auth_code, avs_response_code, and cvv_response_code.

Endpoints

Upload a file

POST /api/filebatch

curl -v \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@<FILENAME>" \
  "https://sandbox.fluidpay.com/api/filebatch"

Response:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "bj1o70m9ku6fr2s21fig",
    "file_name": "testfile.csv",
    "status": "pending",
    "num_lines": 1,
    "created_at": "2019-04-26T22:17:38.078185288Z",
    "updated_at": "2019-04-26T22:17:38.078185288Z"
  }
}

JavaScript example:

function uploadFile() {
  const headers = new Headers();
  headers.append("Authorization", apiKey);

  const formData = new FormData();
  formData.append("file", "testBatch.csv");

  fetch("https://sandbox.fluidpay.com/api/filebatch", {
    method: "POST",
    headers,
    body: formData,
    redirect: "follow"
  })
    .then(r => r.json())
    .then(result => {
      if (result.status === "success") {
        const batchId = result.data.id;
        // ...
      }
    })
    .catch(err => console.log("error", err));
}

Check batch status

GET /api/filebatch/{batch_id}

curl -v \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  "https://sandbox.fluidpay.com/api/filebatch/<batch_id>"

{
  "id": "bj1o70m9ku6fr2s21fig",
  "user_id": "bj1o70m9ku6fr2s21fig",
  "file_name": "testfile.csv",
  "status": "pending",
  "num_lines": 1,
  "processed_lines": 1,
  "created_at": "2019-04-26T22:17:38.078185288Z",
  "updated_at": "2019-04-26T22:17:38.078185288Z"
}

status is one of unknown, pending, queued, processing, failed, completed.

Download the results

GET /api/filebatch/{batch_id}/download

10-day retention

Only batches with status completed can be downloaded, and results expire after ten days.

curl -v \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  "https://sandbox.fluidpay.com/api/filebatch/<batch_id>/download"

On success, the response streams the results CSV. On failure you'll get a JSON error:

{
  "status": "failed",
  "msg": "batch is not in completed status",
  "data": null
}