# 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
payment_method_type No card/ach if you will specificying a payment_method_id
payment_method_id No The specific payment method on the referenced customer you are looking to charge.
amount Yes Amount to process as integer. For example $1.00 should be 100
base_amount No Can be used instead of amount, but will have surcharge and tax added before processing
surcharge No The amount to use for surcharge, this is included to amount. 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.
surcharge_exempt No "true" or "false" if you want to exempt this transaction from having a surcharge applied
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.
email_receipt No "true" or "false" to send an email receipt
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>" \
  "https://sandbox.gosparrowone.com/api/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" \
  "https://sandbox.gosparrowone.com/api/filebatch/<batch id>"

The above command returns JSON structured like this:

{
	"id": "bj1o70m9ku6fr2s21fig",
	"user_id": "bj1o70m9ku6fr2s21fig",
	"file_name": "testfile.csv",
	"status": "pending", // 'unknown', 'pending', 'queued', 'processing', 'failed' or 'completed'
	"num_lines": 1,
	"processed_lines": 1,
	"created_at": "2019-04-26T22:17:38.078185288Z",
	"updated_at": "2019-04-26T22:17:38.078185288Z"
}

# 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" \
  "https://sandbox.gosparrowone.com/api/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
}