Overview

Batch upload is a service which allows you to upload a CSV (comma seperated values) file containing transactions to be processed. Each file is validated and queued for processing behind the scenes. Once completed, a batch can be download in CSV format containing the response of the transactions processed.

Request Format

Each file should meet the following requirements:

  • First row should be a header using the fields below, fields can be in any order and not all fields are required.
  • Each field should be wrapped in quotes and should not contain any quotes
  • Each field should be seperated with a comma
  • Each row should be terminated with a newline \n character.

Example:

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

Valid fields

Field Name Required Description
transaction_type Yes One of the following: sale/authorize/credit
cc_number Yes - if credit card CC Number
cc_expiration Yes - if credit card CC Expiration Date
cc_cvc No Optional unless your account requires CVC for processing
ach_account_number Yes - if ACH ACH account number
ach_routing_number Yes - if ACH ACH routing number
ach_account_type Yes - if ACH "checking" or "savings"
ach_sec_code Yes - if ACH SEC code: WEB/CCD/PPD
customer_id Yes if using customer vault customer vault id to charge
amount Yes Amount to process as integer. For example $1.00 should be 100
shipping_amount No Integer, should be included in Amount. For example $1.00 should be 100.
tax_amount No Integer, should be included in Amount. For example $1.00 should be 100.
discount_amount No Integer, should be included in Amount. For example $1.00 should be 100.
order_id No 17 Alphanumeric characters for reference
description No 100 Alphanumeric characters
po_number No 17 Alphanumeric characters for reference
tax_exempt No "true" or "false" default "false
email_address No Email address to tag to the transaction, emails are not sent.
processor_id No Processor ID to process the transaction, otherwise the default is used.
billing_first_name No
billing_last_name No
billing_company No
billing_address_line_1 No
billing_address_line_2 No
billing_city No
billing_state No
billing_postal_code No
billing_country No
billing_phone No
billing_fax No
billing_email No
shipping_first_name No
shipping_last_name No
shipping_company No
shipping_address_line_1 No
shipping_address_line_2 No
shipping_city No
shipping_state No
shipping_postal_code No
shipping_country No
shipping_phone No
shipping_fax No
shipping_email No

Response Format

Example:

"id","user_name","idempotency_key","type","transaction_source","ip_address","amount","amount_authorized","amount_captured","amount_settled","tip","service_fee","tax_amount","tax_exempt","shipping_amount","po_number","order_id","settlement_batch_id","referenced_transaction_id","payment_method","payment_type","response","response_code","status","processor_type","processor_id","processor_name","subscription_id","currency_iso_code","customer_id","email_address","billing_first_name","billing_last_name","billing_company","billing_address_line_1","billing_address_line_2","billing_city","billing_state","billing_postal_code","billing_country","billing_email","billing_phone","billing_fax","shipping_first_name","shipping_last_name","shipping_company","shipping_address_line_1","shipping_address_line_2","shipping_city","shipping_state","shipping_postal_code","shipping_country","shipping_email","shipping_phone","shipping_fax","created_at","captured_at","settled_at","card_type","entry_type","masked_account","expiration","auth_code","processor_response_code","processor_response_text","sec_code","account_type","avs_response_code","cvv_response_code"

API Endpoints

Upload a file

curl -v \
-H "Authorization: APIKEY" \
-F "file=@<FILENAME>" \
  "URL_GOES_HERE/filebatch"
{
  "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"
  }
}

Query the status of a batch

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
  "URL_GOES_HERE/filebatch/<batch id>"

The above command returns JSON structured like this:


	protected.Post("/filebatch", FileBatchUpload)
	protected.Get("/filebatch/{batchid:[0-9a-z]+}/download", FileBatchGetDownload)

Download the response

TIP

Only batches that are in completed status can be downloaded. After 10 days, batch results will no longer be available.

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
  "URL_GOES_HERE/filebatch/<batch id>/download"

This will stream the batch results if successful. Otherwise an error will be returned like so:

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