Uploading Bills, Downloading Payments, and Automating the Process. Section 1: Uploading bills

Transcription

1 Uplading Bills, Dwnlading Payments, and Autmating the Prcess This dcument describes uplading bills t Xpress-pay, dwnlading payments. There is n requirement fr a bill t upladed prir t payment because Xpress-pay ffers a variety f methds thrugh which transactins can be initiated. Fr infrmatin n these ppular alternatives, please cntact ur Supprt Department. The payment dwnlad functin is always available regardless f hw a transactin was riginated. This dcument is presented in tw sectins, the first fr uplading bills t Xpress-pay and the secnd fr dwnlading payments. ntificatins: Xpress-pay can a ntice in respnse t an uplad. This feature prvides significant cnvenience t the cnsumer and is highly effective in stimulating payment activity. We strngly encurage yu t prvide an address with upladed bills. Sectin 1: Uplading bills Bill are upladed t allw cnsumers t prvide criteria used t lcate and pay specific bills. Multiple search fields can presented and each can be ptinal r required. Where required, a partial value r exact match can be required. Bills matching the visitr s criteria are then presented fr review and selectin. Nte that upn presentatin, additinal infrmatin may be displayed. Fr example, search criteria might require an accunt number and last name, but displayed bills matching the criteria might als reveal the full name and service address in additin t the amunt due. This allws privacy in searching but enhances cnsumer cnfidence in selecting bills fr payment. Prir t uplading bills, the payment type and file frmat must be defined t Xpress-pay by ur Supprt Department. Yur file can be a fixed-frmat ASCII text file r an Excel spreadsheet (currently.xls nly). There must be ne recrd r line fr each bill. Extraneus lines may be included prvided that reliable criteria exists t exclude them, such as an asterisk in psitin ne. File uplads are accmplished in ne f tw ways: Imprt bills: This ptin is invked frm the Xpress-pay administrative menu. Use yur lgin and passwrd t access this functin. Autmated FTP: Yu can establish a schedule within yur wn envirnment t submit requests t uplad r dwnlad files frm Xpress-pay as needed. Fr mre infrmatin, see the end f this dcument r the PDF entitled Autmated Uplads & Dwnlads n ur Cntact us/merchant Supprt page Versin 3.06, Page 1

2 Field list fr uplading bills Bill date: Optinal. Billing date and the basis fr interest calculatin. If mitted here, it must be prvided when uplading bills. Unique ID (entity): Optinal. Used t uniquely identify the entity being billed. This facilitates subsequent ntificatins r assciatins with prerequisite utstanding bills (cntact ur Supprt Team fr additinal infrmatin). Bill amunt: Required. The amunt f the bill r, if negative, the credit. This field can be in multiple lcatins within a recrd and is thus cumulative. Amunts in this field are subject t the interest frmula yu may define fr each bill type. Bill amunt (n interest): Alternative t Bill amunt ; cumulative. Xpress-pay interest frmulas will nt be applied t these bill amunts. Bill credit: Optinal; cumulative. The amunt f credit t be applied t (subtracted frm) the bill amunt; cumulative. Nt applicable t Bill amunt (n interest). Interest: Optinal; cumulative. The amunt f interest t be presented with the bill (negates use f Xpress-pay interest frmulas). Interest credit: Optinal; cumulative. The amunt f credit t be subtracted frm the interest. Payment type restrictin: C=cards nly, E=eChecks nly. Thugh yu may elect t accept bth cards and echecks, this feature allws restrictin f payment types fr specific bills. Fr example, if a custmer has bunced checks, yu may wish t specify C n all bills yu uplad fr that custmer t restrict them t credit/debit card payments nly. Lcatrs 1-5: Five 250-character captined flexible data fields are available. Cntents can be cncatenated (ex. first name+space+last name). Each can be a required r ptinal search field, and exact matches can be required. A lcatr can be flagged as hidden, allwing yu t assciate additinal infrmatin with a bill withut revealing it t the visitr. Bill image filename (PDF, JPG, etc.): Optinal. Prvide the filename+extensin here. Yur server s URL/fldername will be included in the Xpress-pay cnfiguratin fr the payment type. address: Prviding an address allws us t send ntificatins upn bill uplad. Recipients need nly click the buttn t retrieve matching bills. ntificatins significantly elevate cnsumer cnvenience and payment activity and is highly recmmended. Nte that yu can restrict this feature t ne r tw specific days per mnth. This allws yu t uplad a cnsistent file withut spamming yur clients. Please discuss this ptin with ur Supprt Grup. Uplading Bills and Credits Recrds with an amunt due f $0 will be ignred. Recrds with amunts due > $0 are bills and recrds with amunts due < $0 (a minus sign preceding the amunt) are cnsidered t be credits. Visitrs will prvide criteria t search fr bills and credits. All recrds matching the criteria will be displayed, and the visitr may then select which bills t pay r credits t apply. If credits are fund and selected, they are applied against selected bills, but t prceed t checkut, the net amunt due resulting frm their selectins must be greater than $0. Versin 3.06, Page 2

3 Data Filtratin The uplad functin allws the inclusin r exclusin f recrds based n limited criteria. If these filters are mitted, all recrds will be imprted (prvided they have a net amunt due < r > $0). Each filter is independent f any ther filter line, that is if yu specify t include nly if psitin 278, length 1 = C and als specify t include nly if psitin 278, length 1 = R, n recrds will be imprted! That's because it is impssible fr psitin 278 t be bth a C and an R, s ne f the filters will fail. Yu can als use filtratin t simplify exprtatin frm yur system. As an example, fr a prperty management system, yu culd still exprt all bills fr bth security depsits and rent t a single file. When defining security depsits, use an include filter in its bill type t include nly if the psitin cntaining the type is "S". When defining rent, use an include filter in its bill type t include nly if the bill type is "R". Use f this technique vastly reduces the effrt required t imprt similar bills that wuld therwise be transmitted in separate files. If yur exprter is incapable f exprting nly utstanding bills, perhaps there is a way f using the filters circumvent t the shrtcming. Maybe yu can bypass paid recrds, such as a "P" in psitin 302, r include nly if payment date is = 00/00/0000. We invite yu t discuss this with ur Supprt Team prir t finalizing the design f yur extract prgram. (cntinued) Versin 3.06, Page 3

4 Sectin 2: Dwnlading Payments Xpress-pay recrds a histry recrd fr all payments regardless f their rigin. The Administrative Menu allw yu t prduce a reprt, and a dwnlad icn allws yu t capture a file f thse payments. See Sectin 3 fr infrmatin n the autmated FTP uplad/dwnlad. In the Payment Detail Reprt, the icn at the upper right will start a dwnlad f the payments being viewed. The dwnladed fixed-frmat ASCII text file will be in the fllwing frmat: Payment File Frmat State: 1-20 Merchant name: Bill type: Entity identifier: Bill date: as MMDDYYYY Payment date: as MMDDYYYY Payment type: as "card" r "echeck" Bill amunt: as 9(10)V99 Interest: as 9(10)V99 Client revenue: as 9(10)V99: Amunt realized by client, i.e. Bill amunt+ Interest Merchant fee: as 9(7)V99: Estimated amunt due t merchant prvider as a result f this transactin (nt applicable in sme scenaris) Site fee: as 9(7)V99: Amunt due t Systems East, Inc Payment ttal: as 9(10)V99: Grand ttal f the amunt paid by the visitr Transactin ID: as x(12) Lcatr 1: as x(50) Lcatr 2: as x(50) Nte: Fr the five lcatrs, nly the first fifty f the Lcatr 3: as x(50) Lcatr 4: as x(50) Lcatr 5: as x(50) Payer s infrmatin: as x(50) - Payment time: as hh:mm:ss - First name: as x(50) - Last name: as x(50) - Address: as x(100) - City: as x(30) - State: as x(30) - Zip cde: as x(10) pssible tw hundred characters are eched in the payment file Versin 3.06, Page 4

5 Ntes The representatin 9(10)V99 abve is a COBOL-style descriptin f the field s fixed-length internal frmat. In the first example immediately belw, it means ten dllar digits fllwed by the tw digits representing the cents. Fr example: Fr a 9(10)V99 frmat, $1, wuld be Fr a 9(7)V99 frmat, $1, wuld be As an alternative t dwnlading a fixed frmat ASCII payment file as described abve, the administrative menu s Payment Detail Reprt allws yu t dwnlad payments as a CSV file. CSV files may be pened directly by Micrsft Excel. If the CSV dwnlad ptin is used, the first rw will cntain clumn headers and each additinal rw will cntain ne payment recrd. (cntinued) Versin 3.06, Page 5

6 Sectin 3: Autmated Uplading and Dwnlading (FTP/sFTP) Xpress-pay supprts FTP and sftp t allw unattended uplading f bill files and dwnlading f payment files. These functins are initiated thrugh separate API s described in this sectin. Autmating the prcess allws the payments t be retrieved and prcessed at the end f each day withut staff interventin. This functin requires that yu establish an FTP lcatin as a surce r target fr files t be exchanged. Nte: The autmated prcess supprts nly fixed frmat ASCII text files. It des nt currently supprt Excel spreadsheet files. The FTP service allws the exchange f billing and payment files between Xpress-pay and yur FTP site. Whether uplading billing infrmatin t Xpress-pay r dwnlading payment files frm Xpresspay, yur FTP site will be used fr the exchange. Using the FTP service allws yu t: Dwnlad payments: Select a date/time range t dwnlad as a fixed frmat ASCII text file, then prcess these payments against yur internal accunts receivable system. Uplad (pst) a fixed frmat ASCII text file f bills: Allws yur custmers t search, select, and pay bills. Either r bth are typically scheduled t autmate the prcess, eliminating staff interventin. These functins perate independently, and yu can use either r bth. The hyperlink r HTML Pst that initiates the service must cntain all necessary infrmatin fr Xpress-pay t access yur FTP site as needed t exchange the targeted infrmatin. Uplading (psting) bills Sample URL string t uplad a fixed frmat ASCII text file f bills frm yur FTP site t Xpress-pay: txt&hstname=[hstname]&ftpflder=[ftpflder]&username=[username]&passwrd=[passwrd]&fing erprint=[fingerprint]&municipality=[municipality]&state=[state]& t=[ t]&billingdate=[billingd ate]&send =[send ]&rgid=[rgid]&billtypes=[billtypes] - ftptype: Specify ftp r sftp. - mde: If ftptype=ftp, yu must indicate active r passive, therwise specify the parameter but mit the value. - filename: The name f the bill file that is t be upladed, including the file extensin (ex. Bills.txt ) - hstname: Server URL r IP address f yur FTP site (the file surce). - ftpflder: The flder lcatin f the file n yur FTP server. - username, passwrd: Credentials t access the surce flder n yur FTP server. - fingerprint: SSH/SFTP key fingerprint, an security feature fr authenticating user and client applicatin. Fr details, see If &ftptype=ftp, submit this parameter with n value. - municipality: This is yur cmpany r municipality name as prvided by Xpress-pay supprt. - state: The state as yu are listed in Xpress-pay. Must be fully spelled ut; use + fr a space. Versin 3.06, Page 6

7 - t: The address f the persn t receive the uplad recrd cunt and ttal. Multiple recipients can be specified by separating them with a cmma (cmma nly; n space). - billingdate: The billing date t be assciated with the upladed bills. Frmat is mm/dd/yyyy, leading zers are nt required. Nte that If the billing date is included with each recrd in the billing file, it is nt needed here, thugh with a null value such as &billingdate=. Nte: If it must be specified, there are three ptins: Specify a date in the frmat mm/dd/yyyy Use the wrd tday fr tday s date Use the wrd bm t always use the first day f the current mnth (beginning f mnth) - send This parameter is n lnger used and has n effect; please specify 0 (zer) here. Nte: In the new versin f Xpress-pay, s are sent t the address specified in each upladed bill, prvided yur cnfiguratin is set t d s. s can be sent with every uplad r restricted t nly ne r tw specific days f the mnth that yu specify, and nt sent n ther days. This feature allws yu t send a cnsistent file withut spamming yur clients. Please discuss these ptins with ur Supprt Grup. - rgid: If yur file cntains bills f multiple types (as knwn t Xpress-pay) and yu wish t have Xpress-pay uplad them all in a single pass, yu can use this parameter instead f the next (billtypes). Our Supprt Department can prvide yu with the rgid. If yu elect nt t use this ptin, the parameter must still be specified, but with a null value. - billtypes: The specific payment type (billtype pk) established by Xpress-pay fr each payment type. T uplad multiple payment types in a single pass, separate them with a cmma (n spaces) such as 6530,6721, r see the rgid parameter abve. If yu elect nt t use the billtypes ptin, the parameter must still be specified, but with a null value. Dwnlading payments Sample URL string t dwnlad a fixed frmat ASCII text file f payments frm Xpress-pay t yur FTP site: erprint]&startdate=[startdate]&starttime=[starttime]&enddate=[enddate]&endtime=[endtime]&hstna me=[hstname]&username=[username]&passwrd=[passwrd]&ftpflder=[ftpflder]&filename=[filen ame].txt&rgid=[rgid]&billtypes=[billtypes] - ftptype: Specify ftp r sftp. - mde: If ftptype=ftp, yu must indicate active r passive, therwise specify the parameter but mit the value. - fingerprint: SSH/SFTP key fingerprint, an imprtant security feature that helps users and client applicatins authenticate SSH/SFTP servers. Fr details, see If &ftptype=ftp, submit this parameter with a null value. - startdate, starttime, enddate, endtime: Specifies the date range t include in the dwnladed file. Date frmat is mm/dd/yyyy and leading zeres may be mitted. Time frmat is hh:mm:ss [AM PM]. Ntes: The time range fr an entire day is 00:00:00%20AM thrugh 11:59:59%20PM %20 must be used t represent a space Versin 3.06, Page 7

8 If yur payment file dwnlad runs daily and yu wish t capture payments fr the entire preceding day, yu can specify nly &startdate=yesterday&enddate=yesterday and submit the ther tw parameters with a null value - hstname: Server URL r IP address f yur FTP site (the destinatin server). - username, passwrd: Credentials t access yur FTP site. - ftpflder: The destinatin flder n yur FTP server. - filename: The name f the bill file that is t be dwnladed, including the file extensin (ex. Payments.txt ). We recmmend the name be unique such as payments txt t prevent inadvertent verwriting. - rgid: If yu wish t dwnlad payment f all types fr the specified perid, yu can use this parameter instead f the next (billtypepk). Our Supprt Department can prvide yu with the rgid. If yu elect nt t use this ptin, the parameter must still be specified, but with a null value. - BillTypes: The payment types t dwnlad. The identifier (billtype pk) is available frm the Xpress-pay Supprt Grup. T dwnlad multiple payment types in a single pass, separate them with a cmma (n spaces) such as 6530,6721. T dwnlad payments fr all types in a single pass, see the rgid parameter abve. If yu elect nt t use the billtypes ptin, the parameter must still be specified, but with a null value. We remain available t assist yu if and as needed. In the meantime, thank yu fr selecting Xpresspay as yur epayment partner. Versin 3.06, Page 8