Transcription
SOA PAYMENT INTERFACE SPECIFICATIONSFOR THE CITYWIDE PAYMENTS & RECEIVABLES REPOSITORY (CPRR) PROJECT
REVISION HISTORYVersionUpdated ByChange Description0.20.30.40.50.6**** ******** ******** ******** ******** ****0.7**** ****0.8**** ****Draft VersionDraft distributed for commentsUpdates after **** **** meetings on 9/23 & 24Updates after new **** interface specifications and further clarificationsAdded NYCServ informationUpdated reference data values for date fields, added IN DTModified UpdateResponse, VoidRequest referenceAdded logic for retail and future receivables.Added Remittance Flex KeysAdded logic for Convenience Fees.Updates after **** **** meetings on 10/15 & 16Changed “CASHIER REMITTANCE TENDER TYPE” to “REMITTANCE TENDERTYPE” in TNDRID mapping. Clarified validations for TNDRID.Specified mandatory fields for Tender details.Updated VoidRequest processing logic and assumptionsUpdated Remittance Flex Field 1-10 max length to 100.Added NYCServ Interface IDAdd duplicate Transaction Reference Number check.Added logic to validate the various amounts between Transactions,Tenders and TTA.Added a new Tender Type in section 6.1.5Updated information in table 6.1.2 Remittance Flex Key MappingAdded information in section 6.1.4 – Agency, System, Agency AccountNumberAdded information in section 6.1.3 – Agency, System, Transaction Type,ItemCode MappingModified processing logic for TNDRIDRenamed “bank account number” like “bank account nbr”Renamed “bank routing number” like “bank routing nbr”Updated information in section 6.1.3 – Agency, System, Transaction Type,ItemCode Mapping. Added new Transaction TypesRenamed all instances of TrasactionItem like TransactionItemModified processing logic for POSTDTModified processing logic for IN DTModified processing logic for TransactionItem total, as per R. ChatterjeeDeleted processing logic for summing and storing total amount paid underreceipt, as per R. ChatterjeeModified item codes for ECB and STARS values as per D.****Included “ECB-Update” in the list of NYCServ values for IDIncluded “AIMS” in the list of NYCServ values for SOURCE TYPEAdded Remittance Flex Key Logic for Account Receivable paymentsUpdated Remittance Flex Key Mapping TableUpdated Receivable Key Logic for Fairtax Future Receivables(AGCY SHRT NM “DOF” and TransactionItem.SYS NM “FAIRTAX”)Added validation and processing logic for KEY COL5, KEY COL6, KEY COL7Added Remittance Flex Key Logic for Bill Number and revised Flex Key logicfor ScoffTow Case Number.**** ******** ****0.9**** ****1,0**** ****1.1**** ****1.2**** ****1.31.4******** ****1.5**** ****1.6****1.71.8**** ******** ****1.9**** ****2.0**** ****2.12.2**** ******** ****Updated Convenience Fee Processing logicRemoved tag AGCY BANK ACCT NBR from Transaction sectionUpdated Appendix A Reference DataApplied overall document font and formatting improvementsUpdated Remittance Flex Key Logic for Account Receivable paymentsUpdated Remittance Flex Key Mapping TableAdded “SC” (Sheriff Check) to 6.4 Tender Types tableAdded “OC” to list of SOURCE TYPE valuesListed applicable DEPTID and USERID valuesUpdated processing logic for “TransactionReferenceNbr”Added TenderItem “phone number”Exhibit C CPRR SOA Payment Interface SpecificationsPage 2 of 5111/8/2019
2.32.4**** ******** ****2.5**** ****2.62.7**** ******** ****2.83.0**** ******** ****Added TenderItem “EMAIL RECEIPT”Added Remittance Flex Key Logic for CTOPS Retail Payments(AGCY SHRT NM “NYPD” and TransactionItem.SYS NM “CTOPS”)Updated list of applicable DatasourceName, DEPTID, SOURCE TYPE,USERID, and ReceiptReferenceNbr (prefix) valuesEdited Convenience Fee Processing logicChanged location where “phone number” is stored (fromREMTN TNDR DET to REMTR ADDR) and modified logicRenamed doc title and filename like “SOA Payment Interface”Added TenderItems “shipto name,” “shipto address1,” “shipto address2,”shipto city,” shipto state,” shipto zip,” shipto country,”shipto phone number”Exhibit C CPRR SOA Payment Interface SpecificationsPage 3 of 5111/8/2019
TABLE OF CONTENTSREVISION HISTORY . 2TABLE OF CONTENTS . 41 OVERVIEW. 62 PAYMENT UPDATE . 72.1ASSUMPTIONS.72.2UPDATE REQUEST – INTERFACE AND DATA ELEMENTS .82.2.1 Structure.82.2.2 Data Dictionary.92.2.3 Transactions, Tenders and TTA Mapping Example .282.2.4 CPRR Processing .292.3UPDATE RESPONSE – INTERFACE AND DATA ELEMENTS .362.3.1 Structure.362.3.2 CPRR Processing .362.3.3 Data Dictionary.362.3.3.1Success .362.3.3.2Failure .372.3.3.3Error Catalog .373 VOID. 383.1ASSUMPTIONS.383.2VOID REQUEST – INTERFACE AND DATA ELEMENTS .383.2.1 Structure.383.2.2 Data Dictionary.383.2.3 CPRR Processing .393.3VOID RESPONSE – INTERFACE AND DATA ELEMENTS .403.3.1 Structure.403.3.2 CPRR Processing .403.3.3 Data Dictionary.403.3.3.1Success .403.3.3.2Failure .403.3.3.3Error Catalog .414 OPEN ISSUES AND FUTURE CONSIDERATIONS . ERROR! BOOKMARK NOT DEFINED.5 REFERENCES AND RELATED DOCUMENTS . ERROR! BOOKMARK NOT DEFINED.6 APPENDIX A: REFERENCE DATA . 436.1REMITTANCE RECEIVABLE KEY MAPPING .436.2REMITTANCE FLEX KEY MAPPING.436.3AGENCY, SYSTEM, TRANSACTIONTYPE, ITEMCODE MAPPING .436.3.1 DOF – Fairtax .436.3.2 DOF – STARS .466.3.3 ECB - AIMS .496.3.4 DEP – DEPWB .496.3.5 DOF – ScofffTow .496.3.6 DOF – ACRIS.506.4TENDER TYPES .51Exhibit C CPRR SOA Payment Interface SpecificationsPage 4 of 5111/8/2019
Exhibit C CPRR SOA Payment Interface SpecificationsPage 5 of 5111/8/2019
1OVERVIEWThe interfaces between CPRR and **** **** Revenue Portal systems in scope of this document are as follows: Inbound to CPRR from ****:o Update Requesto Void RequestOutbound from CPRR to ****:o Update Response (Success or Failure)o Void Response (Success or Failure)The accepted protocol for data transfer is SOAP and the interfaces covered in this document are real time webservice calls. One use case for this interface (Parking In-Person Payments) is illustrated in the following diagram:Exhibit C CPRR SOA Payment Interface SpecificationsPage 6 of 5111/8/2019
2PAYMENT UPDATE2.1 Assumptionsa. This interface will be used to send to CPRR the following types of payments (remittances):i.Remittances for Account Receivables that already exist in CPRR.ii.Remittances for Account Receivables that do not yet exist in CPRR. These may be sent to CPRR atsome future time from the corresponding agency’s Account Receivables interface to CPRR. Suchreceivables are also called Future Receivables.iii.Retail Payments. These by definition will never have a corresponding Accounts Receivable defined.iv.Convenience Fee remittances, as applicable by business rules established by DOF. These can relate toone or more other remittances.v.Reversals: Need discuss with **** in more detail the layout/validations for Reversals. Reversals willnot be sent by **** with the exception of No Good Check payments. **** currently has no partialreversals, they are in development. Need further details, TBD b. Each Receipt (as represented by the ****Event data structure) will contain an array of Transactions, anarray of Tenders and an array of mapping Transactions to Tenders (as represented by the TTAMAPPINGdata structure).c. The Transaction Reference Number field will uniquely identify each Transaction sent by ****.d. Each Transaction must be identified with the corresponding Agency, System, Transaction Type, Item Codeand Agency Account Number attributes, as predefined by CPRR. These are static reference data that CPRRwill provide at configuration time. Note that for Account Receivables payments CPRR will provide thesevalues via the InquiryResponse message sent to ****. For Future Receivable and Retail Payments thesevalues must be determined by **** based on the previously provided static reference data.e. For Account Receivables only: The attribute Receivable Key (RECVBLS KEY) uniquely identifies a singlereceivable record in CPRR and is required in order to correctly apply the remittance.f. For Future Receivables only: The appropriate keys need to be sent to CPRR so that the payment can becorrectly attributed when sent to the corresponding agency. The types of keys will be predefined perAgency, System and Transaction Type.g. A Convenience Fee remittance may be applied to one or more base payment Transactions depending onbusiness rules. Each Convenience Fee remittance will be sent as a separate Transaction on the sameReceipt as the corresponding base payment Transaction(s). Each Convenience Fee will also have its ownTender element separate from the base payment Tender(s). The TTAMAPPING will map as usual theappropriate Tender to the corresponding Convenience Fee Transaction(s). **** will identify whichTransactions are created because of Convenience Fees.h. NYCServ will also use the same interface definition to send to CPRR remittances (for example originatingfrom ****, ACRIS or CCWeb).Exhibit C CPRR SOA Payment Interface SpecificationsPage 7 of 5111/8/2019
2.2 Update Request – Interface and Data Elements2.2.1 StructureThe XML file submitted in this interface will contain the following logical section(s): UpdateRequest SystemInterfaces SystemInterface SystemInterfaceItems SystemInterfaceItem ****File ****FileItems ****FileItem ****Events ****Event ****EventItems ****EventItem Transactions
1.4 **** **** Included ECB-Update _ in the list of NYServ values for ID Included AIMS _ in the list of NYServ values for SOURE_TYPE Added Remittance Flex Key Logic for Account Receivable payments Updated Remittance Flex Key Mapping Table 1.5 **** **** Updated Receivable Key Logic for Fairtax Future Receivables (AGY_SHRT_NM DOF _ and TransactionItem.SYS_NM FAIRTAX) Added
