TECHNICAL DOCUMENT. Prepaid Program Batch File Interface Specification. VERSION 1.0b DRAFT 3 DATE

Transcription

1 TECHNICAL DOCUMENT Prepaid Program Batch File Interface Specification VERSION 1.0b DRAFT 3 DATE

2 Introduction This document is intended to define the batch file interface used for management of DCBank prepaid services and products, including payments, wallet/account management, and issuance and reload functionality for card-based (closed-loop, gift, debit, MasterCard and VISA) products. Throughout the following text, the terms 'wallet' and 'account' are used somewhat interchangeably; both refer to the pool of funds to which cards are attached, but in general terms only actual bank account products are referred to as an 'account', with 'wallet' representing nonbank products. The wallet/account distinction has little impact on batch functions, other than certain functions only being valid for actual bank-grade products. For technical support with the contents of this specification, please contact your account manager, or Page 1 of 14

3 Batch File Operating Procedures 1. Note that under no circumstances are customers permitted to store DCBank card numbers, whether in cleartext or encrypted form. Users will be permitted to store a SHA- 1 hash of any cards they process, as well as a truncated (first 6 and last 4 digits only) cardnumber for purposes of display to users. Wallet and account numbers (including bank account numbers) as well as 13-digit card serial numbers are not considered sensitive data, and may be stored using all reasonable security and privacy precautions. 2. When a batch file is received, the first step in processing each line is to validate the presence and format of all required columns. Only once all columns are verified is the line processed; otherwise the line is rejected with the first detected error parameter as the failure reason. 3. Errors in individual lines will not prevent valid lines in the file from processing - meaning users must be prepared to handle cases where a file was partially processed (i.e. some records were successful, while some records were not). Page 2 of 14

4 Request Files Files submitted to DCBank should be named according to the following format: PCSV0100mmmmmYYMMDDnnn.txt Where: - 'PCSV' is a fixed value identifying this file as a Prepaid comma-separated value file is a fixed value indicating file format major/minor version (currently 1.00) - 'mmmmm' represents a five-digit number assigned by DCBank and provided by your account representative, which will be used to identify your organization as the originator of the file (all files generated by your organization must use the correct value) - 'YYMMDD' represents the date the file was generated - 'nnn' is a three-digit number, which must be unique within a given 'YYMMDD' value; this is intended to allow users to submit multiple files per day (for ease of tracking, it is recommended that users start each day with file number '001', and increment with each subsequent file). Files should not contain headers or footers; each line within the file will always begin with a fourcharacter "RowType" value, which is made up of a two-character function identifier followed by a two-character major/minor revision number for that record type; how the remainder of the line is structured will vary by RowType, as outlined below. Receipt Files Once submitted files are processed by DCBank, receipt files will be generated, named according to the following format: PREC0100mmmmmYYMMDDnnn.txt Where: - 'PREC' is a fixed value identifying this file as a Prepaid Receipt file is a fixed value indicating file format major/minor version (currently 1.00) - 'mmmmm', 'YYMMDD' and 'nnn' will all be echoed from the original file Receipt files will contain one line for each entry from the source file, as detailed below; input lines which are not in a recognized format will have a receipt RowType of "INV00". Receipt lines will appear in the same order as entries from the source file (providers are encouraged to use distinct UserReference values if more exact request-to-response mapping is required). Page 3 of 14

5 Data Dictionary Glossary The following terms are used throughout this document: - PAN: Primary Account Number, also referred to as cardnumber, digits in length - BIN: Bank Identification Number, the leading digits of a cardnumber which identify the bank issuing the card; variable length (generally the first 6 to 10 digits of a cardnumber) Field formats Throughout the service reference below, field values are described as follows: - Alpha (x-y): A-Z and a-z characters only, between x and y characters in length - AN (x-y): Alphanumeric characters only, between x and y characters in length - ANS (x-y): Alphanumeric and special characters only, between x and y characters in length; permitted 'special' characters will be specifically identified - Base64: Base-64-encoded string (hexadecimal characters plus /+= characters only) - Datetimeoffset: String representation of a UTC time, in format "YYYY-MM-DD hh:mm:ssz" (e.g. " :30:00Z") - Decimal (x,y): Decimal value, maximum x total length, maximum y decimal places (e.g. maximum value for decimal(6,3) would be ) - GUID: String representation of a globally-unique identifier value (e.g. "8B8696C4-FD0D- 4D60-B A") - Hash (SHA1): String representation of a SHA1 binary hash value must be exactly 40 hexadecimal characters, or optionally the characters "0x" followed by exactly 40 hexadecimal characters (see Appendix A for further details on hash value generation) - Hash (SHA256): String representation of a SHA256 binary hash value must be exactly 64 hexadecimal characters, or optionally the characters "0x" followed by exactly 64 hexadecimal characters - Integer (x): Integer value (whole number), maximum value x (optional), leading zeroes ignored - Money ($x.xx): Money value (at least one digit followed by decimal and exactly two decimal places), maximum value $x.xx (optional); leading zeroes as well as $ character, if present, are ignored - Numeric (x-y): Numeric characters only, between x and y characters in length - String (x): Freeform text, maximum length x (valid for responses only) Page 4 of 14

6 "Required" flags Fields will use one of the following to indicate whether the field is a required element: - Required: Must be provided - Optional: May or may not be provided - Approved: Required if request is approved (valid for responses only) - Conditional: May or may not be required (conditions defined in associated comments) - Invalid: Should not be provided (i.e. reserved for future use) Columns marked as optional or conditional can be left blank; trailing blank fields can be excluded completely if desired, but all columns must be included as placeholders if they are followed by a non-blank value in a later column. For example, in a file with two required columns and three optional columns: - "COL1,COL2,COL3": Acceptable: COL4, COL5 excluded - "COL1,COL2,COL3,,": Acceptable: COL4, COL5 included and left blank - "COL1,COL2,,,COL5": Acceptable: Placeholders for COL3 and COL4 included - "COL1,COL2,COL5": Not acceptable: COL5 value will be interpreted as COL3 Page 5 of 14

7 Card Product Management Requests Reload Card RowType 'RC' The Reload Card function allows a pre-existing card to have funds added to its available balance. The card must be valid, and must be registered to the requesting merchant. Column 2 can be either a SHA1 PANHash value OR a 13-digit card serial number. Note that reload requests for cards which are invalid, non-reloadable, or have been disabled (or for cards associated with clients with expired or invalid identification values on file) will be rejected. Parameter Required Format Comments Request File RowType Required AN (4) "RC10", for "Reload Card version 1.0" PANHash Required Hash (SHA1) Identifies the card to be reloaded - OR - SerialNumber - OR - Numeric (13) LoadAmount Required Money Reload amount (gross amount to be credited to card balance before fees) SourceOfFunds Required Integer Identifier for source of LoadAmount funds (see Appendix B) UserReference Optional AN (1-10) Optional value, echoed in response UserLoggingData Optional AN (1-26) User-defined value stored in database for use in reporting (optional) CustomFee Optional Money Amount to be deducted from LoadAmount before crediting card balance; see note 1. Receipt File RowType Required AN (4) Echoed from request ResponseCode Required Integer Zero success, non-zero failure ResponseMessage Required String (255) Descriptive response message for troubleshooting UserReference Conditional AN (1-10) Echoed from request, if present TransactionTimestamp Approved String (14) YYYYMMDDHHMMSS timestamp generated from card system ReferenceNumber Approved Integer Unique identifier for reload transaction EndingBalance Approved Money Balance on card at completion of operation Note 1: CustomFee may be blank or zero; if provided, the total amount of CustomFee plus any fees charged automatically by DCBank must be less than or equal to LoadAmount (i.e. the net amount of a reload request cannot be less than zero). CustomFee charges will be logged and displayed as a separate transaction on cardholder statements and reports. Page 6 of 14

8 Money Transfer Requests Create Transfer RowType 'CT' The Create Transfer function allows new "money transfer" transactions to be created and delivered to a recipient; note that at present only bulk Interac etransfer transactions are supported. Parameter Required Format Comments Request File RowType Required AN (4) "CT10", for "Create Transfer version 1.0" TransferType Required Integer Transfer type being sent. As of this writing, only TransferType 1 (Interac etransfer) is supported. DeliveryType Required Integer Method of transfer delivery to be used. As of this writing, only DeliveryType 1 (bulk) or 2 (priority bulk) are supported. ReceiverPartyType Required Integer 'Party type' code for recipient. As of this writing, only PartyType 1 ( address) is supported. ReceiverAddress Required ANS (1-80) Recipient address, validation rules depend on ReceiverPartyType. As of this writing, must be a valid address. ReceiverName Required ANS (1-80) Name of individual receiving transfer; alpha, space, hyphen and apostrophe characters only TransferAmount Required Money Amount of funds to send TransferMemo Optional ANS (1-80) Optional message to be sent with transfer; alphanumeric, space and the following characters only:.!@/;:'=$?*() SecurityQuestion Required ANS (1-120) Text of security question to be presented to receiver; format and allowed characters as TransferMemo field. As of this writing, this field is required as Interac etransfer requires it; will become Conditional if other transfer types are added. SecurityAnswer Required ANS (3-25) Answer to security question, only alphanumeric and hyphen characters permitted. As of this writing, this field is required as Interac etransfer requires it; will become Conditional if other transfer types are added. See note 1. UserReference Optional AN (1-10) Optional value, echoed in response Receipt File RowType Required AN (4) Echoed from request ResponseCode Required Integer Zero success, non-zero failure ResponseMessage Required String (255) Descriptive response message for troubleshooting UserReference Conditional AN (1-10) Echoed from request, if present TransactionTimestamp Approved String (14) YYYYMMDDHHMMSS timestamp generated from card system ReferenceNumber Approved String (12) Unique identifier for transfer, formatted as "TC" followed by 10 digit numeric value Page 7 of 14

9 Note 1: For Interac etransfer requests, formatting on the SecurityAnswer field will be strictly enforced (alphanumeric and hyphen characters only). Permitted characters allowed in this field can vary based on the recipient's financial institution, as such DCBank enforces the narrowest possible set of results to avoid creating transfers which cannot be claimed by individuals using certain institutions. Page 8 of 14

10 Create EFT RowType 'CE' The Create EFT function allows new EFT/PAD (pre-authorized debits or credits) to be created. Parameter Required Format Comments Request File RowType Required AN (4) "CE10", for "Create EFT version 1.0" CustomerName Required ANS (1-30) Name of target account owner; alphanumeric, space, hyphen, period and apostrophe characters only Bank Required Numeric (3-4) Numeric identifier of institution to which Transit belongs Transit Required Numeric (5) Numeric identifier of bank branch to which Account belongs Account Required Numeric (4-12) Account number to debit/credit Amount Required Money Amount of transfer Type Required Alpha (1) Either "C" (credit, i.e. push Amount to Account) or "D" (debit, i.e. pull Amount from Account) CustomerID Conditional ANS (20) Unique identifier for this customer; alphanumeric, space, hyphen and period characters only. See note 1. TransactionID Conditional Numeric (1-9) Numeric identifier for this transaction; see note 1. EffectiveDate Required Numeric (8) YYYYMMDD payment will be effective (cannot be past-dated) Comment Optional ANS (30) Optional value to be applied as "originator" name for this payment (depending on FI, will typically show on account statement for this transaction). Alphanumeric, space, hyphen and period characters only. UserReference Optional AN (1-10) Optional value, echoed in response Receipt File RowType Required AN (4) Echoed from request ResponseCode Required Integer Zero success, non-zero failure ResponseMessage Required String (255) Descriptive response message for troubleshooting UserReference Conditional AN (1-10) Echoed from request, if present TransactionTimestamp Approved String (14) YYYYMMDDHHMMSS timestamp generated from EFT system ReferenceNumber Approved Integer Unique identifier for transfer Note 1: CustomerID and TransactionID are used for purposes of duplicate transmission checking (together with bank/transit/account and amount), as well as some reporting functions. It is highly recommended that distinct values are provided for these fields to prevent false positives on duplicate checks. Page 9 of 14

11 Appendix A Example Data PANHash values As noted in the data dictionary above, PANHash fields are to be populated with a string representation of a SHA1 binary hash of the cardnumber (PAN); they must be exactly 40 hexadecimal characters, or optionally the characters "0x" followed by exactly 40 hexadecimal characters. Examples of hash values: PAN PANHash "0x65C106640B4EDD589AF8298D10562BF638DB399E" "0xEE62999DC26707FA8DE9963B46088A2776DB106D" "0x E23C0460BFC7EE D716A3D00C34" "0x5B1FE842A5A677DAB28FDE98D887325B5D9117D0" "0x40CF F2DFDDF19EB2898F99E3F2329DAE1" "0x E4C4E91EF34AB0C089A2A9BD27CBDC89C" "0xFB7B86D61BD34B6B59285C6241ACFF4B5DF79EC8" Page 10 of 14

12 Appendix B Reference Files As noted above, these files are provided (and may be updated from time-to-time) in order to provide users with all necessary reference values for batch file interfaces. Filenames will include the date on which they were generated; users should always ensure they are using the most recent version of all reference files. Note that unlike input files, reference files WILL have header records. SourceOfFunds This file provides values for the "SourceOfFunds" parameter associated with amounts being loaded to cards/accounts/etc. Files will be named PCSVREF_SOF_YYMMDD.txt, and will contain: SourceCode Required Integer Numeric identifier for this 'source of funds' value SourceDesc Required String Descriptive string for this value (for information purposes only) AccountPurpose This file provides values for the "AccountPurpose" parameter associated with new activations. Files will be named PCSVREF_AP_YYMMDD.txt, and will contain: AccountPurpose Required Integer Numeric identifier for this 'account purpose' value AccountPurposeDesc Required String Descriptive string for this value (for information purposes only) Occupation This file provides values for the "Occupation" parameter associated with card/account holders. Files will be named PCSVREF_OCC_YYMMDD.txt, and will contain: OccupationID Required Integer Numeric identifier for this occupation OccupationDesc Required String Descriptive string for this value (for information purposes only) Page 11 of 14

13 IDType This file (named PCSVREF_IDS_YYMMDD.txt) provides a listing of identification types which can be used when activating or updating a client record, including information on validation rules and eligibility, as follows: IDType Required Integer Numeric identifier for this identification type IDDesc Required String Descriptive string for this ID type (for information purposes only) IsPrimary Required Integer Indicates whether this IDType is (1) or is not (0) valid as 'primary' identification IsPhoto Required Integer Indicates whether this IDType is (1) or is not (0) valid as 'photo' identification IssueLocationRequired Required Integer Indicates whether state/province of issue is required (1) or optional (0) IssueDateRequired Required Integer Indicates whether date of issue is required (1) or optional (0) ExpiryDateRequired Required Integer Indicates whether expiration date is required (1) or optional (0) AccountClassID This file (named PCSVREF_ACC_YYMMDD.txt) provides a listing of account classes which are valid for activation, along with additional configuration information related to each class, as follows: AccountClassID Required Integer Numeric identifier for this account class AccountClassDesc Required String Descriptive string for this account class (for information purposes only) AccountType Required Integer Indicates debit (20) or MasterCard/Visa (30) IsBankAccount Required Integer Indicates whether this account class is a bank account product (1) or non-bank wallet product (0) RequireCustomerInfo Approved Integer Indicates whether customer name, DOB, address, etc. will be required (1) or not (0) RequirePrimaryID Approved Integer Indicates whether primary ID will be required (1) or optional (0) Page 12 of 14

14 RequirePrimaryPhoto Approved Integer Indicates whether primary ID must be photo ID (1) or not (0) RequireSecondaryID Approved Integer Indicates whether secondary ID will be required (1) or optional (0) RequireSecondaryPhoto Approved Integer Indicates whether secondary ID must be photo ID (1) or not (0) BINID This file (named PCSVREF_BIN_YYMMDD.txt) provides a listing of BIN values which can be used for card-based requests, as follows: BINID Required Integer Numeric identifier for this BIN BIN Required Numeric Leading digits of this BIN CardType Required Integer 1 = Debit, 2 = MasterCard, 3 = Visa PANLength Required Integer Total number of digits in PANs using this BIN StateProvID This file (named PCSVREF_PROV_YYMMDD.txt) provides a listing of state/province codes which can be used for cardholder address or identification, as follows: StateProvID Required Integer Numeric identifier for this state/province StateProvShortName Required Alpha (2) Alpha code for this state/province StateProvName Required String Full name of state/province TransferType, DeliveryType, PartyType This file (named PCSVREF_MTGRID_YYMMDD.txt) provides all valid combinations of TransferType, DeliveryType and PartyType for use in money transfer requests: TransferType Required Integer Identifier for transfer type to be sent TransferTypeDesc Required String Descriptive string/name of transfer type TransferTypeLongDesc Required String Long-form description of transfer type DeliveryType Required Integer Identifier for method of delivery to be used DeliveryTypeDesc Required String Descriptive string/name of delivery type PartyType Required Integer Identifier for party type Page 13 of 14

15 PartyTypeDesc Required String Description of this party type PartyTypeValidation Required String Regular expression against which addresses belonging to this party type will be checked Note that any given TransferType, DeliveryType and PartyType value can and will appear multiple times in this file; only the combination of all three of TransferType, DeliveryType and PartyType will be unique. Page 14 of 14

16 Revision History Version Date Changes 1.0b DRAFT /09/27 Reformatted document; fixed formatting of ReferenceNumber in CT10 receipt file 1.0b DRAFT /08/28 Added support for Create EFT (CE10) function, updated CT10 comments to note priority bulk now supported 1.0b DRAFT /09/14 Added support for Create Transfer function, reference file