GreenByPhone.com Report API Version 1.9

Transcription

1 Report API Version 1.9 (HTTP POST, Soap 1.1, Soap 1.2) Green Payment Processing,

2 REPORT API TABLE OF CONTENTS Introduction... 4 General Information... 4 Service Protocols Supported... 4 SOAP vs. POST/GET... 4 Our Gateway Web Service Address... 4 Message Encryption and Authentication... 5 Web Methods... 5 Testing Web Methods... 6 Web Service Common Input Fields... 6 Authentication Input Fields... 6 Output Specification Input Fields... 7 Check Status Results... 8 Check Status Results Output Fields... 9 Un-Processed Check reports Un-Processed Check Reports Input Un-Processed Check Reports Input Fields Un-Processed Check Reports Ouput Search Function Reports Search Function Reports Ouput SearchCheckDate Input SearchCheckDate Input Fields SearchCheckMemo Input SearchCheckMemo Input Fields SearchCheckNumber Input SearchCheckNumber Input Fields Page 2

3 SearchCheck_ID Input SearchCheck_ID Input Fields History Details reports History Details Reports Input History Details Reports Input Fields History Details Reports Ouput History Reports History Reports Input History Reports Input Fields History Reports Ouput History Reports Output Fields Result Codes Table Verify Result Codes Table... Error! Bookmark not defined. Page 3

4 INTRODUCTION Green By Phone s Report API v1.1 contains methods for reporting and searching on the Green By Phone system. GENERAL INFORMATION The Report API allows for complete integration of your application(s) into our real-time check entry system. The API is a.net web service written entirely in VB managed code and exposes all of the custom classes that you will need for calling its methods and interpreting the responses. The web service resides on our gateway with 1024-Bit encryption via SSL. SERVICE PROTOCOLS SUPPORTED HTTP POST/GET, SOAP 1.1 and SOAP 1.2 are all supported by the system. The choice is left up to your application development team. SOAP VS. POST/GET Originally, SOAP was the acronym for Simple Object Access Protocol. However, recently it has also been known to stand for Service Oriented Architecture Protocol. Either way, SOAP is a protocol for exchanging XML-based messages over computer networks, normally using HTTP or HTTPS. SOAP forms the foundation layer of the Web Services stack, providing a basic messaging framework in which more abstract layers can be built upon. SOAP messages transferred over HTTPS works well with firewalls and is the advocated WS-I method to provide web service security. OUR GATEWAY WEB SERVICE ADDRESS The web service is hosted at the following address: Page 4

5 MESSAGE ENCRYPTION AND AUTHENTICATION The SSL protocol allows applications to communicate across a network in a way designed to prevent eavesdropping, tampering, and message forgery. SSL provides endpoint authentication and communications privacy over the Internet using cryptography. Typically, only the server is authenticated (i.e., its identity is ensured) while the client remains unauthenticated; this means that the end user (be that a person, or an application such as a web browser), can be sure with whom they are "talking". When any method is called, the client must send its Client ID and the appropriate API Service Password along with all of the other input parameters specific to the method. This authorizes use of the method by validating that the password matches a currently active Client ID. WEB METHODS We support several different web methods that will allow you to select check information based on your needs. The methods fall in to three groups: Open Checks, Search Functions, and History Reports and History Details.. Un-Processed (Open) Checks UnProcessedChecks UnProcessedChecksFuture UnProcessedChecksRecurring UnProcessedChecksRiskyBad UnProcessedChecksUnVerified UnProcessedChecksBillPay UnProcessedChecksRefunds Search Function Reports SearchCheckAmount SearchCheckDate SearchCheckMemo SearchCheckNumber SearchCheck_ID History Details HistoryChecksDetails HistoryRejectedChecksDetails HistoryRefundChecksDetails HistoryBillPayChecksDetails History Reports HistoryChecks HistoryRejectedChecks HistoryRefundChecks HistoryBillPayChecks Page 5

6 TESTING WEB METHODS For any of the web methods, you can test them online whenever you like. Simply go to the Report.asmx page, select the method and a method description will be displayed with a test input form (see below). This is a live test page! Simply enter the data that your system will attempt to enter and you will get live results back; including the creation of live checks and invoices, so be careful. WEB SERVICE COMMON INPUT FIELDS All web methods share 4 common input fields. Two of them are for authentication: Client_ID and API Password. The other two are changing output specification: x_delim_data and x_delim_char. AUTHENTICATION INPUT FIELDS < x_delim_data>string</ x_delim_data> < x_delim_char>string</ x_delim_char > Client_ID* - Numeric Client ID assigned by the system. Page 6

7 ApiPassword* - API password assigned by the system (this is not the regular client password used by the web interface. Both authentication input fields are required (*). These are not the regular client password used for the web interface. They are only available through customer service. OUTPUT SPECIFICATION INPUT FIELDS < x_delim_data>string</ x_delim_data> < x_delim_char>string</ x_delim_char > x_delim_data determines whether or not output is delivered as delimited text data. x_delim_char If delimited data is requested, this field allows the user to specify the character used to delimit the data. Since we are using XML Web Services, all output defaults to XML. However, many legacy systems are still use older character delimited text protocol. Setting x_delim_data to TRUE, forces the system output to delimited text. Accepted values are true, T, yes, Y, 1, on ; and is not case sensitive. The default value if left blank is FALSE. If the x_delim_data to TRUE, the default value for x_delim_char is the pipe character ( ). Other common values are the comma (,) or the tilde (~) characters. Input of: x_delim_data=&x_delim_char= Results in: <ReturnResult><value1>1</value1><value2>$2.00</value2><value3>3.0%</value3></ReturnResult> Input of: x_delim_data=on&x_delim_char= Results in: 1 $ % Input of: x_delim_data=true&x_delim_char=, Results in: 1,$2.00,3.0% Note: if delimited text is selected and there is more than one record to be returned, the system delimits the records with Carriage Return / Line Feed characters. In other words, each record will be on a separate line of text. Page 7

8 CHECK STATUS RESULTS Most of the methods in the Report API return an array of Status Results. Each Status Result contains the status of one check, or one Status result that indicates that no checks were found. <ArrayOfStatusResult> <StatusResult> <Result>string</Result> <ResultDescription>string</ResultDescription> <Check_ID>string</Check_ID> <CheckType>string</CheckType> <CheckMemo>string</CheckMemo> <CheckNumber>string</CheckNumber> <CheckAmount>string</CheckAmount> <CheckDate>string</CheckDate> <CreateDate>string</CreateDate> <VerifyResult>string</VerifyResult> <VerifyResultDescription>string</VerifyResultDescription> <VerifyResultPasses>boolean</VerifyResultPasses> <VerifyResultOverridable>boolean</VerifyResultOverridable> <VerifyResultOverriden>boolean</VerifyResultOverriden> <VerifyResultReSubmitable>boolean</VerifyResultReSubmitable> <ProcessDate>string</ProcessDate> <CheckRejectType>string</CheckRejectType> <RejectAmount>string</RejectAmount> <RejectDate>string</RejectDate> <RefundCheck_ID>string</RefundCheck_ID> <Deleted>boolean</Deleted> </StatusResult> <StatusResult> Next status result for next check.. <StatusResult> </StatusResult> </ArrayOfStatusResult> Page 8

9 CHECK STATUS RESULTS OUTPUT FIELDS Result - The numeric Result Code. A Result Code of 0 means that the input was accepted into the System. All other codes indicate that the input not accepted by the system. See the Result Codes Table on page 22. ResultDescription A text description of the Result field from above. **Note: It is possible to have no checks returned for a search or report even though the input format was correct. In this case the Result=0 and the ResultDescription will be No Data For Report. Check_ID Unique record number for the check in the system. CheckType Type of check. Ex: Normal check, CP Button (website button), CP Invoice, Bill Pay Check. CheckMemo Check memo that you entered on the check. CheckNumber Check number assigned to the check. CheckAmount Check amount that you entered on the check. CheckDate Check date that you entered on the check. CreateDate System date when the check was created. VerifyResult Returns the verification code for the check. VerifyResultDescription - The text description of the code above. VerifyResultPasses Boolean (true or false) indicates whether the verification passed or not. VerifyResultOverridable Boolean (true or false) indicates if VerifyResultPasses=False, whether the verification can be overridden or not. VerifyResultOverriden Boolean (true or false) indicates whether the verification was already overridden. VerifyResultReSubmitable Boolean (true or false) indicates if VerifyResultPasses=False, whether the check can be re-submitted or not. ProcessDate The date/time the check was processed. CheckRejectType This is the post deposit reject (returned item) information. Not Rejected means that the item has not yet been rejected. Rejected values include: NSF, Altered Item, UFH, Stop Payment, Closed Account, etc. RejectAmount If Rejected, this will contain the amount or rejected funds(check amount) otherwise ot will be RejectDate Date of reject or blank. RefundCheck_ID If this check was refunded, this is the Check_ID of the refund checked, otherwise 0. Deleted Boolean (true or false) indicates whether the check was deleted or not.. Page 9

10 UN-PROCESSED CHECK REPORTS There are seven Up-Processed Check reports. Un-Processed checks are checks that have not yet been processed by the system. Each of these reports has the same inputs and outputs. Un-Processed (Open) Checks UnProcessedChecks All open in-coming checks (checks coming to you) that are to be processed at the next system process time. UnProcessedChecksFuture All open in-coming checks (checks coming to you) that are to be processed any time in the future. UnProcessedChecksRecurring All open in-coming checks (checks coming to you) that are Recurring checks. UnProcessedChecksRiskyBad All open in-coming checks (checks coming to you) that will not be processed due to a negative verification code of some kind. UnProcessedChecksUnVerified All open in-coming checks (checks coming to you) that have not yet been verified (this can happen if the checks are input in Batch Verification mode, but as the system completes the verifications these checks will move into one of the other reports. UnProcessedChecksRefunds All open out-going refund checks (checks going from you) that are to be processed at the next system process time. UnProcessedChecksBillPay All open out-going Bill-Pay checks (checks going from you) that are to be processed at the next system process time. UN-PROCESSED CHECK REPORTS INPUT <UnProcessedChecks> <Client_ID>string</Client_ID> <ApiPassword>string</ApiPassword> <x_delim_data>string</x_delim_data> <x_delim_char>string</x_delim_char> </UnProcessedChecks> Input is simple, just authentication and output specification. Page 10

11 UN-PROCESSED CHECK REPORTS INPUT FIELDS Input fields with red asterisk (*) are required. Client_ID* - See section on Authentication Input Fields on page 6. ApiPassword* - See section on Authentication Input Fields on page 6. x_delim_data - See section on Output Specification Input Fields on page 7. x_delim_char - See section on Output Specification Input Fields on page 7. UN-PROCESSED CHECK REPORTS OUPUT Output is an array of Check StatusResult records see page 8 for details. If there is incorrect data input (bad ID, password, etc) the system will return a single StatusResult with a Result code other than 0. The ResultDescription will contain the text description of the failure. If there is correct data input, but there is just no data (ex: no open check in the system at this time) the system will return a single StatusResult with a Result code of 0. The ResultDescription will contain "No Data For Report". If there is correct data input, but there is data the system will return a StatusResult for each record returned for the report. Each record will have a Result code of 0 and the ResultDescription will contain the search request description. Page 11

12 SEARCH FUNCTION REPORTS There are five Search reports. Un-Processed checks are checks that have not yet been processed by the system. Each of these reports has the similar inputs and the same output format. Search Function Reports SearchCheckAmount Search All checks (Open, Processed, etc) by Check Amount. SearchCheckDate Search All checks (Open, Processed, etc) by Check Date. SearchCheckMemo Search All checks (Open, Processed, etc) by Check Memo. SearchCheckNumber Search All checks (Open, Processed, etc) by Check Number. SearchCheck_ID Search All checks (Open, Processed, etc) by Check ID. SEARCH FUNCTION REPORTS OUPUT All of the Search Function Reports share the same output specification: Output is an array of Check StatusResult records see page 8 for details. If there is incorrect data input (bad ID, password, etc) the system will return a single StatusResult with a Result code other than 0. The ResultDescription will contain the text description of the failure. If there is correct data input, but there is just no data (ex: no open check in the system at this time) the system will return a single StatusResult with a Result code of 0. The ResultDescription will contain "No Data For Report". If there is correct data input, but there is data the system will return a StatusResult for each record returned for the report. Each record will have a Result code of 0 and the ResultDescription will contain the search request description. Page 12

13 SEARCHCHECKDATE INPUT <SearchCheckDate> <Client_ID>string</Client_ID> <ApiPassword>string</ApiPassword> <CheckDate>string</CheckDate> <x_delim_data>string</x_delim_data> <x_delim_char>string</x_delim_char> </SearchCheckDate> SEARCHCHECKDATE INPUT FIELDS Input fields with red asterisk (*) are required. Client_ID* - See section on Authentication Input Fields on page 6. ApiPassword* - See section on Authentication Input Fields on page 6. CheckDate* - The CheckDate for the search. x_delim_data - See section on Output Specification Input Fields on page 7. x_delim_char - See section on Output Specification Input Fields on page 7. Page 13

14 SEARCHCHECKMEMO INPUT <SearchCheckMemo> <Client_ID>string</Client_ID> <ApiPassword>string</ApiPassword> <CheckMemo>string</CheckMemo> <x_delim_data>string</x_delim_data> <x_delim_char>string</x_delim_char> </SearchCheckMemo> SEARCHCHECKMEMO INPUT FIELDS Input fields with red asterisk (*) are required. Client_ID* - See section on Authentication Input Fields on page 6. ApiPassword* - See section on Authentication Input Fields on page 6. CheckMemo* - The CheckMemo for the search. x_delim_data - See section on Output Specification Input Fields on page 7. x_delim_char - See section on Output Specification Input Fields on page 7. Page 14

15 SEARCHCHECKNUMBER INPUT <SearchCheckNumber> <Client_ID>string</Client_ID> <ApiPassword>string</ApiPassword> <CheckNumber>string</CheckNumber> <x_delim_data>string</x_delim_data> <x_delim_char>string</x_delim_char> </SearchCheckNumber> SEARCHCHECKNUMBER INPUT FIELDS Input fields with red asterisk (*) are required. Client_ID* - See section on Authentication Input Fields on page 6. ApiPassword* - See section on Authentication Input Fields on page 6. CheckNumber* - The CheckNumber for the search. x_delim_data - See section on Output Specification Input Fields on page 7. x_delim_char - See section on Output Specification Input Fields on page 7. Page 15

16 SEARCHCHECK_ID INPUT <SearchCheck_ID> <Client_ID>string</Client_ID> <ApiPassword>string</ApiPassword> <Check_ID>string</Check_ID> <x_delim_data>string</x_delim_data> <x_delim_char>string</x_delim_char> </SearchCheck_ID> SEARCHCHECK_ID INPUT FIELDS Input fields with red asterisk (*) are required. Client_ID* - See section on Authentication Input Fields on page 6. ApiPassword* - See section on Authentication Input Fields on page 6. Check_ID* - The Check_ID for the search. x_delim_data - See section on Output Specification Input Fields on page 7. x_delim_char - See section on Output Specification Input Fields on page 7. Page 16

17 HISTORY DETAILS REPORTS There are four HistoryDetails reports. Each provides the details for a type of processed check that were processed at a specific ProcessTime. If no ProcessTime is provided (left blank), the most current ProcessTime in the system is used. Each HistoryDetails report has a corresponding HistoryReport see page 19. HistoryReports provide summaries of the process dates. Each of these reports has the same inputs and outputs. History Details HistoryChecksDetails Returns all checks processed at a specific date/time. HistoryRejectedChecksDetails Returns all rejected checks processed at a specific date/time. HistoryRefundChecksDetails Returns all Refund checks processed at a specific date/time. HistoryBillPayChecksDetails Returns all Bill Pay checks processed at a specific date/time. HISTORY DETAILS REPORTS INPUT All HistoryDetails reports share the same inputs: <HistoryChecksDetails> <Client_ID>string</Client_ID> <ApiPassword>string</ApiPassword> <ProcessTime>string</ProcessTime> <x_delim_data>string</x_delim_data> <x_delim_char>string</x_delim_char> </HistoryChecksDetails> Page 17

18 HISTORY DETAILS REPORTS INPUT FIELDS Input fields with red asterisk (*) are required. Client_ID* - See section on Authentication Input Fields on page 6. ApiPassword* - See section on Authentication Input Fields on page 6. ProcessTime The time and date of the system processed the checks. If left blank, the system uses the last (most current) processing time. x_delim_data - See section on Output Specification Input Fields on page 7. x_delim_char - See section on Output Specification Input Fields on page 7. HISTORY DETAILS REPORTS OUPUT Output is an array of Check StatusResult records see page 8 for details. If there is incorrect data input (bad ID, password, etc) the system will return a single StatusResult with a Result code other than 0. The ResultDescription will contain the text description of the failure. If there is correct data input, but there is just no data (ex: no open check in the system at this time) the system will return a single StatusResult with a Result code of 0. The ResultDescription will contain "No Data For Report". If there is correct data input, but there is data the system will return a StatusResult for each record returned for the report. Each record will have a Result code of 0 and the ResultDescription will contain the search request description. Page 18

19 HISTORY REPORTS There are four HistoryReports. Each provides a summary report for checks processed during a specified date range. The date range is specified by the DateStart and DateEnd. If no DateStart is provided (left blank), a date of 90 days ago is used. If no DateEnd is provided (left blank), today s date is used. Each HistoryReport has a corresponding HistoryDetails report see page 17. HistoryDetails reports provide details for the process dates returned by the HistoryReports. Each of these reports has the same inputs and outputs. History Reports HistoryChecks Returns a summary of all checks processed in a date range. HistoryRejectedChecks Returns a summary of all rejected checks processed in a date range. HistoryRefundChecks Returns a summary of all Refund checks processed in a date range. HistoryBillPayChecks Returns a summary of all Bill Pay checks processed in a date range. HISTORY REPORTS INPUT All HistoryReports share the same inputs: <HistoryChecks> <Client_ID>string</Client_ID> <ApiPassword>string</ApiPassword> <DateStart>string</DateStart> <DateEnd>string</DateEnd> <x_delim_data>string</x_delim_data> <x_delim_char>string</x_delim_char> </HistoryChecks> HISTORY REPORTS INPUT FIELDS Input fields with red asterisk (*) are required. Client_ID* - See section on Authentication Input Fields on page 6. ApiPassword* - See section on Authentication Input Fields on page 6. DateStart The beginning date for the date range to search. If left blank, the system uses today-90 days. DateEnd The end date for the date range to search. If left blank, the system uses today. x_delim_data - See section on Output Specification Input Fields on page 7. x_delim_char - See section on Output Specification Input Fields on page 7. Page 19

20 HISTORY REPORTS OUPUT Most of the methods in the Report API return an array of Status Results. Each Status Result contains the status of one check, or one Status result that indicates that no checks were found. <ArrayOfHistoryResult> <HistoryResult> <Result>string</Result> <ResultDescription>string</ResultDescription> <ProcessTime>string</ProcessTime> <Count>string</Count> <Total>string</Total> <Reject>string</Reject> <Net>string</Net> </HistoryResult> <HistoryResult> Next history result.. <HistoryResult> </HistoryResult> </ArrayOfHistoryResult> HISTORY REPORTS OUTPUT FIELDS Result - The numeric Result Code. A Result Code of 0 means that the input was accepted into the System. All other codes indicate that the input not accepted by the system. See the Result Codes Table on page 22. ResultDescription A text description of the Result field from above. **Note: It is possible to have no checks returned for a search or report even though the input format was correct. In this case the Result=0 and the ResultDescription will be No Data For Report. ProcessTime The System date and time that the checks were processed. Count Number of checks processed. Total Total amount of the Check Amounts for the checks processed. Reject Total amount (if any) of the rejected Check Amounts for these checks. Net Net check total (Total-Reject). Page 20

21 If there is incorrect data input (bad ID, password, etc) the system will return a single HistoryResult with a Result code other than 0. The ResultDescription will contain the text description of the failure. If there is correct data input, but there is just no data (ex: no checks in the system that match the request data) the system will return a single HistoryResult with a Result code of 0. The ResultDescription will contain "No Data For Report". If there is correct data input, but there is data the system will return a HistoryResult for each record returned for the report. Each record will have a Result code of 0 and the ResultDescription will contain the search request description. Page 21

22 RESULT CODES TABLE Result ResultDescription 0 Report Name if there is data. 0 No Data For Report. 1 Client_ID NOT in Database. 2 Password Supplied Not Correct. 3 Client has been deleted. 4 Client Bank Account Not Verified. 5 Client Not Active. 6 Client is not a member of this application. 10 Missing SearchData value. 11 Invalid SearchData value (integer). 12 Invalid SearchData value (date). 13 Invalid SearchData value (decimal). 20 Invalid ProcessTime value. 30 Invalid DateStart value. 31 Invalid DateEnd value. 96 Invalid x_delim_data value. 97 Invalid x_delim_char value. Page 22