### # 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.