Payment Request Interface

PTMS/IF APPR01 Agency Guide

APPR01

Payment Request Interface

Agency Guide

INT 055

Pennsylvania Treasury

RM G-22 Finance Building

Harrisburg, PA 17120-0018

03/19/2014

Document Information and Revision History

PTMS/IF APPR01 Agency Guide

Version / Date / Revision Notes
1.0 / 1/15/2013 / Initial Version
1.1 / 1/24/2013 / Added the DocumentType element to the Header node for the Request message.
1.2 / 3/27/2013 / Updated guide to correctly reflect request schema field sizes and types.
Updated guide to include correct data type and size for the.
Updated data type for Item.SCDUNoncustodialParentSSN from String to Integer.
Updated documentation for size for Advice.LineType from 2 to 10.
Added additional source system codes to the listing in Appendix A.
Updated Appendix G for IES Source System Document Types.
Added FiscalYear element to the Funding node. Change element names in the Funding node: FundType->Fund, BusinessArea->Department, Fund->Appropriation.
Removed the DiscountAmount and DiscountDate elements from the Header node.
Add CUS for Customer Id as a possible value on the RecipientType element.
Add payment class PYNZ for payroll net zero pays.
Removed example data values from the sample XML from the PaymentRequest and the DataModule nodes.
Changed length of the RecipientLocation element of the Header node from 10 to 14.
Changed length of the FieldValue element of the ValidationMessage node from 18 to 254.
Added Appendix I Country Codes
1.3 / 05/16/13 / Added new lookup value DL for AuditLookupType element.
Revised descriptions for the FormatCode values CCD, PPD, and CTX. Also revised Appendix F.
Added new Payment Class GRLF for payroll Group Life Insurance Payments. Removed Payment Class PRUD.
Clarified definition of ‘appropriation’
1.4 / 06/27/13 / Clarified definition of ‘GrossPaymentAmount’
Clarified definition of ‘Account’
Clarified definition of ‘FiscalYear’
1.5 / 08/01/13 / Added new element VendorTaxpayerId to the Item node. Expanded description for the PayeeNameOne and PayeeNameTwo elements on the Item node to include their usage by additional Item Types.
1.6 / 08/26/13 / Appendix A – New source system ‘COS’ Commission On Sentencing
2.0 / 09/18/13 / Appendix J – Payment Due Date Rules
2.1 / 09/18/13 / Expanded description for the VendorId and VendorLocation elements on the Item node to include their usage by the AC (Advancement Account) ItemType.
3.0 / 11/20/13 / Parent Node: Acknowledgement-Min Occur Field should be 0.
Payment Node: Added New Handling Code, RADG – Return to Auditor General Comptroller. Deleted RTTC – Treasury Mails (UCP Checks)
AddressTwo, City, State, Postal Code descriptions were updated to reflect foreign addresses.
Added Appendix K to list the interface validation edits.
3.1 / 11/20/13 / Appendix A – Removed Source System, ADG “Auditor General” and AGA “Auditor General Allocation Payments.
4.0 / 12/18/13 / Batch ID description updated
4.1 / 12/18/13 / SCDUFIPS Code description updated
4.2 / 12/18/13 / Appendix D-Payment Terms Codes were added and revised
5.0 / 01/15/14 / Appendix A – New Source System “GWL” Great West Life
Appendix K – Added several new validation edits.
6.0 / 02/26/14 / Appendix G – New Document Types ‘AX’, ‘DK’
Item node ItemType element. Added new ItemType ‘AX’.
Added additional Due Date validation edits and edit on Funding.Account requiring the use of an expenditure account. Clarified validation edits related to Advancement Accounts. Added new edit to make a missing PaymentHandlingCode for a Check an error. Revised the withholding tax validation edits.
EFTBeneficiary.Country – Modified description to indicate that it is defaulted to USA if omitted or blank.
EFTBenficiary.TransactionHandling – Modified description to indicate that it is defaulted to X if blank.
Changed severity to Error from TBD for validation edits that prevent processing of monetary amounts in fractional amounts less than one cent.
6.1 / 03/11/2014 / Corrected severity and text description for several validation edits in Appendix K.
Modified description for EFTBeneficiary.BankAccountNumber to indicate that it is mandatory for ACHs and Domestic and International wires.

Table of Contents

Document Information and Revision History ii

Interface Overview 5

Interface Guidance 6

Interfacing using Files 6

Interfacing using Web Service 7

Schema Locations 7

Request Message 8

Sample Request Document 8

Request Detail Node Information 12

Acknowledgement Message 36

Sample Acknowledgement Message 36

Acknowledgement Detail Node Information 38

Appendices 44

Appendix A: Source System Codes 44

Appendix B: Payment Class Codes 45

Appendix C: Payment Type Codes 47

Appendix D: Payment Terms Codes 49

Appendix E: Tax Payment Addenda Requirements 50

Appendix F: Format Code Guidance 58

Appendix G: IES Source System Document Types 59

Appendix H: Non-IES Source System Document Types 60

Appendix I: Country Codes 61

Appendix J: Payment Due Date Rules 69

Appendix K: Interface Validation Edits 73

PTMS/IF APPR01 Agency Guide

Interface Overview

The Payment Request Interface is used by State agencies to initiate disbursement of funds by the Pennsylvania Treasury. Each payment request generates a payment voucher representing a disbursement to a specific recipient. Treasury can automatically consolidate certain vouchers into a single payment. Multiple payment requests can be transmitted in a single payment request interface document.

The required information can be transmitted as either an XML file or via a SOAP formatted web service call. After the information is received and processed, an acknowledgement is sent back with information on transactions received, processed and rejected. The acknowledgement also includes error messages for rejected transactions that can be used to review and correct the data for resubmission.

Interface Guidance

Interfacing using Files

File Naming Conventions:

Each file name must be unique.

2. Name should be in XXXXXXSRC<FREEFORM>YYYYMMDDHHMMSSmmm.xml format

· XXXXXX – The first 6 characters represent the interface name i.e. APPR01

· SRC – The next 3 characters represent the source system code i.e. IES.

· <FREEFORM> - Free form text, sender can add any value they wish. Leave blank if not in use. Length of field can be from 0-10 alphanumeric characters.

· YYYYMMDD - The date of the transmission in YYYYMMDD format i.e. 20120101.

· HHMMSS - The time of day when the transmission occurred; it’s a military time format i.e. 162412 for 4:24:12 PM.

· mmm - This is the milliseconds of the time when the transmission occurred. This is an optional field.

· .xml – This is the file extension.

Example File Names:

· APPR01IES20130101081235.xml – Minimum required in a file name.

· APPR01IES20130101081235123.xml – Includes millisecond.

· APPR01IESFFEX20130101081235123.xml – Includes freeform and milliseconds.

Interfacing using Web Service

Webservice Format:

SOAP XML

Webservice Limitations:

Additional documentation will be provided concerning the maximum number of payment requests to be included in a web service message.

Test WSDL:

Treasury will provide this to agencies that need to develop against a test instance of this interface.

Production WSDL:

T.B.D.

Schema Locations

Request:

Schema xsd can be found in the collaboration SharePoint portal.

Response:

Schema xsd can be found in the collaboration SharePoint portal.

Request Message

The Request Message is used to transmit requests for disbursements to Treasury. It is formatted as an XML document and may be submitted via web service or file. All Request Documents consist of a single document header containing control information and one or more payment request data modules consisting of the data elements necessary for creating a disbursement. Each payment request data module must be identified by a trace id that is unique to the submitting source system.

Sample Request Document

<?xml version="1.0"?>

APPR01Request xmlns="http://schemas.patreasury.gov/interface/schema/APPR01Request.v1"

<InterfaceIdentifierAPPR01</InterfaceIdentifier>

<SourceSystemCodeIES</SourceSystemCode>

<ControlCount1</ControlCount>

<ControlAmount100.00</ControlAmount>

</Control>

</DocumentHeader>

<TraceId</TraceId>

<OriginalTraceId</OriginalTraceId>

<PaymentClass</PaymentClass>

PriorityCode</PriorityCode

<RecipientType</RecipientType>

<RecipientId</RecipientId>

<RecipientLocation</RecipientLocation>

<TaxpayerId</TaxpayerId>

<PreConsolidationIndicator</PreConsolidationIndicator>

<VendorInvoiceId</VendorInvoiceId>

<VendorInvoiceDate</VendorInvoiceDate>

<SourceSystemReference</SourceSystemReference>

<DocumentType</DocumentType

<GrossPaymentAmount</GrossPaymentAmount>

<GrossEarningsAmount</GrossEarningsAmount>

<DueDate</DueDate>

<PaymentTerms</PaymentTerms

<PaymentTermsBasisDate</PaymentTermsBasisDate>

<DocumentFormat</DocumentFormat>

<DocumentVerificationValue</DocumentVerificationValue>

<DocumentURL</DocumentURL>

<BatchType</BatchType>

<BatchId</BatchId>

<BatchSequenceNumber</BatchSequenceNumber>

<ForceBatchProcessing</ForceBatchProcessing>

<PaymentNumber</PaymentNumber>

<PaymentType</PaymentType>

<PaymentMethod</PaymentMethod>

<SeparatePayment</SeparatePayment>

<PaymentHandlingCode</PaymentHandlingCode>

<PrintRemittance</PrintRemittance

<PaymentMessage</PaymentMessage>

<PayrollDeliveryBusinessArea</PayrollDeliveryBusinessArea>

<CheckMemoLine</CheckMemoLine

<LineTypeSequenceNumber</LineTypeSequenceNumber>

</Advice>

<SequenceNumber</SequenceNumber>

</ACHAddenda>

</Payment>

<RecipientNumber</RecipientNumber>

<NameOne</NameOne>

<NameTwo</NameTwo>

<Country</Country>

<StreetAddressOne</StreetAddressOne>

<StreetAddressTwo</StreetAddressTwo>

<City</City>

<State</State>

<PostalCode</PostalCode>

</Recipient>

<BeneficiaryNumber</BeneficiaryNumber>

<WireType</WireType>

<AgencyLocationCode</AgencyLocationCode

<DFIQualifier</DFIQualifier>

<DFI</DFI>

<BankAccountType</BankAccountType>

<BankAccountNumber</BankAccountNumber>

<IBAN</IBAN>

<BankName</BankName>

<Country</Country>

<StreetAddressOne</StreetAddressOne>

<StreetAddressTwo</StreetAddressTwo>

<City</City>

<State</State>

<PostalCode</PostalCode>

<PaymentDetailInformation</PaymentDetailInformation

<FurtherCreditToIndicator</FurtherCreditToIndicator

<BeneficiaryReference</BeneficiaryReference

</EFTBeneficiary>

<ItemNumber</ItemNumber>

<Description</Description>

<ItemAmount</ItemAmount>

<ItemId</ItemId>

<ItemLineNumber</ItemLineNumber

<ItemScheduleNumber</ItemScheduleNumber

<ItemDate</ItemDate>

<ItemReference</ItemReference>

<VendorId</VendorId>

<VendorLocation</VendorLocation>

<VendorTaxpayerId</VendorTaxpayerId

<SCDUNoncustodialParentName</SCDUNoncustodialParentName>

<SCDUNoncustodialParentSSN</SCDUNoncustodialParentSSN>

<SCDUEmploymentTerminated</SCDUEmploymentTerminated>

<SCDUMedicalSupportIndicator</SCDUMedicalSupportIndicator>

<SCDUFIPSCode</SCDUFIPSCode>

<Issuer</Issuer>

<AdvancementAccountBusinessArea</AdvancementAccountBusinessArea

<AdvancementAccountCode</AdvancementAccountCode

<PayeeNameOne</PayeeNameOne>

<PayeeNameTwo</PayeeNameTwo>

<AuditLookupType</AuditLookupType>

<AuditLookupId</AuditLookupId>

<AccountingReference</AccountingReference

<DocumentNumber</DocumentNumber>

<Description</Description>

<Type</Type>

<Format</Format>

<VerificationValue</VerificationValue>

<URL</URL>

</SupportingDocument>

<FundingLineNumber</FundingLineNumber>

<Description</Description>

<Amount</Amount>

<Fund</Fund>

<Department</Department

<Appropriation</Appropriation

<FiscalYear</FiscalYear

<Account</Account>

</Funding>

</Item>

</Header>

</PaymentRequest>

</APPR01Request

Request Detail Node Information

Node Name / APPR01Request / Parent Node
Min Occur / 1 / Max Occurs / 1
Description / Root node of the XML document.
Element Name / Data Type / Size / Format / Required / Description
DocumentHeader / Element / Y / This is the standard inbound request header that must be present once on every inbound interface document.
PaymentRequest / Element / Y / Inbound payment request information.
Node Name / DocumentHeader / Parent Node / APPR01Request
Min Occur / 1 / Max Occurs / 1
Description / The DocumentHeader module contains control and detail information for the interface document. There will be one DocumentHeader module per interface document.
Element Name / Data Type / Size / Format / Required / Description
Control / Element / Y / The Control element holds control data for the document.
Node Name / Control / Parent Node / DocumentHeader
Min Occur / 1 / Max Occurs / 1
Description / Provides control information for the document, including: the source system transmitting the document, a unique identifier for the document in the source system, the number of payment requests in the document, and the total amount of requested payments.
Attribute Name / Data Type / Size / Format / Required / Description
class / String / 1 / Upper / Y / Value must always be “R”.
Element Name / Data Type / Size / Format / Required / Description
InterfaceIdentifier / String / 6 / Upper / Y / Always APPR01.
SourceSystemCode / String / 3 / Upper / Y / The three-character abbreviation of the transmitting source system. Values will be provided by Treasury. See Appendix A for currently defined Source System Codes.
DocumentIdentifier / String / 36 / Mixed / N / Unique identifier used by the source system to identify the interface document. This value will be echoed back in the Acknowledgement response.
DocumentDateTime / String / N / Date and time when the request was transmitted. DocumentDateTime is a datetime. If this value is not populated then the system will default date and time to the time Treasury loads the data.
Format is 2008-10-31T15:07:38.687500-05:00
ControlCount / Integer / 10 / Y / Total count of Payment Requests contained in the file or web service request.
ControlAmount / Decimal / 28 / 23.3 / Y / Total amount of all payments requested in the file or web service request.
Node Name / PaymentRequest / Parent Node / APPR01Request
Min Occur / 1 / Max Occurs / Unbounded
Description / The PayentRequest module contains the information to initiate a single disbursement to a recipient. There may be multiple PaymentRequests modules per interface document.
Element Name / Data Type / Size / Format / Required / Description
Header / Element / Y / The Header record element for a Payment Request.
Node Name / Header / Parent Node / PaymentRequest
Min Occur / 1 / Max Occurs / 1
Description / The Header record element. Each Payment Request adheres to a header, line item and accounting distribution hierarchy. This describes information contained in the header. There can be only one header per Payment Request.
Attribute Name / Data Type / Size / Format / Required / Description
class / String / 1 / Upper / Y / Value must always be “R”.
Element Name / Data Type / Size / Format / Required / Description
TraceId / String / 36 / Mixed / Y / Source system assigned value that uniquely identifies each
Payment Request. This number serves as the unique identifier of the Payment Request throughout its processing in the Treasury systems. It must be unique within a source system. A Trace Id cannot be reused in the Payment Request Interface once it has been loaded into the Treasury system.
If there are errors while processing the Payment Requests, the TraceId will enable the agency to identify the Payment Request on the response to be able to resolve the error and resubmit it for processing.
OriginalTraceId / String / 36 / Mixed / N / Identifies the original Payment Request for a resubmission when the original was rejected by Treasury’s auditing review and is resubmitted as a new Payment Request.
PaymentClass / String / 4 / Upper / Y / Identifies the specific type of payment request. This See Appendix B for the list of valid values.
PriorityCode / String / 1 / Upper / N / Used to indicate the payment requires expedited processing. Valid values are:
1 – Must be paid on the current or next business day.
2 – Must be paid within 5 business days.
R – Regular (default). Expedited processing not required.
Use when the DueDate is within 5 business days of the transmission date and the Payment Request is a high priority payment as classified by Treasury’s Fiscal Review bureau.