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"
  }
}

Batch status

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

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
}