Appearance
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
bash
curl -v \
-H "Authorization: APIKEY" \
-F "file=@<FILENAME>" \
"https://sandbox.pepperpaygateway.com/api/filebatch"
json
{
"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
bash
curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
"https://sandbox.pepperpaygateway.com/api/filebatch/<batch id>"
The above command returns JSON structured like this:
json
{
"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.
bash
curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
"https://sandbox.pepperpaygateway.com/api/filebatch/<batch id>/download"
This will stream the batch results if successful. Otherwise an error will be returned like so:
json
{
"status":"failed",
"msg":"batch is not in completed status",
"data":null
}