###
# BluePay  2.0 "Batch Upload" Interface

Last Update: 2023-05-01

# Description

This interface is intended to be used by a merchant to upload a batch of transactions.

There are two versions of the output of this API. Version 1 receives a upload, imports it and 
responds with the result of the import. Version 2 does the same but sends characters in the 
DOTS field to keep the connection open during  import. This may be necessary when a large 
number of transactions are being uploaded.

The URLs of this interface are currently:
Version 1: https://secure.bluepay.com/interfaces/bp20bu
Version 2: https://secure.bluepay.com/interfaces/bp20bu.v2
           Or
           https://secure.bluepay.com/interfaces/bp20bu 
           with "X-Bluepay-response-version: 2" included in the HTTP header.

If performing ACH microdeposits the credit transactions and sale transactions must be uploaded
in separate files.

# Input format

Input to this web service utilizes an HTTP "POST" style interface.
The headers must be set specifically as such:
1) Content-type: Must include the letters "csv" as in "text/csv" or whatever.
2) Content-length: Must be present and indicate the number of bytes in the body
3) X-BluePay-account: Must be present and include the 12-digit BluePay account ID
4) X-BluePay-key: Contains the 32-character secret key
5) X-BluePay-mode: TEST or LIVE
6) X-Bluepay-ignore-parser-errors: 1 or 0 (Optional) When enabled parser will continue to 
                                   process file after an error is encountered.
 
The body of the POST contains the contents of the batch upload CSV file. The first line must 
contain all of the field names used throughout the remainder of the file.

For example:
"payment_acc","card_expire","amount","trans_type"
"4111111111111111","0128","1.00","SALE"
"4782000000000006","0629","3.00","SALE"

# Output format

Output will be in the immediate response to the POST. The body of the response will contain 
the output parameters and values in a URI-encoded format.

You can also be notified via BluePay's notification system. The notification system will 
notify the merchant via email(default) or can POST to a CGI on the merchant's server.

# Input parameters
The first line in the body of the POST will contain a list of the field names used through the 
remainder of the file, as described above. 

The list of fields allowed in the batch upload are as follows:
trans_type
  Maximum length 8
  -- Required
  AUTH = Reserve funds on a customer's card. No funds are transferred.
  SALE = Make a sale. Funds are transferred.
  CAPTURE = Capture a previous AUTH. Funds are transferred.
  CREDIT = Give a customer funds. Funds are transferred.
  VOID = Cancel a previous SALE or CAPTURE before it has settled.
  REFUND = Reverse a previous SALE. Funds are transferred.
  REBCANCEL = Cancel a rebilling sequence.
payment_acc
  Maximum length 32
  -- Required for AUTH/SALE --Optional for VOID/REFUND or master_id
  The payment account used for the transaction. Credit card number or bank account 
  information. Please see the note below for specifics on processing ACH.
card_expire
  Maximum length 4
  -- Required for payment_type CREDIT -- Required for AUTH/SALE
  -- Optional for VOID/REFUND or master_id Expiration date for a credit card in MMYY. 
  This will be blank for an ACH.
payment_type
  Maximum length 8
  -- Optional
  'ACH' for ACH transactions
  'CREDIT' for credit card transactions. Default.
f_corporate
  Length 1 
  -- Optional
  This flag must be set to '1' for ACH transactions with a doc type of 'CCD'.

External Rebill Field
f_rebilling
  Length 1 
  -- Optional
  Set to '1' for rebilling transactions created outside of the BluePay gateway.

Internal Rebill Fields
do_rebilling
  -- Optional
  Set to '1' to create a rebilling.
next_date
  -- Optional
  Date of first rebilling in ISO format YYYY-MM-DD
sched_expr
  -- Optional
  Period between rebillings
  1 MINUTE
  1 MONTH
  1 YEAR
  1 HOUR
  1 MINUTE
cycles_remain
  -- Optional
  Quantity of times that rebilling should occur. Not set for infinite.
reb_amount
  -- Optional
  Amount to charge on rebilling. Defaults to value in amount field if not set.
reb_is_credit
  -- Optional
  '1' flags the rebill as a credit rather than a debit, for recurring payments from merchant 
  to customer. Not set for debit against customer's payment information.

stored_indicator -  (1 AN) [ F|S]
  'F' - "First" transaction of a stored credential transaction.
  'S' - "Subsequent" transaction in a stored credential setup.
  (null) - Ignore this entire new system and do nothing different.

stored_id - (AN) (id number)
  Transaction identifier received from FD after the initial 'F' stored indicator transaction.  Required on 'S' indicator.

stored_type - (1 AN) [ M|C] 
  'M' - "Merchant" initiated stored credentials transaction.   
  'C' - "Cardholder" initiated stored credentials transaction. 
  Required if STORED_INDICATOR sent.
 
doc_type
  Length 3
  -- Optional
  Can be one of the following:
    'PPD':  Indicates you have a personal signed agreement on file for the customer, this is 
            the default if not set.
    'CCD':  Indicates you have a company-signed agreement on file for the customer.
    'WEB':  Indicates the customer has agreed to the charges via an internet-based or 
            electronic form.
    'TEL':  Indicates you have a recorded telephone call on file with the customer verbally 
            agreeing to be charged.
			
ach_description
  -- Optional
  10 character alphanumeric field that is used to identify the type of transaction being performed.
  
ach_same_day_funding
  Length 1
  -- Optional
  Flag (0 or 1) identifying if same-day funding should be used.

company_name
  Maximum length 64
  -- Optional
  Must contain the company name if f_corporate is set to '1'.
amount
  Maximum length 9
  -- Required for AUTH/SALE -- Optional for REFUND or master_id
  If AMOUNT is sent for a REFUND, it will REFUND the AMOUNT sent. It will only refund up to 
  the original transaction AMOUNT. If not sent, it will REFUND the full amount.
amount_tax
  Tax amount charged payer.
name1
  Maximum length 32
  -- Optional
  The cardholder's name 1.
name2
  Maximum length 32
  -- Optional
  The cardholder's name 2.
addr1
  Maximum length 64
  -- Optional
  The cardholder's address 1.
addr2
  Maximum length 64 
  -- Optional
  The cardholder's address 2.
city
  Maximum length 32 
  -- Optional
  The cardholder's city.
state
  Maximum length 16 
  -- Optional
  The cardholder's state.
zip
  Maximum length 16 
  -- Optional
  The cardholder's zip.
email
  Maximum length 64 
  -- Optional
  The cardholder's email.
phone
  Maximum length 16 
  -- Optional
  The cardholder's phone number.
master_id
  Type: bigint
  -- Optional
  The trans_id (RRNO) of a subsequent transactions run against the payment account.
order_id
  Maximum length 128 
  -- Optional
  The merchant-supplied or system supplied order id.
invoice_id
  Maximum length 64
  -- Optional
  The merchant-supplied or system supplied invoice id. 
customer_code
  Maximum length 17
  -- Optional
  Merchant supplied code identifying customer.			 				   			 											  
custom_id
  Maximum length 16
  -- Optional
  The merchant-supplied value for Custom ID 1.
custom_id2
  Maximum length 64
  -- Optional
  The merchant-supplied value for Custom ID 2.
auth_code
  Maximum length 8 
  -- Optional -- Required for Capture
  A six-character pseudo-ID from the front end processing network.
memo
  Maximum length 128 
  -- Optional
  A memo that was submitted with the transaction.
cust_token
  Maximum length 16
  -- Optional
  The Customer Token whose stored payment information should be used for this transaction. Any 
  parameters not sent will be filled out from the last transaction that used this Customer 
  Token. 
new_cust_token
  Maximum length 16
  -- Optional
  The new Customer Token that will store this customer's payment information. Must be 6-16 
  alphanumeric characters. Cannot include the values of NAME1, NAME2, or COMPANY_NAME. Cannot 
  include the last 4 digits of the customer's payment account number. Must be unique to this 
  account.
f_transarmor
  Maximum length 1
  -- Required if using a TransArmor Token
  -- TransArmor Tokens cannot be created using this API
  Set to '1' if a TransArmor Token is being used.
card_type
  Maximum length 4
  -- Required if f_transarmor=1
  -- Otherwise, this field will be ignored
  A four-character indicator of the credit card brand represented by the TransArmor Token. 
    Possible values are:
    AMEX = American Express
    DC   = Diner's Club
    DISC = Discover
    JCB  = JCB
    MC   = MasterCard
    VISA = Visa
The following fields are available for optional Lodging processing.
lodging_folio_num
  Maximum length 64
  -- Required for lodging
  The lodging folio number.
lodging_arrival_date
  Maximum length 10
  -- Required for lodging
  The date the customer arrived at lodging.
  "YYYY-MM-DD"
lodging_depart_date
  Maximum length 10
  -- Required for lodging
  The date the customer checked out of lodging.
  "YYYY-MM-DD"
lodging_local_phone
  Maximum length 10
  -- Required for lodging
  The local phone number of the specific lodging location, up to 10 digits.
lodging_country
  Maximum length 3
  -- Required for lodging (if outside of USA)
  The code for the country in which the lodging is located. Defaults to 'USA' if not set.
  Use the ISO 3166-1 Alpha-3 Country Code (i.e.: USA, CAN).
lodging_pref_cust_f
  Maximum length 1
  -- Optional
  1 if the customer is a preferred customer.
  0 or not present if not applicable.
lodging_extra_giftshop_f
  Maximum length 1
  -- Optional
  1 if there was an additional charge for the gift shop.
  0 or not present if not applicable.
lodging_extra_laundry_f
  Maximum length 1
  -- Optional
  1 if there was an additional charge for a parking violation.
  0 or not present if not applicable.
lodging_extra_minibar_f
  Maximum length 1
  -- Optional
  1 if there was an additional charge for the mini bar.
  0 or not present if not applicable.
lodging_extra_restaurant_f
  Maximum length 1
  -- Optional
  1 if there was an additional charge for the restaurant.
  0 or not present if not applicable.
lodging_extra_phone_f
  Maximum length 1
  -- Optional
  1 if there was an additional charge for the telephone.
  0 or not present if not applicable.
lodging_extra_other_f
  Maximum length 1
  -- Optional
  This should not include gift shop, laundry, mini bar, restaurant, or telephone charges.
  1 if there was an additional charge.
  0 or not present if not applicable.
lodging_charge_type
  Maximum length 1
  -- Optional
  The code for the description of the lodging charge. Defaults to '1' (Hotel Stay) if not set. 
  Possible codes are:
    1 = Hotel Stay
    2 = Assured Reservation - No Show
    3 = CARDeposit
    4 = Delayed Charge
    5 = Express Service
    6 = Assured Reservation

The following fields are available for Vehicle Rental processing.
vehicle_rent_agree_num
  Maximum length 64
  -- Required for vehicle rentals
  The invoice or rental agreement number of the original vehicle rental agreement.
vehicle_pickup_datetime
  Maximum length 19
  -- Required for vehicle rentals
  The date the vehicle rental began.
  "YYYY-MM-DD HH:MM:SS" Hours, minutes, and seconds are optional
vehicle_dropoff_datetime
  Maximum length 19
  -- Required for vehicle rentals
  The date the vehicle rental ended.
  "YYYY-MM-DD HH:MM:SS" Hours, minutes, and seconds are optional
vehicle_pickup_city
  Maximum length 64
  -- Optional
  The city in which the vehicle was rented.
vehicle_dropoff_city
  Maximum length 64
  -- Required for vehicle rentals
  The city in which the vehicle was returned. 
vehicle_dropoff_location_id
  Maximum length 10
  -- Required for vehicle rentals
  Identification of return location (phone, store ID, etc.), up to 10 characters.
vehicle_pickup_country
  Maximum length 3
  -- Required for vehicle rentals (if outside of USA)
  The code for the country in which the vehicle was rented. Defaults to 'USA' if not set.
  Use the ISO 3166-1 Alpha-3 Country Code (i.e.: USA, CAN).
vehicle_dropoff_country
  Maximum length 3
  -- Required for vehicle rentals (if outside of USA)
  The code for the country in which the vehicle was returned. Defaults to 'USA' if not set.
  Use the ISO 3166-1 Alpha-3 Country Code (i.e.: USA, CAN).
vehicle_renter_name1
  Maximum length 32
  -- Required for vehicle rentals (if different from name1) 
  The first name of the renter. Defaults to name1 if not set.
vehicle_renter_name2
  Maximum length 32
  -- Required for vehicle rentals (if different from name2) 
  The last name of the renter. Defaults to name2 if not set.
vehicle_pref_cust_f
  Maximum length 1
  -- Optional
  1 if the customer is a preferred customer.
  0 or not present if not applicable.
vehicle_extra_gas_f
  Maximum length 1
  -- Optional
  1 if there was an additional charge for gas.
  0 or not present if not applicable.
vehicle_extra_miles_f
  Maximum length 1
  -- Optional
  1 if there was an additional charge for extra mileage.
  0 or not present if not applicable.
vehicle_extra_late_f
  Maximum length 1
  -- Optional
  1 if there was an additional charge for a late return.
  0 or not present if not applicable.
vehicle_extra_violations_f
  Maximum length 1
  -- Optional
  1 if there was an additional charge for a parking violation.
  0 or not present if not applicable.
vehicle_oneway_amount
  -- Optional
  The amount charged for a one-way rental.
vehicle_no_show_amount
  -- Optional
  The amount charged if the renter did not claim the vehicle as scheduled.
vehicle_total_extra_amount
  -- Optional
  The total amount of extra charges that have been added.
vehicle_type
  Maximum length 2
  -- Optional
  The code for the type of vehicle being rented. Defaults to '99' (Miscellaneous) if not set. 
  Possible codes are:
    01 = Mini
    02 = Subcompact
    03 = Economy
    04 = Compact
    05 = Midsize
    06 = Intermediate
    07 = Standard
    08 = Full size
    09 = Luxury
    10 = Premium
    11 = Minivan
    12 = Van (12-passenger)
    13 = Van (moving)
    14 = Van (15-passenger)
    15 = Van (cargo)
    16 = Truck (12-foot)
    17 = Truck (20-foot)
    18 = Truck (24-foot)
    19 = Truck (26-foot)
    20 = Moped
    21 = Stretch
    22 = Regular
    23 = Unique
    24 = Exotic
    25 = Truck (small/medium)
    26 = Truck (large)
    27 = SUV (small)
    28 = SUV (medium)
    29 = SUV (large)
    30 = SUV (exotic)
    99 = Miscellaneous

NOTE: When performing an ACH, you must set the following:

payment_acc = three fields, separated by colons. 
    First is account type. 'C' for checking and 'S' for savings. 
    Second is routing number. 
    Third is account. 
    So for example: "C:123456789:987654321" would be a valid formatting.
payment_type = "ACH"
doc_type = Documentation Type also known as Standard Entry Class (SEC) Codes
           Can be one of the following:
             PPD  Prearranged Payment and Deposit
                  Indicates there is a personal signed agreement on file for the customer, this is
                    the default if not set.
             CCD  Corporate Credit or Debit Entry
                  Indicates there is a company-signed agreement on file for the customer.
             WEB  Internet Initiated/Mobile Entry
                  Indicates the customer has agreed to the charges via an internet-based or 
                    electronic form.
             TEL  Telephone-Initiated Entry
                  Indicates there is a recorded telephone call on file with the customer verbally 
                    agreeing to be charged.
             ARC  Accounts Receivable Entry
                  Indicates that a consumer check was received in the mail or at a dropbox location
                    and converted to an ACH transfer.
             BOC  Back Office Conversion Entry
                  Indicates that a consumer check was recieved in person from the consumer and later
                    converted to an ACH transfer.
             POP  Point of Purchase Entry
                  Indicates that a consumer check was received in person from the consumer and was
                    converted to an ACH transfer while the consumer was present.

NOTE: When using a TransArmor Token, you must set the following:
payment_acc = The TransArmor Token that represents the credit card that should be used.
f_transarmor = Set to "1" to indicate a TransArmor Token is being used.
card_type = The card type of the credit card represented by the TransArmor Token.
card_expire = The expiration date of the credit card represented by the TransArmor Token.																
# Output parameters

DOTS (v2 only)  - Period characters used to keep the connection active. The value can be 
                  discarded.
ERROR_COUNT     - Number of errors that occurred.
STATUS          - "OK" or "ERROR"
TRANS_COUNT     - Number of transaction processed.
MESSAGE         - Human-readable description of file processing result. For example "No errors 
                  detected".
BATCH_ID        - 12-digit BluePay Batch ID. Can be used when requesting the batch upload 
                  results using the Batch Upload Reporting API.