Gateway Specification Version 7.3 | Update 1/16/19 · iPay Gateway API Guide for XML Gateway...

iPay Gateway API Guide for XML Gateway Specification

Version 7.3 | Update 1/16/19

Notice: This document contains confidential, trade secret information, which is proprietary to Planet

Payment, Inc., and its subsidiaries (collectively Planet Payment®) and is provided solely for recipient’s

use in connection with recipient’s participation in one of Planet Payment’s Processing Programs. Planet

Payment reserves the right to make changes to specifications at any time and without notice. The

information furnished by Planet Payment in this publication is believed to be accurate and reliable as of

the date of its release; however, no responsibility is assumed by Planet Payment for its use, nor for

infringements of patents or other rights of third parties resulting from its use, nor for the violation,

misinterpretation, or misapplication of any laws, or any regulation of any credit card association

including Visa, Inc., or MasterCard, Inc. No general license is granted under any patents, copyrights or

other intellectual property rights owned by Planet Payment and the recipient is only granted an end user

license to use this information for the purposes of participating in one of Planet Payment’s Processing

Programs, pursuant to an agreement with Planet Payment or one of its authorized Program partners. All

modifications or improvements to any of the information and specifications in this document shall

belong exclusively to Planet Payment, Inc. No unauthorized copying, disclosure or use of this document

is permitted without the express written consent of Planet Payment, Inc. Planet Payment®, Pay in Your

Currency®, BuyVoice®, iPAY® and the globe-and-ring logo are trademarks and/or registered

trademarks of Planet Payment, Inc.© 2018 Planet Payment, Inc. All Rights Reserved

Contents

CHAPTER 1 ..................................................................................................................... 1

Introduction to the iPay XML API ........................................................................................ 1 Transaction Components................................................................................................... 1

What the Components do ........................................................................................... 2 Encryption Requirements .................................................................................................. 2

Message-Level Data Encryption ................................................................................... 2 Valid Characters ................................................................................................................ 3

Valid Data Characters ................................................................................................... 3 XML Character Encoding .............................................................................................. 4

Example XML Character Encoding ............................................................................. 4 Invalid Data ................................................................................................................... 5

Base64 Encoding .............................................................................................................. 5 The Base64 Alphabet ................................................................................................... 5

Modulus Checks ................................................................................................................ 6 Modulus 10/Luhn Algorithm .......................................................................................... 6 Modulus 9 ..................................................................................................................... 7

Modulus 9 Example .................................................................................................... 7 XML Transaction Transmission ......................................................................................... 8

Transmitting XML Transactions..................................................................................... 8 Sample Request ........................................................................................................... 9 Sample Response ........................................................................................................ 9 Connection Restrictions .............................................................................................. 10

Batch File Processing ...................................................................................................... 10 Batch Transmission .................................................................................................... 10 Batch File Size ............................................................................................................ 11 Batch File Layouts ...................................................................................................... 11

REQUESTS .............................................................................................................. 11 Batch Request Requirements ................................................................................... 11 RESPONSES ........................................................................................................... 12 Batch Response Requirements ................................................................................ 12

Batch File Naming Conventions .................................................................................. 12 Valid Alphanumeric Characters for Batch File Names .............................................. 13

File Compression ........................................................................................................ 14 Supported Compression Formats ............................................................................. 14

CHAPTER 2 ................................................................................................................... 15

Transaction Data ................................................................................................................ 15 Transaction Elements ...................................................................................................... 15

Example Transaction .................................................................................................. 15 Request Attributes ...................................................................................................... 16 Example Requests ...................................................................................................... 16

Example FMT = 0 without any Encoding ................................................................... 16 Example FMT = 1 without any Encoding ................................................................... 17 Example Encoding = 0 .............................................................................................. 17 Example Encoding = 1 .............................................................................................. 17

Field Acceptance ........................................................................................................ 18 Sample SERVICE/SERVICE_FORMAT ................................................................... 18

Request Elements ........................................................................................................... 18 Field Elements ............................................................................................................ 18

AAV Request Element ..................................................................................................... 23 ACCOUNT Request Element .......................................................................................... 24 ACCOUNT_ID Request Element ..................................................................................... 25 ACCOUNT_NUMBER Request Element ......................................................................... 26 ACCOUNT_SUBTYPE Request Element ........................................................................ 27 ACCOUNT_TYPE Request Element ............................................................................... 28 ACCOUNT_VALIDATION Request Element.................................................................... 28 ADDRESS Request Element ........................................................................................... 29 AMOUNT Request Element ............................................................................................. 30 APPROVAL_CODE Request Element ............................................................................. 31 AUTH_SOURCE_CODE Request Element ..................................................................... 31 BATCH_ID Request Element .......................................................................................... 32 BILLING_DESCRIPTION Request Element .................................................................... 33 BILLING_ID Request Element ......................................................................................... 33 BILLING_METHOD Request Element ............................................................................. 34 BILLING_NAME Request Element .................................................................................. 35 BILLING_TRANSACTION Request Element ................................................................... 35 CHECK_NUMBER Request Element .............................................................................. 36 CITY Request Element .................................................................................................... 37 CLIENT_ID Request Element .......................................................................................... 37 CLIENT_IP Request Element .......................................................................................... 38 CONSUMER_VALIDATION Request Element ................................................................ 38 COUNTRY Request Element .......................................................................................... 40 CURRENCY_CODE Request Element ............................................................................ 40 CURRENCY_INDICATOR Request Element................................................................... 41

Pay Gateway API Guide for XML

CVV Request Element ..................................................................................................... 42 EFFECTIVE_DATE Request Element ............................................................................. 43 EFFECTIVE_TYPE Request Element ............................................................................. 43 EMAIL_ADDRESS Request Element .............................................................................. 44 ENTRY_MODE Request Element ................................................................................... 45 EXPIRATION Request Element....................................................................................... 46 FIRST_NAME Request Element ...................................................................................... 46 FRAUD_VALIDATION Request Element ......................................................................... 47 FREQUENCY_DATE Request Element .......................................................................... 48 FREQUENCY_DAY Request Element............................................................................. 49 FREQUENCY_INTERVAL Request Element................................................................... 50 FREQUENCY_MONTH Request Element ....................................................................... 51 FREQUENCY_TYPE Request Element ........................................................................... 52 GOODS_INDICATOR Request Element ......................................................................... 53 IMAGE Request Element................................................................................................. 54 INITIAL_AMOUNT Request Element ............................................................................... 55 LAST_FOUR Request Element ....................................................................................... 55 LAST_NAME Request Element ....................................................................................... 56 LOCAL_DATE Request Element ..................................................................................... 57 LOCAL_TIME Request Element ...................................................................................... 57 MARKET_SPECIFIC_ID Request Element ..................................................................... 58 MEMBER_NUMBER Request Element ........................................................................... 58 MERCHANT_CITY Request Element .............................................................................. 59 MERCHANT_NAME Request Element ............................................................................ 59 MERCHANT_PHONE Request Element ......................................................................... 60 MERCHANT_STATE Request Element ........................................................................... 61 MERCHANT_URL Request Element ............................................................................... 62 MIN_PAYMENT_AMOUNT Request Element ................................................................. 62 MINUTES Request Element ............................................................................................ 63 MVV Request Element .................................................................................................... 63 OPERATOR Request Element ........................................................................................ 64 P3DS_PA_REQUEST Response Element ...................................................................... 64 P3DS_TRANSACTION_ID Request Element .................................................................. 65 PHONE Request Element ............................................................................................... 66 PIN Request Element ...................................................................................................... 66 POSTAL_CODE Request Element .................................................................................. 67 PROCESS_RESIDUAL Request Element ....................................................................... 67 PRODUCT_BILLING Request Element ........................................................................... 68 PRODUCT_DESCRIPTION Request Element ................................................................ 69 PRODUCT_ID Request Element ..................................................................................... 69


PRODUCT_NAME Request Element .............................................................................. 70 PRODUCT_URL Request Element ................................................................................. 71 QUERY_TYPE Request Element .................................................................................... 71 RETRY_COUNT Request Element ................................................................................. 72 RETRY_INTERVAL Request Element ............................................................................. 73 ROUTING_NUMBER Request Element .......................................................................... 73 SCHEDULE_CHARGE_DATE Request Element ............................................................ 74 SCHEDULE_DESCRIPTION Request Element ............................................................... 76 SCHEDULE_END_AMOUNT Request Element .............................................................. 76 SCHEDULE_END_COUNT Request Element ................................................................. 77 SCHEDULE_END_DATE Request Element .................................................................... 77 SCHEDULE_ID Request Element ................................................................................... 78 SCHEDULE_START_DATE Request Element ................................................................ 79 SCHEDULE_TYPE Request Element.............................................................................. 79 SELLER_ACCOUNTID Request Element ....................................................................... 80 SELLER_ACTUAL_NAME Request Element .................................................................. 81 SELLER_BUSINESSNAME Request Element ................................................................ 81 SELLER_CITY Request Element .................................................................................... 82 SELLER_COUNTRY_CODE Request Element ............................................................... 82 SELLER_EMAIL_ADDRESS Request Element ............................................................... 83 SELLER_MCC Request Element .................................................................................... 83 SELLER_POSTAL_CODE Request Element .................................................................. 84 SELLER_REGION Request Element .............................................................................. 84 SELLER_STREET Request Element .............................................................................. 85 SELLER_TELEPHONE Request Element ....................................................................... 85 SEQUENCE_NUMBER Request Element ....................................................................... 86 SERVICE Request Element ............................................................................................ 86 SERVICE_FORMAT Request Element ............................................................................ 87 SERVICE_SUBTYPE Request Element .......................................................................... 88 SERVICE_TYPE Request Element ................................................................................. 89 SESSION_ID Request Element ....................................................................................... 90 SHIP_ADDR1 Request Element ...................................................................................... 91 SHIP_ADDR2 Request Element ...................................................................................... 91 SHIP_CITY Request Element .......................................................................................... 92 SHIP_COUNTRY Request Element ................................................................................ 92 SHIP_PHONE Request Element ..................................................................................... 93 SHIP_POSTAL Request Element .................................................................................... 93 SHIP_STATE Request Element ...................................................................................... 94 SITE Request Element .................................................................................................... 94 STATE Request Element................................................................................................. 95


TAX_AMOUNT Request Element .................................................................................... 96 TERMINAL_ID Request Element ..................................................................................... 96 TICKET Request Element ............................................................................................... 97 TIP_AMOUNT Request Element ..................................................................................... 97 TRACK_DATA Request Element ..................................................................................... 98 TRANSACTION_ID Request Element ........................................................................... 100 TRANSACTION_INDICATOR Request Element ........................................................... 101 TRIAL_AMOUNT Request Element ............................................................................... 103 UP_COMMODITYDISCOUNT Request Element ........................................................... 104 UP_COMMODITYNAME Request Element ................................................................... 104 UP_COMMODITYQUANTITY Request Element ........................................................... 105 UP_COMMODITYUNITPRICE Request Element .......................................................... 105 UP_COMMODITYURL Request Element ...................................................................... 106 UP_CUSTOMERNAME Request Element ..................................................................... 106 UP_DEFAULTBANKNUMBER Request Element .......................................................... 107 UP_DEFAULTPAYTYPE Request Element ................................................................... 107 UP_FRONTENDURL Request Element ........................................................................ 108 UP_TRANSFERFEE Request Element ......................................................................... 109 USER_DATA Request Element ..................................................................................... 110 VERBOSE_RESPONSE Request Element ................................................................... 111 XID Request Element .................................................................................................... 112

CHAPTER 3 ................................................................................................................. 113

Transaction Response Messages ................................................................................... 113 Response Elements ...................................................................................................... 113 AAV Response Element ................................................................................................ 117 AAV_RESPONSE Response Element........................................................................... 117 ACCOUNT_DESCRIPTION Response Element ............................................................ 118 ACCOUNT_ID Response Element ................................................................................ 119 AMOUNT Response Element ........................................................................................ 120 APPROVAL_CODE Response Element ........................................................................ 120 ARC Response Element ................................................................................................ 121 AVS_RESPONSE Response Element........................................................................... 125 BATCH_ID Response Element ...................................................................................... 126 BILLING_ID Response Element .................................................................................... 126 CARD_TYPE Response Element .................................................................................. 126 CARDHOLDER_AMOUNT Response Element ............................................................. 127 CARDHOLDER_CURRENCY_CODE Response Element ............................................ 127 CLIENT_ID Response Element ..................................................................................... 128 COMMERCIAL_RESPONSE Response Element .......................................................... 128


COMPANY_KEY Response Element ............................................................................ 129 CVV_RESPONSE Response Element .......................................................................... 129 EXCHANGE_RATE Response Element ........................................................................ 130 FINANCIAL_TRAN_ID Response Element .................................................................... 130 FRAUD_AUTO Response Element ............................................................................... 131 FRAUD_ERROR(S) Response Element ........................................................................ 131 FRAUD_GEOX Response Element ............................................................................... 132 FRAUD_KAPT Response Element ................................................................................ 132 FRAUD_KYCF Response Element ................................................................................ 133 FRAUD_REAS Response Element ............................................................................... 133 FRAUD_REGN Response Element ............................................................................... 134 FRAUD_RULE(S) Response Element ........................................................................... 134 FRAUD_SCOR Response Element ............................................................................... 135 FRAUD_SESS Response Element ................................................................................ 135 FRAUD_TRAN Response Element ............................................................................... 135 FRAUD_VELO Response Element ................................................................................ 136 FRAUD_WARNING(S) Response Element ................................................................... 136 FRC Response Element ................................................................................................ 137 FXASSURED_MARKUP Response Element................................................................. 137 LOCAL_DATE Response Element ................................................................................ 138 LOCAL_TIME Response Element ................................................................................. 138 MRC Response Element ............................................................................................... 139 P3DS_ACS_URL Response Element ............................................................................ 141 P3DS_ARS Response Element ..................................................................................... 141 P3DS_CARD_ENROLLED Response Element ............................................................. 141 P3DS_PA_RESPONSE Response Element .................................................................. 142 P3DS_SRS Response Element ..................................................................................... 143 P3DS_TRANSACTION_ID Response Element ............................................................. 143 PRODUCT_ID Response Element ................................................................................ 143 PYC_EXCHANGE_RATE Response Element ............................................................... 144 PYC_RATE_MARKUP Response Element ................................................................... 144 RATE(S) Response Element ......................................................................................... 145 RESPONSE_TEXT Response Element ......................................................................... 146 SCHEDULE_ID Response Element .............................................................................. 147 SEQUENCE_NUMBER Response Element .................................................................. 147 TERMINAL_ID Response Element ................................................................................ 148 TRANSACTION_ID Response Element ........................................................................ 148 TRANSACTION_RESPONSECODE Response Element .............................................. 149 TRANSACTION_RESPONSEMESSAGE Response Element ....................................... 149 TRANSACTION_RESULTTYPE Response Element ..................................................... 150


UP_ACTIONURL Response Element ............................................................................ 150 UP_ORDERNUMBER Response Element .................................................................... 150 UP_PAYLOAD Response Element ................................................................................ 151 UP_SETTLEDATE Response Element.......................................................................... 151 XID Response Element ................................................................................................. 152

CHAPTER 4 ................................................................................................................. 153

Selected ISO Currency and Country Codes ................................................................... 153

CHAPTER 5 ................................................................................................................. 156

Frequently Asked Questions ........................................................................................... 156 What do I do when a "refer to issuer" response is returned?................................... 156 What happens if someone resubmits a transaction? ............................................... 156 What do I do if my transaction or file upload times out? .......................................... 156 What is TDES? ....................................................................................................... 156 How long does a credit card authorization hold funds on an account? .................... 156 How do I remove an authorization? ........................................................................ 157 If I get an approval code back, is my transaction approved for funds available? ..... 157 If I get an approval for funds available and a decline on AVS, will my transaction still go through? ................................................................................................................. 157


CHAPTER 1 Introduction to the iPay XML API The iPay Gateway XML API provides merchants with the ability to write their own custom payment processing interfaces to the iPay multi-currency enabled platform. This guide provides detailed instructions on connection and encryption protocols, XML request/response formats, and defines all XML elements, their constraints and functionality. As a merchant, this furnishes you with the ability to send real-time transactions that meet your own specifications.

Note: Transaction functionality could be limited based on your back-end service provider. Please check with your sales representative, account manager, Merchant Services, or Merchant Integration if you have any questions.

See the following topics for details:

• Transaction Components.

• Encryption Requirements.

• Valid Characters. The iPay Gateway accepts many data characters, some of which need XMLdata encoding. Transactions with data that does not meet iPay standards will be rejected.

• Base64 Encoding. If the data sent is encrypted, it must also be base64 encoded.

Note: Base64 encoding is optional for clear-text data sent over SSL.

• Modulus Checks. Modulus checks include the Luhn algorithm (also known as the Modulus 10or MOD-10 check) for all card numbers, and the Modulus 9 check for ACH ABA/routing andtransit numbers.

• Transmitting XML Transactions. The steps to transmit an XML transaction include building theXML transaction string, encrypting and transmitting the data, maintaining the connection untilthe response is received, decoding the response, and decrypting the response data.

• Batch File Processing. Merchants have the ability to interface with iPay via real-time and/or ina batch mode.

Transaction Components The iPay transaction components interact directly with the iPay Gateway payment-processing platform. Using a supplied component greatly reduces the development effort needed by the merchant's IT staff. These components are written in the following programming languages.

• Windows: C# DLL (.NET Framework 1.1), C++ DLL

• Platform independent Java

Documentation is included with each component download.


of 165

What the Components do

The components will:

• Build the required XML format with the supplied transaction information.

• Encrypt the data.

• Encode the data with the base64 algorithm.

• Open a socket (TCP/IP) connection to the Gateway transaction server.

• Transmit the data over the socket connection.

• Receive the response generated from the TRANSACTION.

• Decode the response string of XML using the base64 algorithm.

• Decrypt the response string of XML.

Note: The component does not perform any data validation. The merchant must verify thatthe supplied data meet the requirements outlined in the API guides.

Merchants must build their billing page or application around the component. The billing page is where the merchant obtains the required transaction information. Once the merchant has this information, they can then interact with the component. Once the data are passed back to the component from the transaction servers, the merchant has to parse the XML response string to post the response to the user.

Encryption Requirements See the following for details on encryption requirements:

• Message-Level Data Encryption. All real-time transactions are required to be encrypted usingthe Triple-DES encryption algorithm when connecting via TCP/IP Socket.

• Communication-Level Data Encryption. If you are sending data to the iPay Gateway over asecure socket layer (SSL) connection, a 256-bit encryption level (or higher) must be used.

Message-Level Data Encryption

Because transaction data is being transmitted across the Internet, there is always the risk of your data being compromised. Therefore, all real-time transactions are required to be encrypted using the Triple-DES encryption algorithm when connecting via TCP/IP Socket. Electronic codebook (ECB) is the supported mode for Triple-DES. Planet Payment does not provide any assistance with implementing or developing the encryption algorithm, but we will assist you with testing your application. Additional information concerning encryption is available at http://csrc.nist.gov/.

Data encryption is not required when using the SSL protocol but is recommended for additional security.

See the following for further details on encryption:

• Padding. Because Triple-DES encryption must be in blocks of 8 bytes, space padding “isrequired to ensure the data are divisible by 8.


of 165

http://csrc.nist.gov/

• Encryption Verification. The iPay servers attempt to decrypt incoming messages using theencryption key and encryption mode associated with the internal setup of the REQUEST KEY(aka COMPANY_KEY) provided in the incoming message. The encryption key and encryptionmode used is not passed in the actual message; therefore, the system must look at theREQUEST KEY used and attempt to decrypt the message based on the current internal setupinformation for the given account. Merchants are expected to use the correct encryption typeand encryption key supplied by Planet Payment. All improperly encrypted transactions arerejected.

Note: A fee may be associated with excessive encryption errors.

Valid Characters See the following for details:

• Valid Data Characters. A complete list of valid data characters for use with the iPay Gateway.

• XML Character Encoding. Several characters require encoding so that XML parsers can readthem.

• Invalid Data. Transactions with data that does not meet iPay standards will be rejected.

Valid Data Characters

The table below displays all allowable characters (unless otherwise noted) accepted by the iPay Gateway. Characters are displayed in Courier New font.

Dex Hex Character Dex Hex Character Dex Hex Character 32 20 Space 63 3F ? 96 60 ` 33 21 ! 64 40 @ 97 61 a 34 22 " See XML

Character Encoding

65 41 A 98 62 b

35 23 # 66 42 B 99 63 c 36 24 $ 67 43 C 100 64 d 37 25 % 68 44 D 101 65 e 38 26 & See XML

Character Encoding

69 45 E 102 66 f

39 27 ' See XML Character Encoding

70 46 F 103 67 g

40 28 ( 71 47 G 104 68 h 41 29 ) 72 48 H 105 69 i 42 2A * 73 49 I 106 6A j 43 2B + 74 4A J 107 6B k 44 2C , 75 4B K 108 6C l 45 2D - 76 4C L 109 6D m 46 2E . 77 4D M 110 6E n 47 2F / 78 4E N 111 6F o 48 30 0 79 4F O 112 70 p 49 31 1 80 50 P 113 71 q


of 165

50 32 2 81 51 Q 114 72 r 51 33 3 82 52 R 115 73 s 52 34 4 83 53 S 116 74 t 53 35 5 84 54 T 117 75 u 54 36 6 85 55 U 118 76 v 55 37 7 86 56 V 119 77 w 56 38 8 87 57 W 120 78 x 57 39 9 88 58 X 121 79 y 58 3A : 89 59 Y 122 7A z 59 3B ; 90 5A Z 123 7B { 60 3C < See XML

Character Encoding

92 5C \ 124 7C |

61 3D = 94 5E ^ 125 7D } 62 3E > See XML

Character Encoding.

95 5F _ 126 7E ~

Note: Incoming transactions containing invalid characters will be rejected.

XML Character Encoding

The following characters (also shown in Valid Data Characters) are acceptable characters, but they require special coding. This encoding ensures that XML parsers can properly read the instruction of the document.

Character Encoding

< <

> >

& &

‘ '

“ "

Example XML Character Encoding

• Valid: <USER_DATA_0>John & Jane</USER_DATA_0>

• Invalid: <USER_DATA_0>John & Jane</USER_DATA_0>

Note: Many XML parsers encode these characters for you. In this case, no encoding isrequired. However, if you are not using a parser, or if the parser does not handle this encoding, then you are required to format these characters accordingly, or the XML will be invalid and the transaction will be rejected.


of 165

Invalid Data

The iPay Gateway does not accept invalid data from companies that write their own custom applications. Data must be cleansed to meet iPay standards. Transactions with invalid data will be rejected. Depending on the nature of the situation, a fee and/or a per-transaction charge may be associated with additional programming support. Please see specific transaction types for required data. The XML data structure should be validated through an XML parser before and after data encoding and/or data encryption.

Base64 Encoding If the data sent is encrypted, it must also be base64 encoded. Base64 encoding is optional for clear-text data sent over SSL.

The following is the algorithm to perform base64 encoding:

• A 65-character subset of US-ASCII is used, enabling 6 bits to be represented per printablecharacter. (The extra 65th character, "=", is used to signify a special processing function.)

• The encoding process represents 24-bit groups of input bits as output strings of 4 encodedcharacters. Proceeding from left to right, a 24-bit input group is formed by concatenating three8-bit input groups. These 24 bits are treated as four concatenated 6-bit groups, each of whichis translated into a single digit in the base64 alphabet.

• Each 6-bit group is used as an index into an array of 64 printable characters. The characterreferenced by the index is placed in the output string.

The Base64 Alphabet

Value Encoding Value Encoding Value Encoding Value Encoding

0 A 17 R 34 I 51 z

1 B 18 S 35 j 52 0

2 C 19 T 36 k 53 1

3 D 20 U 37 l 54 2

4 E 21 V 38 m 55 3

5 F 22 W 39 n 56 4

6 G 23 X 40 o 57 5

7 H 24 Y 41 p 58 6

8 I 25 Z 42 q 59 7

9 J 26 a 43 r 60 8

10 K 27 b 44 s 61 9

11 L 28 c 45 t 62 +

12 M 29 d 46 u 63 /

13 N 30 e 47 v


of 165

14 O 31 f 48 w (pad) =

15 P 32 g 49 x

16 Q 33 h 50 y

Special processing is performed if fewer than 24 bits are available at the end of the data being encoded. A full encoding quantum is always completed at the end of a quantity. When fewer than 24 input bits are available in an input group, zero bits are added (on the right) to form an integral number of 6-bit groups. Padding at the end of the data is performed, using the '=' character.

Because all base64 input is an integral number of octets, only one of the following cases can arise:

1. The final quantum of encoding input is an integral multiple of 24 bits. In this case, the final unitof encoded output is an integral multiple of 4 characters with no "=" padding.

2. The final quantum of encoding input is exactly 8 bits. In this case, the final unit of encodedoutput is two characters followed by two "=" padding characters.

3. The final quantum of encoding input is exactly 16 bits. In this case, the final unit of encodedoutput is three characters followed by one "=" padding character.

Modulus Checks Modulus checks include the following:

• Modulus 10/Luhn Algorithm. This algorithm is for all card numbers of all lengths and verifiesthat the presented card number could be a live account.

• Modulus 9. This algorithm verifies that the ABA number is valid.

Modulus 10/Luhn Algorithm

The Luhn algorithm (also known as the Modulus 10 or MOD-10 check) is for all card numbers of all lengths and verifies that the supplied card number is valid in composition only. This check does not determine the validity of the account—it only verifies that the presented number could be a live account.

1. Beginning with the second to last digit from right to left, multiply every other digit by 2.

2. Beginning with the third to last digit from right to left, multiply every other digit by 1.

Odd-length digit example: 4000 214 792 588

4 0 0 0 2 1 4 7 9 2 5 8

Multiply by: 1 2 1 2 1 2 1 2 1 2 1 2

4 0 0 0 2 2 4 14 9 4 5 16

Even-length digit example: 4000 2222 1111 7983

4 0 0 0 2 2 2 2 1 1 1 1 7 9 8

Multiply by: 2 1 2 1 2 1 2 1 2 1 2 1 2 1 2

8 0 0 0 4 2 4 2 2 1 2 1 14 9 16


of 165

3. Add the digits of the products obtained in Step 1.

Note: Numbers greater than 9 equal the sum of the individual digits.

Odd-length digit example:

4 + 0 + 0 + 0 + 2 + 2 + 4 + (1 + 4) + 9 + 4 + 5 + (1 + 6) = 42

Even-length digit example:

8 + 0 + 0 + 0 + 4 + 2 + 4 + 2 + 2 + 1 + 2 + 1 + (1 + 4) + 9 + (1 + 6) = 47

4. Add the last digit (check digit) to the total in Step 2. The sum must be a number divisible by 10.

Odd-length digit example:

42 + 8 = 50

Even-length digit example:

47 + 3 = 50

Modulus 9

Modulus 9 is used for the Automated Clearing House (ACH) American Banking Association (ABA) routing and transit number check.

MODULUS: 9

WEIGHTS: 3, 7, 1, 3, 7, 1, 3, 7

ROUTING NUMBER with a Check Digit in the 9th position: 072401006

Modulus 9 Example

FEDERAL RESERVE ROUTING SYMBOL

INSTITUTION’S ABA SUFFIX

Routing Number

0 7 2 4 0 1 0 0

Multiply by 3 7 1 3 7 1 3 7

Results 0 +49 + 2 +12 0 + 1 + 0 + 0 64 Sum of Results

+6 Check Digit*

70

*The check digit is the number which, when added to the sum, produces a number ending in zero.


of 165

XML Transaction Transmission See the following for details:

• Transmitting XML Transactions. Outlines the steps for transmitting XML transactions.

• Sample Request. Provides a sample request.

• Sample Response. Provides a sample response.

• Connection Restrictions. Lists connection restrictions, such as ten simultaneous connectionsper IP address.

Transmitting XML Transactions

The steps for transmitting an XML transaction are as follows:

1. Build the XML transaction string.

2. Encrypt the data with the exception of REQUEST tag.

Note: Transmission via HTTPS POST does not require encryption; however, encryption isrecommended.

3. Base64 encode the encrypted data (This is optional based upon the ENCODING attribute).

4. Wrap encrypted, base64 data within the REQUEST tag.

5. Transmit data via socket connection (TCP/IP) or HTTPS POST.

6. Maintain connection until response is received.

7. Decode the response using the base64 algorithm (This is optional based upon theENCODING attribute).

8. Decrypt the response data.


of 165

Sample Request

Sample Response


of 165

Connection Restrictions

The connection restrictions include:

• Any connection that exceeds 130,000 bytes for a transaction will be severed.

• The iPay Gateway allows only ten simultaneous connections from a single IP address. Oursystem runs multiple transaction servers, which are load balanced. With the load balancing, itis possible to have more than ten simultaneous connections from a single IP address, but thisis not guaranteed. If a single transaction server receives more than ten connections from oneIP address, the eleventh connection will be refused.

• If a connection is made and no data are transmitted within five seconds, the connection will bedropped.

• Streaming connections are not permitted—one connection per transaction.

• The client must close the connection once the </RESPONSE> is received. If the client doesnot close the connection within five seconds of receipt of the </RESPONSE>, our servers willclose the connection.

Batch File Processing The batch file format is identical to the real-time format with the addition of two elements, which are used to wrap many real-time transactions into a file. This format offers merchants the ability to re-use code for both real-time and batch processing.

See the following for details:

• Batch Transmission. Batch files are transmitted via file transfer protocol (FTP).

• Batch File Size. Batch files must be no greater than 25 MB.

• Batch File Layouts. Each file must contain certain XML elements.

• Batch File Naming Conventions. The filename conventions include the number of transactionsin the file.

• File Compression. Files should be compressed before uploading to the iPay Gateway toreduce file transfer time and allow multiple files to be contained within a single compressedfile.

Batch Transmission

Batch files are transmitted via file transfer protocol (FTP); response files are pushed back to the merchant via FTP or e-mail, depending on the merchant’s automated transaction reporting system (ATRS) settings.

The basic batch file sequence is as follows:

1. The file is sent from your application via FTP to our FTP site.

2. An e-mail notification is generated and sent confirming receipt of the file.

3. Files are processed in the order in which they are received.

4. An e-mail notification is generated and sent confirming that the file processing is complete.


of 165

5. Upon completion of processing, you receive your response file back to your FTP site or e-mailaddress, depending on your ATRS selection. FTP delivery is recommended and preferred.

Note: You must provide Planet Payment with a general e-mail address and a validmaintained FTP site if FTP is to be used.

Batch File Size

It is requested that all batch files be no greater than 25 MB. Please contact your Integration Specialist if you feel that 25 MB is not a sufficient size for your business. This limitation has been put in place to ensure maximum efficiency for batch file processing.

Batch File Layouts

See the following:

• REQUESTS.

• RESPONSES.

REQUESTS

All incoming batch files must contain the following elements. The file should contain one or more <REQUEST>(s); see XML Transaction Transmission for formatting of the individual REQUEST.

Batch Request Requirements

Element Child Element

BATCH

REQUESTS

Note: The data displayed are only for demonstration.

<BATCH>

<REQUESTS>

<REQUEST KEY="8993"> Kq9gn++Pw+WLxPGbReAec+B8ofm0q3h2putj6Q80fpVQGazVue0Q</REQUEST>

<REQUEST KEY="8992"> Kq9gn++Pw+WLxPGbReAec+B8ofm0q3h2putj6Q80fg==</REQUEST>

<REQUEST KEY="8992"> 9mk7PH0m/fXlDSPHQ2WHYPxPDz8KmGuxk1eram0v9lqfc4IyTP+u</REQUEST>

<REQUEST KEY="8993"> 9mk7PH0m/fXlDSPHQ2WDz8KmGuxk1eram0v9lqfc4IyTP+uo63S=</REQUEST>

</REQUESTS>

</BATCH>

Note: It is possible to send multiple company numbers in a single file.


of 165

RESPONSES

All response batch files must contain the following elements. The file should contain one or more <RESPONSE>(s); see XML Transaction Transmission for formatting of the individual RESPONSE.

Batch Response Requirements

Element Child Element

BATCH

RESPONSES

Note: The data displayed are only for demonstration.

<BATCH>

<RESPONSES>

<RESPONSE KEY="8993"> 8D5/O7vC35QVfsFQXexxAflhj3lDEMAnR8moZURQfxOAYQ==</RESPONSE>

<RESPONSE KEY= "8992"> DbscEhID2MqgadUeix9KbtX6qRnTi4CJKbshgvIHXWfpq1==</RESPONSE>

<RESPONSE KEY="8993"> 8D5/O7vC35QVfsFQXexxAflhj3lDEMAnR8moZURQfxOAYQ==</RESPONSE>

<RESPONSE KEY="8992"> DbID2MHrqgbl8xedU9Kb11tX6qRnTi4CJKbshgvIHXWfpq1lIz=</RESPONSE>

</RESPONSES>

</BATCH>

Note: Transactions are not guaranteed to be returned in the same order in which they were submitted.

Batch File Naming Conventions

The following filename convention must be followed to prevent another user’s batch file from overwriting your batch file, and conversely, to prevent you from overwriting another user’s batch file.

At a minimum, the raw (uncompressed) batch file name must conform to the following filename format:

RTF_RRRRR_CCCCC_XXXXX.xml

Where

RTF = Static value, file format identifier.

_ = Literal underscore character (ASCII ‘95’).

RRRRR = The number of transaction records contained in the file: 5 digits, zero-padded This file count is required to help provide verification of a complete file transfer. If the count indicated by


of 165

RRRRR does not match the actual count of the transactions in the file, the entire file is rejected and not processed.


CCCCC = Assigned COMPANY_KEY: 5 digits, zero-padded.


XXXXX = Any alphanumeric which may be meaningful to your system and is unique to the file (i.e., not a duplicate of a previously uploaded file). Alphanumeric characters must be validated against the Valid Alphanumeric Characters for Batch File Names. It can be a checksum based on the contents of the file, date, or any other unique identifier (e.g., 9701 or 1A0F3). It is not limited to 5 digits as implied by XXXXX in the example shown. It can be any number of digits, providing the filename length limit of 255 characters in not exceeded. Only the first 40 characters of the filename are stored; these characters are validated for duplicate file names.

Note: In an effort to prevent duplicate transactions, the iPay Gateway eliminates potential duplicate files by looking at the filename, transaction count, and total transaction amount. Therefore, it is important to follow the naming convention above to avoid giving the appearance of a duplicate file. If it appears to be a duplicate, the file is rejected. A valid file name is held in the system for 45 days upon receipt of the file.

Valid Alphanumeric Characters for Batch File Names

The valid alphanumeric characters for batch file names are as follows:

ABCDEFGHIJKLMNOPQRSTUVWXZY0123456789_

Note: Alpha characters can be upper and/or lower case.

The batch response file name is the same as the name of the original file.


of 165

File Compression

Files should be compressed before uploading to the iPay Gateway. Compression provides several important advantages: it reduces file transfer time by two to five times (depending on the data in the file), and it allows multiple files to be contained within the compressed file.

Supported Compression Formats

Supported format

Compressed filename format Sample compressed filename

File Description

PKZip® v2.04g

CCCCCYYYYMMDD_NNNN.ZIP 8990220141208_6583.ZIP Zipped plain text batch containing one or more XML files, uploaded by Company #89902 on 12/8/2014.

The filename format is as follows:

CCCCC = assigned COMPANY_KEY: 5-digits, zero-padded

YYYY = 4-digit year

MM = 2-digit month, zero-padded (e.g., January = ‘01’)

DD = 2-digit day of the month, zero-padded (e.g., 3 = ‘03’)

_ = literal underscore character (ASCII ‘95’)

NNNN = 4-digit unique or random number, zero padded (0000-9999) to prevent duplicate files

Note: Compressed file formats simply provide a “container” for the raw data files by compressing the individual batch file(s). The benefits are well worth the effort!


of 165

CHAPTER 2 Transaction Data See the following topics for details:

• Transaction Elements.

• Request Elements.

Transaction Elements All transactions sent to the iPay Gateway must contain the following elements:

Element Child Element Child Element

REQUEST

TRANSACTION

FIELDS

See the following topics for details:

• Example Transaction.

• Request Attributes.

• Example Requests.

• Field Acceptance.

Example Transaction

<REQUEST KEY="" PROTOCOL="" FMT="" ENCODING="">

<TRANSACTION>

<FIELDS>

Must be populated with transaction based FIELD elements.

</FIELDS>

</TRANSACTION>

</REQUEST>


of 165

Request Attributes

The REQUEST element contains the following additional attributes:

Attribute Name

Description Attribute Values Type

KEY Company Key Assigned processing account number (see COMPANY_KEY for more information).

N

PROTOCOL Identifies the protocol used to transmit the data.

0 – Data Transmitted via raw TCP/IP socket connection. Default value if not provided.

1 – Data Transmitted via HTTP/HTTPS POST.

N

FMT Defines the format of the XML sent in the request body.

All transaction examples use FMT = 1

0 – Legacy XML format—all field elements are within the FIELD node. This is the default value if attribute is not provided.

Example: <FIELD KEY=”AMOUNT”></FIELD>

1 – XML v2 format—each field element is a unique name in both the request and the response.

Example: <AMOUNT></AMOUNT>

N

ENCODING Specifies the encoding of the data within the request body.

0 – No encoding is applied to the data.

1 – Base64 encoding has been applied; this is required for encrypted data, and optional for non-encrypted data sent over SSL. The default value if not specified is zero (0).

N

Example Requests

The following examples illustrate requests with and without encoding:

• Example FMT = 0 without any Encoding.

• Example FMT = 1 without any Encoding.

• Example Encoding = 0.

• Example Encoding = 1.

Example FMT = 0 without any Encoding

<REQUEST KEY="8990" FMT="0" ENCODING="0">

<TRANSACTION>

<FIELDS>

<FIELD KEY=”ACCOUNT_NUMBER”></FIELD>

<FIELD KEY=”AMOUNT”></FIELD>

<FIELD KEY=”SERVICE”></FIELD>

<FIELD KEY=”SERVICE_TYPE”></FIELD>


of 165

<FIELD KEY=”SERVICE_SUBTYPE”></FIELD>

</FIELDS>

</TRANSACTION>

</REQUEST>

Example FMT = 1 without any Encoding


<TRANSACTION>

<FIELDS>

<ACCOUNT_NUMBER></ACCOUNT_NUMBER>

<AMOUNT></AMOUNT>

<SERVICE> </SERVICE>

<SERVICE_TYPE></SERVICE_TYPE>

<SERVICE_SUBTYPE></SERVICE_SUBTYPE>

</FIELDS>

</TRANSACTION>

</REQUEST>

Example Encoding = 0


<TRANSACTION>

<FIELDS>

<ACCOUNT_NUMBER></ACCOUNT_NUMBER>

<AMOUNT></AMOUNT>

<SERVICE></SERVICE>

<SERVICE_TYPE></SERVICE_TYPE>

<SERVICE_SUBTYPE></SERVICE_SUBTYPE>

</FIELDS>

</TRANSACTION>

</REQUEST>

Example Encoding = 1


SlVTVCBBIFRFU1QgU1RSSU5HDQo=

</REQUEST>


of 165

Field Acceptance

Because not all fields are accepted and/or validated with each SERVICE and SERVICE_FORMAT type, the following table is provided with each FIELD element definition. The table specifies the allowable SERVICE and SERVICE_FORMAT type that the field can be transmitted with.

For example:

<SERVICE>CC</SERVICE>

<SERVICE_FORMAT>1010</SERVICE_FORMAT>

Note: The table does not define data requirements for each transaction. See the various transaction processing guides for data requirements for allowable transaction types. The table is provided as a reference for allowable data for each SERVICE/SERVICE_FORMAT combination. Columns that appear for each element description may differ depending on the suitable SERVICE types.

Sample SERVICE/SERVICE_FORMAT

CC ACH DBT Recur Wallet Repository Template Currency Network

0000 √ √ √ √

1010 √ √ √ √ √

1020 √ √ √ √

Request Elements Below is every allowable element that the iPay Gateway transaction servers accept. The TRANSACTION type requested will dictate the use and value supplied of each individual field.

Refer to Field Elements for valid alphanumeric characters.

Note: Empty tags must not be passed in with the transaction REQUEST. Supplying FIELD(s) with no data will cause data validation errors.

Field Elements

Request ELEMENT ELEMENT_VALUE Type Length

AAV Account holder Authentication Value. AN 32

ACCOUNT Payment method of recurring transaction. AN 3

ACCOUNT_ID Unique account identifier. AN 19

ACCOUNT_NUMBER Bank/Credit Card account number. N 17

ACCOUNT_SUBTYPE ACCOUNT_TYPE identifier. AN 1

ACCOUNT_TYPE Type of consumer account. AN 1

ACCOUNT_VALIDATION CVV settings. AN 5


of 165

Request ELEMENT ELEMENT_VALUE Type Length ADDRESS Account holder’s address. AN 30

AMOUNT Transaction amount. N 12

APPROVAL_CODE Transaction approval code. AN 6

AUTH_SOURCE_CODE Identifies authorization source for capture transactions. N 1

BATCH_ID ID for batches. AN 40

BILLING_DESCRIPTION Description of a billing template. AN 100

BILLING_ID Unique identifier for a billing template. AN 19

BILLING_METHOD Selection of pre-pay or post-pay option. AN 4

BILLING_NAME Name of a billing template. AN 50

BILLING_TRANSACTION Specifies the transaction type that will be processed for the billing. N 1

CHECK_NUMBER Consumers check number. AN 9

CITY Account holders city. AN 25

CLIENT_ID Unique client identifier. AN 19

CLIENT_IP IP address of source client sending transaction.

AN 15

CONSUMER_VALIDATION AVS settings. AN 7

COUNTRY Account holder’s country. AN 3

CURRENCY_CODE Code for the transactions currency type. N 3

CURRENCY_INDICATOR Specifies how the amount and currency code will be processed. N 1

CVV Card Verification Value. N 4

EFFECTIVE_DATE Date certain actions become effective. N 8

EFFECTIVE_TYPE Defines DATE or END OF CYCLE for DELETE. AN 12

EMAIL_ADDRESS Account holder’s e-mail address. AN 50

ENTRY_MODE Mode of transaction capture. N 1

EXPIRATION Expiration date of account number. N 4

FIRST_NAME Primary account holder’s first name. AN 25

FRAUD_VALIDATION *Value that determines if a fraud score willbe performed on the transaction, and what level for soft decline functionality.

AN 7

FREQUENCY_DATE The date the frequency will run. N 2


of 165

Request ELEMENT ELEMENT_VALUE Type Length FREQUENCY_DAY The day the frequency will run. AN 7

FREQUENCY_INTERVAL The interval of the schedule. N 3

FREQUENCY_MONTH The month the frequency will run. AN 3

FREQUENCY_TYPE The type of frequency. AN 7

GOODS_INDICATOR Type of product purchased. AN 1

IMAGE Check images for ACH POP SALE transactions.

AN 46550

INITIAL_AMOUNT Initial amount of a recurring schedule. N 12

LAST_FOUR Last four numbers embossed on credit card N 4

LAST_NAME Primary account holder’s last name. AN 25

LOCAL_DATE Local transaction date. N 4

LOCAL_TIME Local transaction time. N 6

MARKET_SPECIFIC_ID Indicator for specific markets (e.g., bill payments). AN 1

MEMBER_NUMBER Merchant-assigned customer identifier AN 25

MERCHANT_CITY Merchant city for merchant descriptor function. AN 13

MERCHANT_NAME Merchant name for merchant descriptor function. AN 25

MERCHANT_PHONE Merchant phone for merchant descriptor function. AN 13

MERCHANT_STATE Merchant state for merchant descriptor function. AN 2

MERCHANT_URL Merchant URL for merchant descriptor function. AN 50

MIN_PAYMENT_AMOUNT Minimum amount the merchant expects to be paid after currency conversion for a recurring schedule.

N 12

MINUTES Number of minutes purchased. N 3

MVV Merchant Verification Value for Visa tax payments. AN 10

OPERATOR Individual performing transaction. AN 10

P3D3_PA_RESPONSE Data received by the merchant’s web site in response to a 3-D Secure authentication. AN 1000

P3D3_TRANSACTION_ID Transaction identifier received from the 3-D Secure provider. AN 20


of 165

Request ELEMENT ELEMENT_VALUE Type Length PHONE Account holder’s phone number. N 15

PIN Encryption key. N 4

POSTAL_CODE Account holder’s postal code. AN 9

PROCESS_RESIDUAL Indicates whether residual amounts are processed. AN 1

PRODUCT_BILLING Identifies how the billing will be processed for the product. N 1

PRODUCT_DESCRIPTION Description of a product. AN 100

PRODUCT_ID Unique identifier for a product. AN 19

PRODUCT_NAME Name of a product. AN 50

PRODUCT_URL URL of a product. AN 100

QUERY_TYPE Defines the manner in which the query will be performed. N 1

RETRY_COUNT Number of times a failed recur cycle can be retried. N 1

RETRY_INTERVAL Interval (in days) between recur cycle retries. N 2

ROUTING_NUMBER Consumer’s routing number. N 9

SCHEDULE_CHARGE_DATE Date charge will run or start. N 8

SCHEDULE_DESCRIPTION Schedule description. AN 50

SCHEDULE_END_AMOUNT The total collected amount when schedule ends.

N 10

SCHEDULE_END_COUNT The total recurring cycle count when schedule ends.

N 3

SCHEDULE_END_DATE The date when schedule ends. N 8

SCHEDULE_ID Unique schedule identifier. AN 19

SCHEDULE_START_DATE Start date of a new recurring schedule. N 8

SCHEDULE_TYPE Type of schedule. AN 16

SEQUENCE_NUMBER Unique client-generated ID for multiple transactions. N 10

SERVICE Service requested. A 6

SERVICE_FORMAT Format for request. N 4

SERVICE_SUBTYPE Detail of service requested. A 8

SERVICE_TYPE Type of service requested. A 6


of 165

Request ELEMENT ELEMENT_VALUE Type Length

SESSION_ID

*Web server session id from merchant’s website. Required for fraud Kaptcha functionality. AN 32

SHIP_ADDR1 Consumer’s ship-to address, field 1. AN 30

SHIP_ADDR2 Consumer’s ship-to address, field 2. AN 30

SHIP_CITY Consumer’s ship-to city AN 25

SHIP_COUNTRY Consumer’s ship-to country code AN 3

SHIP_PHONE Consumer’s ship-to phone number. N 15

SHIP_POSTAL Consumer’s ship-to postal code. AN 9

SHIP_STATE Consumer’s ship-to state code. AN 2

SITE *Short name for merchant’s web site; usedfor the fraud scoring system. AN 8

STATE Account holders state. AN 2

TAX_AMOUNT Total tax amount. N 7

TERMINAL_ID ID number of terminal requesting transaction. AN 15

TICKET Receipt or Invoice Number. AN 30

TIP_AMOUNT Total tip amount. N 7

TRACK_DATA Electronically read account information. AN 79

TRANSACTION_ID Unique Gateway-generated transaction ID. AN 19

TRANSACTION_INDICATOR Transaction indicator. AN 1

TRIAL_AMOUNT One-time amount for a trial period. N 12

UP_COMMODITYDISCOUNT Amount of discount given on transaction. N 12

UP_COMMODITYNAME Merchant order information. AN 256

UP_COMMODITYQUANTITY Quantity of goods. N 10

UP_COMMODITYUNITPRICE Goods unit price. N 12

UP_COMMODITYURL URL where goods are sold. AN 1024

UP_CUSTOMERNAME Name of cardholder. AN 20

UP_DEFAULTBANKNUMBER Default preferred issuer code for bankcard. N 11

UP_DEFAULTPAYTYPE Default payment method preferred by cardholder. AN 20

UP_FRONTENDURL

URL of merchant website for UPOP to redirect cardholder after payment completion. AN 256


of 165

Request ELEMENT ELEMENT_VALUE Type Length UP_TRANSFERFEE Transportation cost. N 12

USER_DATA Optional merchant provided information AN 50

VERBOSE_RESPONSE Option to choose response message detail. N 3

XID Unique ID for Verified by Visa transactions. AN 20

*Merchant must be subscribed to the fraud scoring system to utilize this functionality. See the iPayGateway API Guide for Domestic and Multi Currency Payments for more information.

AAV Request Element Authentication information for transactions that use Verified by Visa or MasterCard SecureCode.

Type Length AN Visa: 20 characters that equal a 28 alphanumeric string after base64

encoding

MasterCard: 0 to 32 characters after base64 encoding

Description

The Account holder Authentication Value (AAV) field holds the authentication information for transactions that have used the Verified by Visa or the MasterCard SecureCode feature.

• For Verified by Visa, the data must be 20 alphanumeric characters that equal a 28alphanumeric string after base64 encoding. The TRANSACTION_INDICATOR value must be5 or 6.

• For MasterCard, the data must be 0 to 32 alphanumeric characters after base64 encoding.The TRANSACTION_INDICATOR value must be 5.

If a merchant account is activated for Verified by Visa or MasterCard SecureCode transactions, this field is optional. If the account is not activated for these transactions, the field should not be included in the transaction request.

For Verified by Visa transactions, merchants can also opt to send in their own unique identifier; see XID.

Merchants must notify Planet Payment if they are going to send Verified by Visa or MasterCard SecureCode data so that their merchant profile can be updated and those transactions can be processed. If a merchant sends transactions with AAV data prior to notifying Planet Payment, the transaction will be rejected, and the merchant will receive an MRC of IS (Inactive Service).

Industry Naming Conventions Each credit card association has a unique name for the AAV data field. For simplicity, our system accepts the data in a single field. Please see the grid below for the mapping associated with each association.


of 165

VISA MC CAVV UCAF

See also AAV Response Element and AAV_RESPONSE Response Element.

Service/Service Format

CC ACH DBT Recur Wallet Currency

0000

1010 √

1020

ACCOUNT Request Element Payment method of the recurring/wallet transaction.

Type Length

AN 3

Values

Value Definition CC Transaction processed from credit card account.

ACH Transaction processed from checking/savings account.

Description

This field indicates the payment method of the recurring/wallet transaction.

Example

<ACCOUNT>CC</ACCOUNT>



0000

1010 √ √

1020 √ √


of 165

ACCOUNT_ID Request Element A unique iPay Gateway-generated identifier for a newly created ACCOUNT.

Type Length

AN 19

Values

Value Definition

CC Transaction processed from credit card account.


Description

This field is a unique identifier generated and returned by iPay for a newly created ACCOUNT. This identifier is used for the life of the ACCOUNT and must be supplied for a MODIFY or DELETE of the ACCOUNT. This identifier is required for any RECUR SCHEDULE INSERT, CC, or ACH token-based transactions that use the stored consumer account information from the WALLET functionality.

Note: See the iPay Gateway API Guide for Secure Tokens and the iPay Gateway API Guide for Recurring Payments for more information.

This ID is unique to the <REQUEST KEY = ""> for which it was generated, and each dependent transaction must be submitted with the originating <REQUEST KEY = "">. For example, a TRANSACTION REQUEST is submitted under KEY (also referenced as COMPANY_KEY) "8990"; any relevant TRANSACTION that requires this ID must be submitted using KEY "8990".

See also ACCOUNT_ID Response Element.

Example

<ACCOUNT_ID>0381B10ETW3YYDPWR5Q</ACCOUNT_ID>



0000

1010 √ √

1020 √ √


of 165

ACCOUNT_NUMBER Request Element Bank account number for ACH transactions, or credit card number for credit card transactions.

Type Length

N 17

Description

This field can be populated with the bank account number for ACH transactions, or the credit card number for credit card transactions. This field should be validated for credit card transactions using the Luhn Algorithm; all transactions received that fail this check are rejected. The length of primary account numbers (PANs) should also be checked to eliminate invalid credit cards that may otherwise pass the Luhn Algorithm (see Credit Card Primary Account Number (PAN) Ranges and Number Lengths below). The value of this field must be greater than 0.

Account and card numbers can only be transmitted in this field. For data security reasons, they are not permitted to be sent in any other field. Merchants who send this data in any custom fields will be subject to investigation and possible termination.

Credit Card Primary Account Number (PAN) Ranges and Number Lengths Card Type Pan Range (Inclusive) Length Visa 400000–499999 13, 16

MasterCard 510000–559999 16

American Express 340000–349999

370000–379999 15

Discover Network

601100–601199

622126-622925

640000-659999

16

Diners Club 300000–309999

380000-389999 14, 16

Discover Network/Diners* 360000–369999 14

JCB Card 352800–358999 16

*Transactions from internationally issued Diners Club cards will be processed as MasterCardtransactions when submitted from a merchant located in the United States.

Example

<ACCOUNT_NUMBER>4111111111111111</ACCOUNT_NUMBER>


of 165



0000 √

1010 √ √ √ √

1020 √ √ √

ACCOUNT_SUBTYPE Request Element Type of ACH ACCOUNT_TYPE.

Type Length AN 1

Values

Value Definition

B Transaction processed to/from a business account.

P Transaction processed to/from a personal account.

Description

This field indicates the type of ACH ACCOUNT_TYPE.

Note: See the iPay Gateway API Guide for ACH Payments for more information.

Example

<ACCOUNT_SUBTYPE>P</ACCOUNT_SUBTYPE



0000

1010 √ √ √

1020 √ √ √


of 165

ACCOUNT_TYPE Request Element Type of bank account for an ACH transaction.

Type Length

AN 1

Values

Value Definition

C Transaction processed to/from checking account.

S Transaction processed to/from savings account.

Description

This field indicates the type of bank account for an ACH transaction. See also ACCOUNT_SUBTYPE Request Element.

Note: See the iPay Gateway API Guide for ACH Payments for more information.

Example

<ACCOUNT_TYPE>C</ACCOUNT_TYPE>



0000

1010 √ √ √

1020 √ √ √

ACCOUNT_VALIDATION Request Element Optional indicator of whether the merchant accepts transactions that failed the CVV check but otherwise were approved by the card issuer.

Type Length AN 5

Values

Value Definition

EXACT CVV (or CVV2 or CID) must match exactly.

NONE No match required.


of 165

Description

This field indicates whether the merchant accepts transactions that failed the CVV check but otherwise were approved by the card issuer. The iPay Gateway only validates these transactions when an ARC code of 00 (approved) and a CVV_RESPONSE are returned in the authorization response.

If the ACCOUNT_VALIDATION field is present in the transaction request with a value of EXACT, the iPay Gateway evaluates the received CVV_RESPONSE, as follows:

• If the CVV_RESPONSE is M, the transaction is allowed to proceed.

• If the CVV_RESPONSE is N, the iPay Gateway soft declines the transaction on behalf of themerchant, and an ARC of SD is returned.

• If the CVV_RESPONSE is P, S, or U, the ACCOUNT_VALIDATION check is bypassed andthe transaction is allowed to proceed.

If the ACCOUNT_VALIDATION field is present in the transaction request with a value of NONE, the iPay Gateway allows the transaction to proceed with any returned CVV_RESPONSE.

The transaction is rejected (MRC=IK) if the ACCOUNT_VALIDATION field is present with an invalid TYPE value or the field does not contain one of the values shown above.

The values provided in the request override any values set up at the billing option or schedule level.

TYPE=”CVV” must be submitted with this field.

Example

<ACCOUNT_VALIDATION TYPE=”CVV”>EXACT </ACCOUNT_VALIDATION>


CC ACH DBT Recur Wallet Template Currency

0000 √

1010 √ √ √

1020 √ √ √

ADDRESS Request Element Address

that appears on the cardholder’s billing statement. Type Length

AN 30

Description

This field is the address that appears on the cardholder’s billing statement.


of 165

Example

<ADDRESS>123 Main St</ADDRESS>



0000

1010 √ √ √ √ √

1020 √ √ √

AMOUNT Request Element Transaction amount to be processed.

Type Length

N 12

Description

This field contains the transaction amount to be processed. The decimal is NOT implied, and merchants should send data that is rounded appropriately for the requested currency. For currency using a dollar as the base unit, amounts must be rounded to two decimal places.

Note: If an amount submitted in U.S. dollars is not rounded to two decimal places, iPay will round the amount (and change it, if necessary) and then truncate it to two decimal places prior to processing the transaction. If the third decimal place is 5 or greater, the amount will be rounded up; if the third decimal place is 4 or lower, the amount will be rounded down. The value of the fourth decimal place will not be considered.

See also AMOUNT Response Element.

Example

<AMOUNT>19.99</AMOUNT>



0000 √ √

1010 √ √ √ √ √

1020 √ √ √


of 165

APPROVAL_CODE Request Element Approval code from a voice authorization system.

Type Length

AN 6

Description

This field should be populated with a previously obtained approval code from a voice authorization system.

See also AMOUNT Response Element.

Example

<APPROVAL_CODE>042191</APPROVAL_CODE>



0000

1010 √

1020 √

AUTH_SOURCE_CODE Request Element Authorization source for CAPTURE transactions when the authorization was not processed through the iPay Gateway.

Type Length

AN 1

Values

Value Definition 6 Voice-approved authorization.

9 Authorization not performed (merchant must be activated for Express Payment program to use this value).

Description

This field identifies the authorization source for CAPTURE transactions when the authorization was not processed through the iPay Gateway (e.g., CAPTURE without TRANSACTION_ID).


of 165

Example

<AUTH_SOURCE_CODE>6</AUTH_SOURCE_CODE>



0000

1010 √ √

1020 √ √

BATCH_ID Request Element Merchant-assigned ID to group multiple transactions together. Optional for real-time transactions; required for batch files.

Type Length AN 40

Values

Valid Characters Definition

ABCDEFGHIJKLMNOPQRSTUVWXZY0123456789_. Alpha characters can be upper and/or lower case.

Description

This field is a merchant-assigned ID to group multiple transactions together. This is an optional field for real-time transactions, but its use is encouraged as it can facilitate reconciliation. BATCH_ID is required for batch files and should contain the batch file name. For more information, see Batch File Naming Conventions.

See also BATCH_ID Response Element.

Example Real-Time Transaction

<BATCH_ID>cc11202014</BATCH_ID>

Example Batch File

<BATCH_ID>RTF_00352_08990_02FEB2014.xml</BATCH_ID>


CC ACH DBT Recur Wallet Repository Template

0000 √ √

1010 √ √ √ √


of 165


1020 √ √ √ √

BILLING_DESCRIPTION Request Element Billing template description.

Type Length

AN 100

Description

This field is the description of a billing template.

Note: See the iPay Gateway API Guide for Recurring Payments for more information on billing templates.

Example

<BILLING_DESCRIPTION>Test Billing Description 123</ BILLING_DESCRIPTION >


CC ACH DBT Recur Wallet Template

0000 √

1010

1020

BILLING_ID Request Element A unique iPay-generated identifier for a newly created billing template.

Type Length AN 19

Description

This field is a unique identifier generated and returned by the iPay Gateway for a newly created billing template. This identifier is used for the life of the billing template and must be supplied for a MODIFY or DELETE of the billing template or a CLIENT_INSERT, ACCOUNT_INSERT, or SCHEDULE_REPLACE transaction.

Note: See the iPay Gateway API Guide for Recurring Payments for more information.

This ID is unique to the <REQUEST KEY = ""> for which it was generated, and each dependent transaction must be submitted with the originating <REQUEST KEY = "">. For example, a


of 165

TRANSACTION REQUEST is submitted under KEY "8990". Any relevant (e.g., DELETE or MODIFY) TRANSACTION that requires this ID must be submitted using KEY "8990".

See also BILLING_ID Response Element.

Example

<BILLING_ID>0999B10ZZZ3YYDPWQ5R</BILLING_ID>



0000 √

1010 √

1020 √

BILLING_METHOD Request Element Required mode for billing a customer’s recurring schedule.

Type Length

AN 4

Values

Value Definition

PRE Customer is charged at the beginning of the billing cycle.

POST Customer is charged at the end of the billing cycle.

Description

This field represents the mode for billing a customer’s recurring schedule. In the pre-pay mode, the customer is charged before the consumption of the service (i.e., at the beginning of the cycle). In the post-pay mode, the customer is charged after the consumption of the service (i.e., at the end of the cycle). The selection of pre-pay or post-pay has an effect on how residual amounts are handled when a schedule is replaced or canceled. See PROCESS_RESIDUAL for more information.


Example

<BILLING_METHOD>PRE</BILLING_METHOD>


of 165



0000 √

1010 √

1020 √

BILLING_NAME Request Element Required billing template name.

Type Length AN 50

Description

This field is the name of a billing template.

Note: See the iPay Gateway API Guide for Recurring Payments for more information on billing templates.

Example

<BILLING_NAME>platinum three year</BILLING_NAME>



0000 √

1010

1020

BILLING_TRANSACTION Request Element Transaction type that will be processed for the billing.

Type Length

N 1

Values

Value Definition

0 (zero) An authorization will be performed for the billing.

1 A sale will be performed for the billing.


of 165

Value Definition 2 An AVS_ONLY will be performed for credit card validation.

3 A data validation will be performed for ACH transaction types only.

Description

This field specifies the transaction type that will be processed for the billing.


Example

<BILLING_TRANSACTION>0</BILLING_TRANSACTION>



0000

1010 √ √ √

1020 √ √

CHECK_NUMBER Request Element The number of the check that the account holder presents for payment. Optional unless ENTRY_MODE is 1 or 2; then, required.

Type Length AN 9

Description

This field is the number of the check that the account holder presents for payment. This is an optional field unless ENTRY_MODE is 1 or 2; then, it is required.

Example

<CHECK_NUMBER>238</CHECK_NUMBER>



0000

1010 √ √

1020 √ √


of 165

CITY Request Element City that appears on the cardholder’s billing statement.

Type Length

AN 25

Description

This field is the city that appears on the cardholder’s billing statement.

Example

<CITY>New York</CITY>



0000

1010 √ √ √ √

1020 √ √ √ √

CLIENT_ID Request Element A unique iPay Gateway-generated identifier for a newly created CLIENT.

Type Length

AN 19

Description

This field is a unique identifier generated and returned by the iPay Gateway for a newly created CLIENT. This identifier is used for the life of the CLIENT and must be supplied for a MODIFY or DELETE of the CLIENT. It must also be supplied with ACCOUNT INSERT transactions.

This ID is unique to the <REQUEST KEY = ""> for which it was generated. Each dependent transaction must be submitted with the originating <REQUEST KEY = "">. For example, a TRANSACTION REQUEST is submitted under KEY "8990"; any relevant (e.g., DELETE or MODIFY) TRANSACTION that requires this ID must be submitted using KEY "8990".

See also CLIENT_ID Response Element.

Example

<CLIENT_ID>0381B103TW3YYDPWQ5R</CLIENT_ID>


of 165



0000

1010 √ √

1020 √ √

CLIENT_IP Request Element Optional Internet protocol (IP) address of the source client that requested the transaction of the merchant.

Type Length

AN 15

Description

This field contains the Internet protocol (IP) address of the source client that requested the transaction of the merchant. The IP address may contain one to three numbers in each segment and is validated based on the format ###.###.###.###. This is an optional field.

Valid examples include 10.0.0.1, 192.168.10.1; and 127.000.000.001.

Note: The iPay Gateway supports only IP version 4.

Example

<CLIENT_IP>157.42.30.01</CLIENT_IP>



0000 √ √ √ √

1010 √ √ √ √ √

1020 √ √ √ √

CONSUMER_VALIDATION Request Element Optional indication of whether to accept transactions that failed the AVS check but otherwise were approved by the card issuer.

Type Length AN 7


of 165

Values

Value Definition AVS Responses That Result in a Validated Transaction

ADDRESS Street address only. X, Y, A, B, D

EXACT Street address and postal code. X, Y

ANY Street address or postal code. X, Y, W, Z, A, B, D, P

NONE No match required. All codes are accepted and the transaction will proceed.

POSTAL Postal code only. X, Y, W, Z, P, D

Description

This field allows merchants to control whether they wish to accept transactions that failed the AVS check but otherwise were approved by the card issuer. The iPay Gateway only validates these transactions when an ARC of 00 (approved) and an AVS_REPONSE are returned in the authorization response.

If a transaction fails the validation, the transaction is soft declined and an ARC of SD is returned.

If the AVS_REPONSE is C, E, G, I, R, S, or U, the CONSUMER_VALIDATION check is bypassed and the transaction is allowed to proceed.

The transaction is rejected (MRC=IK) if the CONSUMER_VALIDATION field is present with an invalid TYPE value or the field does not contain one of the values shown above.

The values provided in the request override any values set up at the billing option or schedule level.

Attribute TYPE=”AVS” must be included when submitting this field.

Example

<CONSUMER_VALIDATION TYPE=”AVS”>EXACT</CONSUMER_VALIDATION>



0000 √

1010 √ √ √

1020 √ √ √


of 165

COUNTRY Request Element Optional three-character alpha International Standards Organization (ISO) 3166 country code.

Type Length

AN 3

Description

This field is the three-character alpha International Standards Organization (ISO) 3166 country code. This is the country that appears on the cardholder’s billing statement. The value for this field must be referenced from the Country Code column in the Selected ISO Currency and Country Codes.

Example

<COUNTRY>USA</COUNTRY>



0000

1010 √ √ √ √ √

CURRENCY_CODE Request Element Standard numeric ISO 4217 code used to identify the type of currency in the AMOUNT field.

Type Length

N 3

Description

This field is the standard numeric ISO 4217 code used to identify the type of currency in the AMOUNT field. The value for this field must be referenced from the Currency Code column in the Selected ISO Currency and Country Codes. The value of the currency code will be represented in attribute “alpha” in the response messages for the RATE service only.

Example Values Provided within Transaction

<CURRENCY_CODE>826</CURRENCY_CODE> <AMOUNT>15</AMOUNT>

Example Current Exchange Rate and Card Type

The current exchange rate of the provided currency and card type is returned in the transaction response:


of 165

<EXCHANGE_RATE>0.971</EXCHANGE_RATE> <CURRENCY_CODE alpha=”GBP”>826</CURRENCY_CODE>



0000 √ √

1010 √ √ √ √ √

1020 √ √ √ √

CURRENCY_INDICATOR Request Element How the amount and currency code will be processed.

Type Length

N 1

Values

Value Definition

0 (zero) The currency will be processed as a domestic currency transaction.

1 (one) The currency will be processed as an MCP transaction.

2 (two) The currency will be processed as a PYC transaction.

Description

This field is used to identify how the amount and currency code will be processed.

Note: See the iPay Gateway API Guide for Domestic and Multi Currency Payments for more information.

Example

<CURRENCY_INDICATOR>0</CURRENCY_INDICATOR>



0000 √ √

1010 √ √ √ √ √

1020 √ √ √ √


of 165

CVV Request Element Conditional Card Verification Value (CVV) from the cardholder's card.

Type Length

N 5

Description

This field is the CVV printed on the cardholder's card. The Card Verification Value (CVV) is an extra level of cardholder validation and is part of the authorization process. The CVV is printed (not embossed) on the card and is not encoded on the magnetic strip. The value is 3 digits for Visa and MasterCard and 4 digits for American Express. This field is conditional and depends on the merchant’s contract with the acquiring financial institution. AMEX requires enrollment with American Express Global Fraud Prevention before accepting and validating this field.

Note: These values are not permitted to be stored anywhere and are for real-time transactions only. CVV data may only be transmitted in this field. For data security reasons, CVV values are not permitted to be sent in any other field. Merchants who send these data in any custom fields will be subject to investigation and possible termination.

CVV Industry Naming Conventions Each credit card association has a unique name for the CVV data field. For simplicity, our system accepts the data in a single field (CVV). The mapping associated with each association is as follows:

Visa MC Amex Discover

CVV2 CVC2 CID CID

Example

<CVV>123</CVV>



0000

1010 √ √ √

1020 √


of 165

EFFECTIVE_DATE Request Element Date when a CLIENT DELETE, ACCOUNT DELETE, or SCHEDULE DELETE becomes effective. Required for SCHEDULE DELETE and SCHEDULE REPLACE transactions.

Type Length

N 8 digits fixed in YYYYMMDD format

Description

This field is the date when an action of CLIENT DELETE, ACCOUNT DELETE, or SCHEDULE DELETE becomes effective. If present for CLIENT DELETE or ACCOUNT DELETE transactions, the effective date is the date when all associated schedules are cancelled. The effective date must be a date equal to or greater than the present date.

Example

<EFFECTIVE_DATE>20151015</EFFECTIVE_DATE>



0000

1010 √

1020 √

EFFECTIVE_TYPE Request Element When a CLIENT DELETE, ACCOUNT DELETE, or SCHEDULE DELETE becomes effective. Required for all RECUR_XXXX_DELETE transactions.

Type Length

AN 12

Values

Value Definition DATE DELETE action is performed on EFFECTIVE_DATE.

END_OF_CYCLE DELETE action is performed at the end of the schedule’s cycle.

Description

This field defines when an action of CLIENT DELETE, ACCOUNT DELETE, or SCHEDULE DELETE becomes effective. If an EFFECTIVE_TYPE value of DATE is submitted, the DELETE becomes effective on the submitted EFFECTIVE_DATE. If an EFFECTIVE_TYPE of END_OF_CYCLE is submitted, the DELETE automatically becomes effective at the end of the


of 165

schedule’s cycle and does not have to be calculated. Using END_OF_CYCLE allows the schedule to remain active until the next scheduled billing date. In either case, no future billings, including those scheduled on the EFFECTIVE_DATE, are processed once the EFFECTIVE_DATE is reached.


Example

<EFFECTIVE_TYPE>END_OF_CYCLE</EFFECTIVE_TYPE>



0000

1010 √

1020 √

EMAIL_ADDRESS Request Element Optional consumer's email address.

Type Length AN 50

Description

This field is the consumer's email address. There are two field types that can be used, PRIMARY and SECONDARY. This is an optional field.

Example

<EMAIL_ADDRESS TYPE=”PRIMARY”>[email protected]</EMAIL_ADDRESS> <EMAIL_ADDRESS TYPE=”SECONDARY”>[email protected]</EMAIL_ADDRESS>



0000 √ √

1010 √ √ √ √ √

1020 √ √ √ √


of 165

ENTRY_MODE Request Element How transaction data was captured. Conditional for ACH and card-present CC transactions. Optional for card-not-present transactions.

Type Length

N 1

Values

Value Definition 1 A card/check reader swiped the data.

2 Data was manually entered (key entered), card/check present

3 Data was manually entered (key entered), card/check not present.

Description

This field indicates how the transaction data was captured. This field is conditional for ACH and card-present CC transactions depending on the transaction type. It is optional for card-not-present transactions.

Note the following:

• For ACH Transactions: If ENTRY_MODE is 1 or 2, CHECK_NUMBER must also be includedin the transaction data.

• For Credit Card Transactions: ENTRY_MODE is modified internally based on the typeof TRACK_DATA transmitted when sending swiped data (ENTRY_MODE = “1”). This field ismodified to identify the track received; the value 4 identifies Track 1, value 5 identifies Track 2.Merchants using VERBOSE_RESPONSE and transmitting TRACK_DATA receive themodified value in the response message.

Example

<ENTRY_MODE>1</ENTRY_MODE>



0000

1010 √ √ √ √ √

1020 √ √ √ √


of 165

EXPIRATION Request Element Expiration date from cardholder's card.

Type Length

N 4 digits fixed in format MMYY

Description

This field is the expiration date that is embossed on the front of the cardholder's card.

Example

<EXPIRATION>1117</EXPIRATION>



0000

1010 √ √ √

1020 √ √ √

FIRST_NAME Request Element First name of the consumer.

Type Length

AN 25

Description

This field is the first name of the consumer, which is embossed on the card or printed on the check.

Example

<FIRST_NAME>John</FIRST_NAME>



0000

1010 √ √ √ √ √

1020 √ √ √ √


of 165

FRAUD_VALIDATION Request Element Whether and how to score the card using the Fraud Score Service.

Type Length

AN 50

Values

Value Score Soft Decline When

NONE No Not applicable.

APPROVE Yes FRAUD_AUTO = R (review), M (manager review), or D (decline).

REVIEW Yes FRAUD_AUTO = M (manager review) or D (decline).

MREVIEW Yes FRAUD_AUTO = D (decline).

ANY Yes Score only; Soft Decline will not be triggered.

Description

This field indicates the following: (1) whether or not to score the transaction for fraud, and (2) if a Soft Decline response is desired based on the FRAUD_AUTO response value.

Note: The merchant’s iPay account must be subscribed to the Fraud Score Service to participate. See the iPay Gateway API Guide for Domestic and Multi Currency Payments for more information.

Subscribed merchants may request a fraud score for each qualifying financial transaction. The fraud scoring system will return a FRAUD_AUTO response value that is based on the merchant’s pre-defined fraud rules configured in the fraud web console. It is this value that the Soft Decline functionality will use to determine if the Sale or Authorization will be reversed on the merchant’s behalf.

Note: A fraud score response that indicates an error or timeout condition will not affect the outcome of the financial transaction. The transaction will proceed normally as if no fraud score or Soft Decline functionality had been requested.

Example

<FRAUD_VALIDATION>REVIEW</FRAUD_VALIDATION>



0000

1010 √ √ √

1020


of 165

FREQUENCY_DATE Request Element Required date of the month when a MONTHLY or YEARLY frequency is to occur if FREQUENCY_TYPE = (MONTHLY or YEARLY) and FREQUENCY_DAY is not present.

Type Length

N 2 digits fixed in format DD

Description

This field is the date of the month when the MONTHLY or YEARLY frequency is to occur. This is required if FREQUENCY_TYPE = (MONTHLY or YEARLY) and FREQUENCY_DAY is not present.

Note the following:

• If a CLIENT, ACCOUNT, or SCHEDULE INSERT includes a free trial period,FREQUENCY_DATE is automatically calculated based on SCHEDULE_START_DATE andthe length of the free trial period and is not required.

• If a BILLING_ID is referenced for an INSERT or REPLACE recurring transaction, and thebilling template includes a FREQUENCY_TYPE = (MONTHLY or YEARLY) but does notinclude a FREQUENCY_DATE, then the FREQUENCY_DATE is automatically calculated andsubmitted for the schedule by iPay based on the DD value of the SCHEDULE_START_DATE.For example, if the FREQUENCY_TYPE=MONTHLY and the SCHEDULE_START_DATE is20120425, the FREQUENCY_DATE is set as 25, and the customer is billed on the 25th ofevery month.


Example

<FREQUENCY_DATE>17</FREQUENCY_DATE>



0000 √

1010 √

1020 √


of 165

FREQUENCY_DAY Request Element Required day when the WEEKLY, MONTHLY, or YEARLY frequency is to occur if FREQUENCY_TYPE = (WEEKLY or MONTHLY or YEARLY) and FREQUENCY_DATE is not present.

Type Length AN 7

Values

FREQUENCY_DAY VALUES Value Definition

SUN Schedule runs on Sunday.

MON Schedule runs on Monday.

TUE Schedule runs on Tuesday.

WED Schedule runs on Wednesday.

THU Schedule runs on Thursday.

FRI Schedule runs on Friday.

SAT Schedule runs on Saturday.

DAY Schedule runs on the type FIRST or LAST day.

WEEKDAY Schedule runs on the type FIRST or LAST weekday.

FREQUENCY_DAY TYPES Value Definition

FIRST Schedule runs on FIRST FREQUENCY_DAY.

SECOND Schedule runs on SECOND FREQUENCY_DAY.

THIRD Schedule runs on THIRD FREQUENCY_DAY.

FOURTH Schedule runs on FOURTH FREQUENCY_DAY.

LAST Schedule runs on LAST FREQUENCY_DAY.

Description

This field is the day when the WEEKLY, MONTHLY, or YEARLY frequency is to occur. This is required if FREQUENCY_TYPE = (WEEKLY or MONTHLY or YEARLY) and FREQUENCY_DATE is not present.

This field also contains a TYPE attribute that offers the ability to dictate the interval of the FREQUENCY_DAY selected; this type must be supplied when the FREQUENCY_DAY value is DAY or WEEKDAY. The values SECOND, THIRD, and FOURTH cannot be supplied in


of 165

combination with FREQUENCY_DAY value of DAY or WEEKDAY. This attribute cannot be used for the WEEKLY FREQUENCY_TYPE.

Example Customer Billed Weekly on Monday

In this example, the customer is billed weekly on Monday.

<FREQUENCY_TYPE>WEEKLY</FREQUENCY_TYPE> <FREQUENCY_DAY>MON</FREQUENCY_DAY>

Example Customer Billed on First Tuesday

In this example, the customer is billed on the first Tuesday of every month.

<FREQUENCY_TYPE>MONTHLY</FREQUENCY_TYPE> < FREQUENCY_DAY TYPE="FIRST">TUE</FREQUENCY_DAY>



0000 √

1010 √

1020 √

FREQUENCY_INTERVAL Request Element Number of frequencies to occur between scheduled billings.

Type Length

N 3

Description

This field indicates the number of frequencies to occur between scheduled billings. This field is numeric with a maximum length of 3 digits. Together with the FREQUENCY_TYPE, these two fields define the length of time between billings. For example, if the FREQUENCY_INTERVAL is set to 4 and the FREQUENCY_TYPE is set to WEEKLY, the customer is billed every four weeks.

This field is also used to denote the FREQUENCY_INTERVAL of a trial period. To define the frequency type of a trial period, add TYPE=”TRIAL”; see below. The duration of the trial is further defined using the FREQUENCY_TYPE field. Both fields must be used to define a trial period.


Example Frequency Interval

<FREQUENCY_INTERVAL>1</FREQUENCY_INTERVAL>


of 165

Example Frequency Interval with Trial Period

<FREQUENCY_INTERVAL TYPE=”TRIAL”>1</FREQUENCY_INTERVAL>



0000 √

1010 √

1020 √

FREQUENCY_MONTH Request Element Required month if FREQUENCY_TYPE = YEARLY.

Type Length

AN 3

Values

Value Definition JAN Schedule runs in January.

FEB Schedule runs in February.

MAR Schedule runs in March.

APR Schedule runs in April.

MAY Schedule runs in May.

JUN Schedule runs in June

JUL Schedule runs in July.

AUG Schedule runs in August.

SEP Schedule runs in September.

OCT Schedule runs in October.

NOV Schedule runs in November.

DEC Schedule runs in December.

Description

This field is the month when the YEARLY frequency is to occur. This is required if FREQUENCY_TYPE = YEARLY.


of 165

Note: If a BILLING_ID is referenced for an INSERT or REPLACE recurring transaction, and the billing template includes a FREQUENCY_TYPE = YEARLY but does not include a FREQUENCY_MONTH or FREQUENCY_DATE, these values are automatically calculated and submitted for the schedule by iPay based on the MMDD values of the SCHEDULE_START_DATE. For example, if the FREQUENCY_TYPE=YEARLY and the SCHEDULE_START_DATE is 20120425, the FREQUENCY_MONTH is set in the system as APR and the FREQUENCY_DATE is set in the system as 25, resulting in the customer being billed every April 25th. See the iPay Gateway API Guide for Recurring Payments for more information.

Example

<FREQUENCY_MONTH>JAN</FREQUENCY_MONTH>



0000 √

1010 √

1020 √

FREQUENCY_TYPE Request Element Type of frequency requested for a recurring schedule or to indicate a trial period.

Type Length AN 7

Values

Value Definition Maximum Trial Period Lengths

DAILY Schedule runs daily based on the frequency. 90

WEEKLY Schedule runs weekly based on the frequency. 4

MONTHLY Schedule runs monthly based on the frequency. 6

YEARLY Schedule runs yearly based on the frequency. 1

Description

This field indicates the type of frequency requested for a recurring schedule. This field is also used to denote the FREQUENCY_TYPE of a trial period. To define the frequency type of a trial period, add TYPE=TRIAL (see the example below). The duration of the trial is further defined using the FREQUENCY_INTERVAL field. Both fields must be used to define a trial period.


of 165

Note: If a CLIENT, ACCOUNT, or SCHEDULE INSERT includes a free trial period, SCHEDULE_CHARGE_DATE must not be included. In this case, the SCHEDULE_CHARGE_DATE is automatically calculated based on the SCHEDULE_START_DATE and the length of the free trial period.

Example Frequency Type

<FREQUENCY_TYPE>MONTHLY</FREQUENCY_TYPE>

Example Frequency Type with Trial Period

<FREQUENCY_TYPE TYPE=”TRIAL”>MONTHLY</FREQUENCY_TYPE>



0000 √

1010 √

1020 √

GOODS_INDICATOR Request Element Type of goods purchased.

Type Length AN 1

Values

Value Definition

P Item purchased was a physical good.

D Item purchased was a digital/electronic good.

Description

This field indicates the type of goods purchased.

Example

<GOODS_INDICATOR>D</GOODS_INDICATOR>


of 165



0000

1010 √ √ √ √ √

1020

IMAGE Request Element Transmits up to two scanned check images for ACH POP SALE transactions.

Type Length AN 46550 characters before base64 decoding

Values

Attribute Value Required Type Length

TYPE Description of image. Y AN 50 characters

FORMAT File format. Defaults to "JPEG". N AN 4 characters

Description

This field is used to transmit scanned check images for ACH POP SALE transactions. A maximum of two IMAGE tags may be included for one transaction. The data must be a valid JPEG file. The TYPE attribute is required and contains the description for the IMAGE. The FORMAT attribute is optional and defaults to the only acceptable value of “JPEG”. The transaction will be rejected if the FORMAT is not correct.

Any connection that exceeds 130000 bytes for a transaction will be severed. Keep this in mind when preparing to send JPEG image files. See Connection Restrictions for more information.

Example

IMAGE TYPE="CHECK_FRONT" FORMAT="JPEG"></IMAGE>



0000

1010 √

1020 √


of 165

INITIAL_AMOUNT Request Element Optional override of the AMOUNT field of a schedule only for the first billing cycle.

Type Length N 12

Description

This field is used to override the AMOUNT field of a schedule only for the first billing cycle. This field is used to bill the customer a different amount for the first billing cycle of the schedule (e.g., an introductory price). This is an optional field.


The initial amount can be an introductory discount or an additional charge on the first billing cycle. The decimal is NOT implied, and merchants should send data rounded to two decimal places for U.S. currency.

Note: If an amount submitted in U.S. dollars is not rounded to two decimal places, iPay rounds the amount (and changes it, if necessary) and then truncates it to two decimal places prior to processing the transactions. If the third decimal place is 5 or greater, the amount is rounded up; if the third decimal place is 4 or lower, the amount is rounded down. The value of the fourth decimal place is not considered.

Example

<INITIAL_AMOUNT>19.95</INITIAL_AMOUNT>



0000 √

1010 √

1020 √

LAST_FOUR Request Element Last four digits of the account holder’s card.

Type Length

N 4


of 165

Description

This field contains the last four digits of the account holder’s card. This is a security feature that compares the last four digits embossed on the front of the card (keyed in by the terminal operator) to the last four digits in the magnetic stripe (TRACK_DATA) of the card. If the keyed last four digits do not match the TRACK_DATA, the transaction is rejected with an MRC of IK (invalid key). This is an optional field.

Example

<LAST_FOUR>5879</LAST_FOUR>



0000

1010

1020 √ √ √

LAST_NAME Request Element Last name embossed on the card or printed on the check.

Type Length

AN 25

Description

This field is the last name that is embossed on the card or printed on the check.

Example

<LAST_NAME>Doe</LAST_NAME>



0000

1010 √ √ √ √ √

1020 √ √ √ √


of 165

LOCAL_DATE Request Element Local month and day on which the transaction takes place.

Type Length

N 8 digits in format YYYYMMDD

Description

This field the local (i.e., point of card acceptor location) month and day on which the transaction takes place.

See also LOCAL_DATE Response Element.

Example

<LOCAL_DATE>20151022</LOCAL_DATE>



0000

1010 √ √ √ √ √

1020 √ √ √ √

LOCAL_TIME Request Element Local time at which the transaction takes place.

Type Length

N 6 digits fixed in format HHMMSS

Description

This field is the local (i.e., point of card acceptor location) time at which the transaction takes place. The format is HHMMSS, using a 24-hour clock (“military time”).

See also LOCAL_TIME Response Element.

Example

<LOCAL_TIME>233106</LOCAL_TIME>


of 165



0000

1010 √ √ √ √ √

1020 √ √ √ √

MARKET_SPECIFIC_ID Request Element Optional market-specific bill payment indicator.

Type Length AN 1

Values

Value Definition

B Bill payment.

Description

This field is a market-specific ID in the form of a bill payment indicator. Utility merchants (MCC 4900) may qualify for special interchange rates if this indicator is included for eligible transactions. This is an optional field.

Example

<MARKET_SPECIFIC_ID>B</MARKET_SPECIFIC_ID>



0000

1010 √ √ √ √

1020 √ √ √ √

MEMBER_NUMBER Request Element Optional merchant user data field.

Type Length

AN 25


of 165

Description

This field is a merchant user data field. The field is commonly used for order number, customer number, etc. This is an optional field.

Example

<MEMBER_NUMBER>tr58743</MEMBER_NUMBER>



0000

1010 √ √ √ √ √

1020 √ √ √ √

MERCHANT_CITY Request Element Merchant city used as part of the merchant descriptor.

Type Length

AN 13

Description

This field contains the merchant city. This field is only used as part of the merchant descriptor. Data passed in this field can be used for internal reporting only.

Example

<MERCHANT_CITY>Portland</MERCHANT_CITY>



0000

1010 √ √ √

1020 √ √ √

MERCHANT_NAME Request Element Merchant name used as part of the merchant descriptor.

Type Length AN 25


of 165

Values

Card Type Maximum Length

Discover 22

AMEX 20

MasterCard 22

Visa 25

JCB 22

Description

This field contains the merchant name. Valid lengths vary for this field depending on the card type being submitted. Data is truncated if the maximum length specified above is exceeded. This field is only used as part of the merchant descriptor. Depending on the backend service provider, data passed in this field can override default merchant information.

Note: Valid characters are restricted to upper- and lower-case alphabetic characters (A-Z), numeric characters (0-9), the comma (,), period (.), space ( ), and asterisk (*). The use of any other special characters (e.g., front slash, back slash, underscore, hyphen, dash, etc.) will cause the transaction to be rejected.

Example

<MERCHANT_NAME>Data Solutions Inc</MERCHANT_NAME>



0000 √

1010 √ √ √

1020 √ √ √

MERCHANT_PHONE Request Element Merchant customer service phone number.

Type Length AN 13 characters maximum in the format xxx-xxx-xxxx

Description

This field contains the merchant’s customer service phone number. This field is only used as part of the merchant descriptor. Depending on the backend service provider, data passed in this field can override default merchant information.


of 165

The number must be in the format xxx-xxx-xxxx, where x is any valid numeral (0 through 9, inclusive) and – is a literal dash character (ASCII ‘45’).

Example

<MERCHANT_PHONE>800-999-9999</MERCHANT_PHONE>



0000 √

1010 √ √ √

1020 √ √ √

MERCHANT_STATE Request Element Merchant State.

Type Length

AN 2

Description

This field contains the merchant state. Standard United States Postal Service abbreviations must be used (see www.usps.gov for more information). This field is only used as part of the merchant descriptor. Data passed in this field can be used for internal reporting only. This is only available for US locations.

Example

<MERCHANT_STATE>OR</MERCHANT_STATE>



0000 √

1010 √ √ √

1020 √ √ √


of 165

http://www.usps.gov/

MERCHANT_URL Request Element Uniform resource locator (URL) of the Web site where the transaction originated.

Type Length

AN 50

Description

This field contains the uniform resource locator (URL) of the Web site where the transaction originated. This field is only used as part of the merchant descriptor and is available only for Internet payment services provider (IPSP) merchants. Data passed in this field can be used for internal reporting only.

Example

<MERCHANT_URL>www.myStore.com</MERCHANT_URL>



0000

1010 √

1020

MIN_PAYMENT_AMOUNT Request Element Minimum payment that the merchant expects to be paid after currency conversion.

Type Length

AN 3

Values

Account Definition CC Transaction processed from credit card account.


Description

This field represents the minimum payment the merchant expects to be paid after currency conversion. The field is used to support the minimum payment event linked to a recurring schedule.

Example

<MIN_PAYMENT_AMOUNT>19.95</MIN_PAYMENT_AMOUNT>


of 165



0000 √

1010 √

1020 √

MINUTES Request Element Quantity of minutes purchased by the customer for telecommunication.

Type Length N 3

Description

This field contains the quantity of minutes purchased by the customer for telecommunication service including local and long distance calls, credit card calls, calls through use of magnetic stripe-reading telephones, and facsimile services. This field is only required for merchants with Merchant Category Code (MCC)/Standard Industrial Classification (SIC) code 4814.

Example

<MINUTES>120</MINUTES>



0000

1010 √

1020

MVV Request Element Optional Merchant Verification Value for Visa tax payments.

Type Length

AN 10

Description

This field contains the Merchant Verification Value for Visa tax payments, assigned to the merchant by their acquirer and Visa enrollment in the program. This is an optional field.


of 165

Example

<MVV>12345ABCDE</MVV>



0000

1010 √

1020 √

OPERATOR Request Element Optional identifier for the operator or location that generated the transaction.

Type Length

AN 10

Description

This field allows the merchant to provide the name/identifier of the operator or location responsible for the transaction generation (e.g., John Doe or Web site 3). This is an optional field.

Example

<OPERATOR>Jane Doe</OPERATOR>



0000 √ √ √ √

1010 √ √ √ √ √

1020 √ √ √ √

P3DS_PA_REQUEST Response Element An encoded authentication request sent to the access control server from the cardholders’ browser to complete 3-D Secure authentication.

Type Length

AN 2048

Description

This field is an encoded authentication request to be sent to the access control server from the cardholders’ browser in order to complete 3-D Secure authentication.


of 165

Note: See the iPay Gateway API Guide for Domestic and Multi Currency Payments for more information on 3-D Secure functionality.

Example

<P3DS_PA_REQUEST>…</P3DS_PA_REQUEST>



0000

1010 √ √ √

1020

P3DS_TRANSACTION_ID Request Element The Transaction ID received from a 3D Secure transaction supplied from the 3D Secure provider.

Type Length AN 1000

Description

This field is the Transaction ID received from a 3-D Secure transaction supplied from the 3-D Secure provider.


See also P3DS_TRANSACTION_ID Response Element.

Example

<P3DS_TRANSACTION_ID>…</P3DS_TRANSACTION_ID>



0000

1010 √ √ √

1020


of 165

PHONE Request Element Optional phone number when a TYPE of DOMESTIC or INTERNATIONAL is added to the request.

Type Length

N 15 digits maximum

Description

This field can be the cardholder’s phone number or the merchant’s customer service number when a TYPE of DOMESTIC or INTERNATIONAL is added to the request. The DOMESTIC or INTERNATIONAL values should only be used with SERVICE=REPOSITORY. This is an optional field.

Example Cardholder Phone

<PHONE>3023260700</PHONE>

Example Merchant Service Number

<PHONE TYPE=”DOMESTIC”>8667044729</PHONE>


CC ACH DBT Recur Wallet Repository

0000 √

1010 √ √ √ √ √

1020 √ √ √ √

PIN Request Element Required iPay Gateway-assigned key for PLAIN TEXT transactions.

Type Length

N 4

Description

This field is the iPay Gateway-assigned key for PLAIN TEXT transactions.

Example

<PIN>4567</PIN>


of 165



0000 √ √ √ √

1010 √ √ √ √ √

1020 √ √ √ √

POSTAL_CODE Request Element Postal code that appears on the cardholder’s billing statement.

Type Length AN 9

Description

This field is the postal code that appears on the cardholder’s billing statement.

Example

<POSTAL_CODE>99999</POSTAL_CODE>



0000

1010 √ √ √ √ √

1020 √ √ √ √

PROCESS_RESIDUAL Request Element Required indicator of whether a DEBIT or CREDIT should be processed for a deleted or replaced recurring schedule.

Type Length

AN 1

Values

Value Definition Y If BILLING_METHOD=PRE, the customer is CREDITED for the unused portion of the

schedule. If BILLING_METHOD=POST, the PROCESS_RESIDUAL value is ignored.


of 165

Value Definition N If BILLING_METHOD=PRE, the customer receives no credit for the unused portion of

the schedule. If BILLING_METHOD=POST, the PROCESS_RESIDUAL value is ignored.

Description

This field is used to indicate whether the system should process a DEBIT or CREDIT for a deleted or replaced recurring schedule. A CREDIT applies to schedules designated with a BILLING_METHOD=PRE and DEBIT applies to schedules designated with a BILLING_METHOD=POST.


Example

<PROCESS_RESIDUAL>Y</PROCESS_RESIDUAL>



0000 √

1010 √

1020 √

PRODUCT_BILLING Request Element How the billing is to be processed for the product.

Type Length N 1

Values

Value Definition

0 (zero) Recurring payments will be applied. See the iPay Gateway API Guide for Recurring Payments for more information.

1 One time transaction will be applied.

2 Wallet functionality will be applied

Description

This field identifies how the billing will be processed for the product.


of 165

Example

<PRODUCT_BILLING>0</PRODUCT_BILLING>



0000 √

1010

1020

PRODUCT_DESCRIPTION Request Element Description of a product.

Type Length

AN 100

Description

This field is the description of a product.

Example

<PRODUCT_DESCRIPTION>My Product Description</PRODUCT_DESCRIPTION>



0000 √

1010

1020

PRODUCT_ID Request Element A unique iPay Gateway-generated identifier for a newly created PRODUCT.

Type Length

AN 19

Description

This field is a unique identifier generated and returned by the iPay Gateway for a newly created PRODUCT. This identifier is used for the life of the PRODUCT and must be supplied for a MODIFY or DELETE of the PRODUCT or an INSERT of a TEMPLATE. A billing template must be linked to an active product by providing this value.


of 165


This ID is unique to the <REQUEST KEY = ""> for which it was generated, and each dependent transaction must be submitted with the originating <REQUEST KEY = "">. Example: a TRANSACTION REQUEST is submitted under KEY "8990". Any relevant (e.g., DELETE or MODIFY) TRANSACTION that requires this ID must be submitted using KEY "8990".

Note: <REQUEST KEY = ""> is also referenced as COMPANY_KEY.

See also PRODUCT_ID Response Element.

Example

<PRODUCT_ID>0999B10WTW3YYDPWQ5R</PRODUCT_ID>



0000 √ √

1010

1020

PRODUCT_NAME Request Element Name of a product.

Type Length

AN 50

Description

This field is the name of a product.

Example

<PRODUCT_NAME>My Product Name</PRODUCT_NAME>



0000 √

1010

1020


of 165

PRODUCT_URL Request Element Uniform resource locator (URL) of a product.

Type Length

AN 100

Description

This field is the Uniform resource locator (URL) of a product.

Example

<PRODUCT_URL>http://www.iPAY.com</PRODUCT_URL>



0000 √

1010

1020

QUERY_TYPE Request Element The manner in which a query will be performed.

Type Length

N 1

Values

Value Definition 0 (zero) A transactional or detail level query request.

1 (one) A group query request.

Description

This field defines the manner in which the query will be performed.

Example

<QUERY_TYPE>1</QUERY_TYPE>


of 165



0000 √

1010

1020

RETRY_COUNT Request Element Optional number of times a specific recurring transaction is resubmitted for payment if a recoverable billing cycle fails. Required with RETRY_INTERVAL.

Type Length

N 1

Description

In the event of a recoverable billing cycle failure, this field sets the number of times a specific recurring transaction is resubmitted for payment. If the retry count is reached without a successful completed transaction, the schedule is automatically canceled. This field must be a valid one-digit number between 1 and 4, inclusive. This field is optional but is required with RETRY_INTERVAL. This function is for credit card transactions only.


Example

<RETRY_COUNT>3</RETRY_COUNT>



0000 √

1010 √

1020 √


of 165

RETRY_INTERVAL Request Element Optional number of days between rebill retries if a recoverable billing cycle fails. Required when using RETRY_COUNT.

Type Length

N 2 digits between 1 and 99, inclusive

Description

In the event of a recoverable billing cycle failure, this field sets the number of days between rebill retries. The product of the RETRY_INTERVAL and RETRY_COUNT cannot exceed the rebill cycle (e.g., if the customer is billed weekly, the retry interval multiplied by the retry count cannot exceed 7 days).


For a list of recoverable failures, please see the ARC Response Element. If RETRY_INTERVAL is not included, the transaction would not be resubmitted in the event of a recoverable failure. This function is for credit card transactions only.

Note: Merchants are responsible for setting RETRY_COUNT and RETRY_INTERVAL values in accordance with card association regulations.

Example

<RETRY_INTERVAL>2</RETRY_INTERVAL>



0000 √

1010 √

1020 √

ROUTING_NUMBER Request Element Account holder’s financial institution.

Type Length

N 9

Description

This field identifies the account holder’s financial institution. The merchant should validate the ABA/Routing and Transit number before submitting transactions using the Modulus 9 check.


of 165

Example

<ROUTING_NUMBER>072401006</ROUTING_NUMBER>



0000

1010 √ √ √

1020

SCHEDULE_CHARGE_DATE Request Element First payment date of a new schedule or the next payment date of a schedule that has started. Required if a trial period is not included in the schedule.

Type Length N 8 digits fixed in format YYYYMMDD

Description

This field indicates the first payment date of a new schedule or the next payment date of a schedule that has started. This date must equate to the FREQUENCY_DAY or FREQUENCY_DATE value provided. This condition applies to the following:


• CLIENT, ACCOUNT, or SCHEDULE INSERT.

• SCHEDULE MODIFY of SCHEDULE_CHARGE_DATE before SCHEDULE has started.

• SCHEDULE MODIFY of SCHEDULE_CHARGE_DATE and frequency.

For example, if the merchant chooses a frequency of the 15th of every month, the charge date must be the 15th of the starting month.

This field can also be used to modify the next schedule payment date regardless of the frequency. This can be achieved by modifying only the SCHEDULE_CHARGE_DATE field. This modification can affect future payments if the SCHEDULE_CHARGE_DATE is less than the next scheduled payment. See the examples below for usage.

Example Monthly Schedule on the 15th of Every Month In this example, the SCHEDULE is MONTHLY on the 15th of every month, and the schedule started 01/15/12.

• The current date is 01/18/12.

• The SCHEDULE_CHARGE_DATE was modified with a value of 01/20/12.

• The transaction runs as requested on 01/20/12.

• The next scheduled payment is 02/15/12.


of 165

Note: Modifying the SCHEDULE_CHARGE_DATE to a date less than the next scheduled charge date allows for a transaction to be run in between billing intervals. The next scheduled payment date is not affected.

Example Monthly Schedule on the First Weekday of Every Month In this example, the SCHEDULE is MONTHLY on the FIRST WEEKDAY of every month. The schedule started 02/01/12.

• The current date is 02/28/12.

• The SCHEDULE_CHARGE_DATE is modified with a value of 04/01/12.

• The 03/01/06 payment is skipped as dictated by the SCHEDULE_CHARGE_DATE modifyrequest.

• The transaction runs as requested on 04/01/12.

• The next scheduled payment would be 04/02/12 (first weekday of April) as defined in thefrequency for the SCHEDULE.

Note: Modifying the SCHEDULE_CHARGE_DATE to a date greater than the nextscheduled charge date allows for a transaction(s) to be skipped. The next scheduled payment date is defined after the SCHEDULE_CHARGE_DATE has occurred based on the frequency.

Note: If a CLIENT, ACCOUNT, or SCHEDULE INSERT includes a free trial period, SCHEDULE_CHARGE_DATE must not be included. In this case, the SCHEDULE_CHARGE_DATE is automatically calculated based on the SCHEDULE_START_DATE and the length of the free trial period.

Example

<SCHEDULE_CHARGE_DATE>20150401</SCHEDULE_CHARGE_DATE>



0000

1010 √

1020 √


of 165

SCHEDULE_DESCRIPTION Request Element Optional merchant-generated description for a newly created or modified recurring schedule.

Type Length

AN 50

Description

This field is a merchant-generated description for a newly created or modified recurring SCHEDULE. This is an optional field.


Example

SCHEDULE_DESCRIPTION>9.99 Monthly</SCHEDULE_DESCRIPTION>



0000 √

1010 √

1020 √

SCHEDULE_END_AMOUNT Request Element Required amount that must be reached to end the schedule if SCHEDULE_TYPE is END_AFTER_AMOUNT.

Type Length

N 10

Description

This field specifies the amount that must be reached to end the schedule. This field is required if SCHEDULE_TYPE is END_AFTER_AMOUNT. The decimal point is NOT implied.


Example

<SCHEDULE_END_AMOUNT>399.95</SCHEDULE_END_AMOUNT>


of 165



0000 √

1010 √

1020 √

SCHEDULE_END_COUNT Request Element Required number of billings that must be reached to end the schedule if SCHEDULE_TYPE is END_AFTER_AMOUNT.

Type Length

N 3

Description

This field specifies the number of billings that must be reached to end the schedule. This field is required if SCHEDULE_TYPE is END_AFTER_COUNT.


Example

<SCHEDULE_END_COUNT>8</SCHEDULE_END_COUNT>



0000 √

1010 √

1020 √

SCHEDULE_END_DATE Request Element Required date that must be reached to end the schedule if SCHEDULE_TYPE is END_AFTER_DATE.

Type Length N 8 digits in format YYYYMMDD

Description

This field specifies the date that must be reached to end the schedule. This field is required if SCHEDULE_TYPE is END_AFTER_DATE. This date cannot be a past date.


of 165

Note: If SCHEDULE_END_DATE is used in a billing template, all schedules referencing that billing template will end at the same time, regardless of start date or charge date. See the iPay Gateway API Guide for Recurring Payments for more information.

Example

<SCHEDULE_END_DATE>20150515</SCHEDULE_END_DATE>



0000 √

1010 √

1020 √

SCHEDULE_ID Request Element A unique iPay-generated identifier for a newly created SCHEDULE.

Type Length

AN 19

Description

This field a unique identifier generated and returned by the iPay Gateway for a newly created SCHEDULE. This identifier is used for the life of the SCHEDULE and must be supplied for a MODIFY or DELETE of the SCHEDULE. It can also be included in a regular CC or ACH transaction if you are charging this schedule customer outside of their scheduled billing cycle. Including it in this manner associates the transaction with the scheduled payments for reporting purposes.


This ID is unique to the <REQUEST KEY = ""> for which it was generated, and each dependent transaction must be submitted with the originating <REQUEST KEY = "">. For example, a TRANSACTION REQUEST is submitted under KEY "8990", and any relevant (e.g., DELETE or MODIFY) TRANSACTION that requires this ID must be submitted using KEY "8990".


See also SCHEDULE_ID Request Element.

Example

<SCHEDULE_ID>0681B10WTW3YYDPWQ5R</SCHEDULE_ID>


of 165



0000

1010 √ √

1020 √ √

SCHEDULE_START_DATE Request Element Start date for a recurring schedule.

Type Length N 8 digits fixed in format YYYYMMDD

Description

This field defines the start date for a recurring schedule. It must be a valid date greater than or equal to the present date. This is the date when the service offered by the merchant becomes active and available to the consumer.


Example

<SCHEDULE_START_DATE>20150612</SCHEDULE_START_DATE>



0000

1010 √

1020 √

SCHEDULE_TYPE Request Element Type of schedule requested.

Type Length

AN 16


of 165

Values

Value Definition

END_AFTER_AMOUNT Schedule ends when SCHEDULE_END_AMOUNT has been reached.

END_AFTER_COUNT Schedule ends when SCHEDULE_END_COUNT has been reached.

END_AFTER_DATE Schedule ends when SCHEDULE_END_DATE has been reached

NO_END Schedule does not end unless deleted or modified.

Description

This field indicates the type of schedule requested.


Example

<SCHEDULE_TYPE>END_AFTER_COUNT</SCHEDULE_TYPE>



0000 √

1010 √

1020 √

SELLER_ACCOUNTID Request Element Amex aggregator only: account ID of seller.

Type Length

AN 10

Description

This field contains the last 10 characters of an Aggregators specific seller or vendor account ID.

Example

<SELLER_ACCOUNTID>1234QR7890</SELLER_ACCOUNTID>


of 165



0000

1010 √

1020 √

SELLER_ACTUAL_NAME Request Element Amex aggregator only: actual name of seller (can have spaces).

Type Length AN 37

Description

This field contains the seller’s actual name. Spaces are allowed.

Example

<SELLER_ACTUAL_NAME>Katis Beach Umbrellas</SELLER_ACTUAL_NAME>



0000

1010 √

1020 √

SELLER_BUSINESSNAME Request Element Amex aggregator only: seller’s abbreviated name (no spaces).

Type Length AN 9

Description

This field contains the seller’s abbreviated name. Spaces are not allowed.

Example

<SELLER_BUSINESSNAME>KatisBeac</SELLER_BUSINESSNAME>


of 165



0000

1010 √

1020 √

SELLER_CITY Request Element Amex aggregator only: city name of seller’s location.

Type Length AN 21

Description

This field contains the name of the city of the seller’s location. If the city name is more than 21 characters, use proper and meaningful abbreviation when possible; do not truncate.

Example

<SELLER_CITY>Key West</SELLER_CITY>



0000

1010 √

1020 √

SELLER_COUNTRY_CODE Request Element Amex aggregator only: seller’s ISO country code.

Type Length

AN 3

Description

This field contains the ISO alpha or numeric country code. For example, the ISO alpha code for the United States is “USA” and the numeric code is “840”. Either value is acceptable.

Example

<SELLER_COUNTRY_CODE>USA</SELLER_COUNTRY_CODE>


of 165



0000

1010 √

1020 √

SELLER_EMAIL_ADDRESS Request Element Amex aggregator only: seller’s email address.

Type Length AN 19

Description

This field contains the email address of the seller.

Example

<SELLER_EMAIL_ADDRESS>[email protected]</SELLER_EMAIL_ADDRESS>



0000

1010 √

1020 √

SELLER_MCC Request Element Amex

aggregator only: seller’s Merchant Category Code (MCC). Type Length N 4

Description

This field contains the Merchant Category Code (MCC) of the seller that corresponds to the seller’s business type.

Example

<SELLER_MCC>5999</SELLER_MCC>


of 165



0000

1010 √

1020 √

SELLER_POSTAL_CODE Request Element Amex aggregator only: postal code of the seller’s location.

Type Length AN 15

Description

This field contains the postal code of the seller’s location.

Example

<SELLER_POSTAL_CODE>33040</SELLER_POSTAL_CODE>



0000

1010 √

1020 √

SELLER_REGION Request Element Amex aggregator only: region code of the seller’s location.

Type Length AN 3

Description

This field contains the region code that corresponds to the state, province or other country subdivision of the seller’s location. For example, the region code for California, USA is “CA”, Nova Scotia, Canada is “NS”, and Colima, Mexico is “COL”.

Example

<SELLER_REGION>FL</SELLER_REGION>


of 165



0000

1010 √

1020 √

SELLER_STREET Request Element Amex aggregator only: street address of the seller’s location.

Type Length AN 38

Description

This field contains the street address of the seller’s location.

Example

<SELLER_STREET>2320 N. Roosevelt Blvd.</SELLER_STREET>



0000

1010 √

1020 √

SELLER_TELEPHONE Request Element Amex aggregator only: seller’s telephone number.

Type Length N 10

Description

This field contains the seller’s telephone number.

Example

<SELLER_TELEPHONE>3052965000</SELLER_TELEPHONE>


of 165



0000

1010 √

1020 √

SEQUENCE_NUMBER Request Element Optional merchant-generated unique identifier.

Type Length N 6

Description

This field is a merchant-generated unique identifier. This number is echoed back to the merchant to assist in matching requests to response messages. This value is not stored. The use of this field is highly recommended when transmitting batch transactions, because it is needed to match the RESPONSE to a given REQUEST. This is an optional field.

See also SEQUENCE_NUMBER Response Element.

Example

<SEQUENCE_NUMBER>1</SEQUENCE_NUMBER>



0000 √ √ √ √ 1010 √ √ √ √ √

1020 √ √ √ √

SERVICE Request Element The type of transaction to be performed.

Type Length

AN 10


of 165

Values

Value Definition

ACH Electronic check transaction.

CC Credit card transaction.

DBT UP Secure (UPOP) transaction. This service is single-message where money moves automatically. Ecommerce (1010) only.

RECUR Recurring transaction.

WALLET Wallet transaction.

REPOSITORY Storage of an individual item represented by a unique ID which can be used as input into a transaction.

TEMPLATE Storage of a group of items represented by a unique ID with association to a specific Gateway service which can be used as input into a transaction within that SERVICE.

CURRENCY Currency transactions.

NETWORK Network transactions.

Description

This field is the identification of the type of transaction to be performed.

Example

<SERVICE>CC</SERVICE>



0000 √ √ √ √ 1010 √ √ √ √ √

1020 √ √ √ √

SERVICE_FORMAT Request Element Format identifier for the type of transaction.

Type Length N 4


of 165

Values

Value Definition

0000 Non-financial SERVICEs.

1010 Card not present (eCommerce, MOTO, etc.).

1020 Retail (card present).

Description

This field is the format identifier for the transaction type.

Example

<SERVICE_FORMAT>1020</SERVICE_FORMAT>



0000 √ √ √ √ 1010 √ √ √ √ √

1020 √ √ √ √

SERVICE_SUBTYPE Request Element Detailed information on the SERVICE to be performed.

Type Length

A 8

Values

Value Definition

AUTH Authorization request for funds available.

CAPTURE Move funds based on a previous authorization

DELETE Action performed on CLIENT, ACCOUNT, SCHEDULE, PRODUCT, or BILLING SERVICE_TYPE.

INSERT Action performed on CLIENT, ACCOUNT, SCHEDULE, PRODUCT, or BILLING SERVICE_TYPE.

MODIFY Action performed on CLIENT, ACCOUNT, SCHEDULE, PRODUCT, or BILLING SERVICE_TYPE.

REFUND Move funds from the merchant’s account to the account holder’s account.


of 165

Value Definition REPLACE Replaces a current recurring schedule with another recurring schedule (i.e., a

product upgrade).

SALE Authorize and move funds from the account holder’s account to the merchant’s account.

VOID Void a previous unsettled transaction.

QUERY Query data from the system.

REVERSAL Reverse a previous transaction.

AVS_ONLY Verifies the provided billing address associated with the card number, no funds are held.

Description

This field is the detailed information on the SERVICE to be performed.

Example

<SERVICE_SUBTYPE>AUTH</SERVICE_SUBTYPE>



0000 √ √ √ √ 1010 √ √ √ √ √

1020 √ √ √ √

SERVICE_TYPE Request Element The action to be performed on the SERVICE transaction.

Type Length AN 8

Values

Value Definition

ACCOUNT ACCOUNT record for recurring transaction.

BILLING BILLING template record.

CLIENT CLIENT record for recurring transaction.

CREDIT Credit account holder’s account.


of 165

Value Definition DEBIT Debit account holder’s account.

PRODUCT PRODUCT record.

SCHEDULE SCHEDULE record for recurring transaction.

RATE Rate record for currency transactions.

STATUS Status request for system or transaction.

Description

This field indicates the action to be performed on the SERVICE transaction.

Note: When issuing a CREDIT, the amount must not exceed the original sale amount. Multiple credits can be issued, but the SUM of these credits cannot exceed the original sale amount.

Example

<SERVICE_TYPE>CREDIT</SERVICE_TYPE>



0000 √ √ √ √ 1010 √ √ √ √ √

1020 √ √ √

SESSION_ID Request Element The unique web session identification number captured from the consumer’s web session on the merchant’s web site. Required for a Fraud Score Service call for ecommerce transactions.

Type Length AN 32

Description

This field is the unique web session identification number captured from the consumer’s web session on the merchant’s web site. This value is used to tie the Fraud Score Service call to the consumer’s web session with Kaptcha interaction. Please refer to iPay Gateway API Guide for Domestic and Multi Currency Payments for an overview of the fraud scoring system. This field is required to successfully perform a fraud scoring system call for ecommerce transactions (TRANSACTION_INDICATOR = 5, 6, or 7).


of 165

Example

<SESSION_ID>j3cshl3hduiniev20c4odcq5</SESSION_ID>



0000

1010 √ √ √

1020

SHIP_ADDR1 Request Element First line of the consumer’s shipping address.

Type Length

AN 30

Description

This field is one of two fields for the consumer’s shipping address.

Example

<SHIP_ADDR1>89 E. Main St.</SHIP_ADDR1>



0000

1010 √ √ √ √ √

1020 √ √ √ √

SHIP_ADDR2 Request Element Second line of the consumer’s shipping address.

Type Length

AN 30

Description

This field is one of two fields for the consumer’s shipping address.


of 165

Example

<SHIP_ADDR2>Apt. 101</SHIP_ADDR2>



0000

1010 √ √ √ √ √

1020 √ √ √ √

SHIP_CITY Request Element Consumer's ship-to city.

Type Length

AN 25

Description

This field is the consumer’s ship-to city.

Example

<SHIP_CITY>Auburn</SHIP_CITY>



0000

1010 √ √ √ √ √

1020 √ √ √ √

SHIP_COUNTRY Request Element Optional ship-to country of the consumer.

Type Length

AN 3

Description

This field is the three-character alpha International Standards Organization (ISO) 3166 country code. This is the ship-to country for the consumer. The value for this field must be referenced from the Country Code column in the Selected ISO Currency and Country Codes. This is an optional field.


of 165

Example

<SHIP_COUNTRY>USA</SHIP_COUNTRY>



0000

1010 √ √ √ √ √

1020 √ √ √ √

SHIP_PHONE Request Element Optional phone number of the consumer.

Type Length

N 15

Description

This field is the consumer’s phone number for shipping purposes. This is an optional field.

Example

<SHIP_PHONE>2545551212</SHIP_PHONE>



0000

1010 √ √ √ √ √

1020 √ √ √ √

SHIP_POSTAL Request Element Consumer's ship-to postal code.

Type Length

AN 9

Description

This field is the consumer’s ship-to postal code.


of 165

Example

<SHIP_POSTAL>77389</SHIP_POSTAL>



0000

1010 √ √ √ √ √

1020 √ √ √ √

SHIP_STATE Request Element Consumer's ship-to state.

Type Length

AN 2

Description

This field is the ship-to state for the consumer. Valid state abbreviations can be found on the U.S. postal service’s web site, www.usps.com. For non-US addresses, a value of XX should be passed in the SHIP_STATE field for transactions where the field is required.

Example

<SHIP_STATE>TX</SHIP_STATE>



0000

1010 √ √ √ √ √

1020 √ √ √ √

SITE Request Element Optional designation of the merchant’s web site for use in the fraud scoring system.

Type Length

AN 8


of 165

http://www.usps.com/

Description

This field is used to designate the merchant’s web site for use in the fraud scoring system. This is an optional field. Refer to the iPay Gateway API Guide for Domestic and Multi Currency Payments for an overview of the fraud scoring system.

Example

<SITE>WebSite1</SITE>



0000

1010 √ √ √ √

1020

STATE Request Element State that appears on the cardholder’s billing statement.

Type Length AN 2

Description

This field is the state that appears on the cardholder’s billing statement. Valid state abbreviations can be found on the U.S. postal service’s web site, www.usps.com. For non-US addresses, a value of XX should be passed in the STATE field for transactions where STATE is required.

Example

<STATE>OH</STATE>



0000

1010 √ √ √ √ √

1020 √ √ √ √


of 165

http://www.usps.com/

TAX_AMOUNT Request Element Optional tax amount applied to the transaction.

Type Length

N 7

Description

This field is the tax amount applied to the transaction can be recorded in this field. The TAX_AMOUNT is not calculated by the iPay Gateway. The decimal point is NOT implied. The SUM of TIP_AMOUNT and TAX_AMOUNT must not exceed the value in the AMOUNT field. This is an optional field.

Example

<TAX_AMOUNT>36.48</TAX_AMOUNT>



0000

1010 √ √ √ √ √

1020 √ √ √ √

TERMINAL_ID Request Element iPay Gateway-assigned ID for the device that will be performing transactions with the iPay transaction servers.

Type Length AN 15

Description

This field is the iPay Gateway-assigned ID for the device that will be performing transactions with the iPay transaction servers. Multiple TERMINAL_IDs can be assigned per account based on the number of devices performing transactions. A device can be defined as, but is not limited to, a specific web site, personal computer, handheld device, or card-swipe terminal. If your company has multiple terminals and each terminal has its own TERMINAL_ID, and if only one terminal is sending incorrect or fraudulent information, the iPay Gateway would have the ability to shut this one terminal down without interrupting the remainder of the terminals doing business. If a merchant does not choose multiple TERMINAL_IDs, and, for any reason, the ID needs to be deactivated, all terminals would be affected. It is the merchant’s responsibility to request multiple TERMINAL_IDs.

See also TERMINAL_ID Response Element.


of 165

Example

<TERMINAL_ID>1234</TERMINAL_ID>



0000 √ √ √ √

1010 √ √ √ √ √

1020 √ √ √ √

TICKET Request Element Optional

merchant-assigned receipt or invoice number. Type Length

AN 30

Values

Valid Characters Note ABCDEFGHIJKLMNOPQRSTUVWXZY0123456789 Alpha characters can be upper and/or

lower case.

Description

This field contains the merchant-assigned receipt or invoice number. This is an optional field.

Example

<TICKET>7859943287</TICKET>



0000

1010 √ √ √ √

1020 √ √ √

TIP_AMOUNT Request Element Optional tip amount applied to the transaction.

Type Length

N 7


of 165

Description

This field is the tip amount applied to the transaction can be recorded in this field. The decimal point is NOT implied. The SUM of TIP_AMOUNT and TAX_AMOUNT must not exceed the value in the AMOUNT field. This is an optional field.

Example

<TIP_AMOUNT>28.75</TIP_AMOUNT>



0000

1010

1020 √

TRACK_DATA Request Element Information produced when the account holder’s credit card is swiped or electronically read.

Type Length

AN Length for ISO Track 1 Format Length must be equal to or greater than 16 and less than or equal to 76 characters

Length for ISO Track 2 Format Length must be equal to or greater than 7 and less than or equal to 37 characters

Values for ISO Track 1 Format

Size Value Description

1 % Start sentinel.

1 B Format code for track 1.

19 4500############ Primary account number.

1 ^ Separator.

26 John Card holder name.

1 ^ Separator.

4 YYMM Card expiration date.

3 ### Service code.


of 165

Size Value Description variable Optional issuer data.

1 ? End sentinel Track 1 data.

1 Longitudinal redundancy check.

79 Maximum record length.

Values for ISO Track 2 Format

Size Value Description

1 ; Start sentinel.

19 4500############ Primary account number.

1 = Separator.

4 YYMM Card expiration date.

3 ### Service code.

variable Optional issuer data.

1 ? End sentinel track 2 data.

1 Longitudinal redundancy check.

40 Maximum record length.

Description

This field is the information that is produced when the account holder’s credit card has been swiped or electronically read. This field is alphanumeric with a maximum length of 79 characters. TRACK_DATA must be populated when ENTRY_MODE value is equal to 1. Start, end, and LRC sentinels must be stripped before submitting a transaction. TRACK_DATA must be base64 encoded because not all card encoding follows ISO standards. Invalid characters can be contained within the track that could conflict with XML. Merchant should only submit one TRACK_DATA type (Track 1 or Track 2) per transaction. The iPay Gateway supports Track 1 and Track 2 data only; Track 3 data is not supported.

Note: This data cannot be stored anywhere and is available for real-time transactions only. It is a violation of card association regulations to store track data.

Track data can only be transmitted in this field. For data security reasons, these data are not permitted to be sent in any other field. Merchants who send these data in any custom fields are subject to investigation and possible termination.

Example

Track 2 Data 4111111111111111=07121011000025915 <TRACK_DATA>NDExMTExMTExMTExMTExMT0wNzEyMTAxMTAwMDAyNTkxNQ==</TRACK_DATA>


of 165



0000

1010

1020 √ √ √

TRANSACTION_ID Request Element Unique iPay Gateway-generated identifier for each transaction.

Type Length AN 19

Description

This is a unique identifier generated and returned by the iPay Gateway for each transaction. This identifier is used to match related transactions (e.g., AUTH to a CAPTURE or SALE to a VOID). This field is unique to the <REQUEST KEY = ""> for which it was generated; each matching transaction must be submitted with the originating <REQUEST KEY = "">.

When providing the TRANSACTION_ID with a CAPTURE or REVERSAL transaction, several fields are referenced from the original AUTH transaction. Including these authorization addenda records with the CAPTURE transactions allows you to receive the best processing rate. Therefore, you must ensure that the TRANSACTION_ID is included with all CAPTURE transactions that originated as an iPay Gateway AUTH transaction.

Optional data can be supplied and will be stored with the CAPTURE transaction (see below for the excluded fields).


Excluded Capture Fields ACCOUNT_NUMBER

ADDRESS

APPROVAL_CODE

CITY

COUNTRY

ENTRY_MODE

EXPIRATION

FIRST_NAME

LAST_NAME


of 165

MEMBER_NUMBER

PHONE

POSTAL_CODE

TRANSACTION_INDICATOR

STATE

See also TRANSACTION_ID Response Element.

Example

<TRANSACTION_ID>0350YJ3FQ9R60Y7BAKT</TRANSACTION_ID>



0000

1010 √ √ √

1020 √ √

TRANSACTION_INDICATOR Request Element How the account information was captured between the cardholder and the merchant.

Type Length AN 1

Values

Value Definition

M Account information captured through the mail.

P Account information captured at the point of purchase (ACH only).

T Account information captured through a telephone call.

2 Recurring transactions excluding installment payments. Initial order must have the correct indicator of how the transaction originated between the cardholder and merchant. The Gateway recurring system will send a value of 2 for all subsequent recurring transactions. Merchant must obtain written authorization from account holder to perform recurring transactions.

5 Authenticated transaction.

6 Authentication attempted but failed.


of 165

Value Definition 7 Account information was received from a secured Internet site. This information

must be encrypted (SSL or RSA) between the cardholder and the merchant. Merchants are required to provide the following information to the iPay Gateway upon setup and ongoing certificate renewals:

• Name of certificate issuer.

• Merchant certificate number.

• Expiration date of merchant certificate.

• Ownership status of certificate if shared or individual.

Note: ACH REFUND without TRANSACTION_ID must use values M or T.

Description

This field is used to identify how the account information was captured between the cardholder and the merchant, regardless of how the authorization was performed. For CC CREDIT/REFUND transactions, the original transaction indicator must be used from the SALE/CAPTURE transaction.

For example:

• The customer logs on to the merchant's web site to purchase an item, and the accountinformation is submitted on the web site for the item to be purchased. In this example, aTRANSACTION_INDICATOR of 7 should be sent in the transaction request.

• The customer logs on to the merchant's web site to purchase an item that cost $1500.00. Thecustomer agrees to initially pay $500.00 down and provides his or her account information onthe Web site. The customer also agrees to recurring payments for the remainder of thebalance. In this example, the transaction request for the initial $500.00 should contain aTRANSACTION_INDICATOR of 7. The recurring payments should be sent with aTRANSACTION_INDICATOR of 2.

• The customer calls the merchant to order an item; the account information is given to themerchant on the telephone for the item to be purchased. In this example, aTRANSACTION_INDICATOR of T should be sent in the transaction request.

• A customer purchases an item from a catalog or mailing provided by the merchant, and thecustomer sends his or her account information along with the items to be purchased back tothe merchant via mail. In this example, a TRANSACTION_INDICATOR of M should be sent inthe transaction request.

• The customer presents a check to collect his or her routing number, account number, andcheck serial number (the check should be voided by the merchant and returned to theconsumer at the point-of-purchase). These data are used to generate a debit ACH entry to thecustomer's account. In this example, a TRANSACTION_INDICATOR of P should be sent inthe transaction request.

Note: The merchant may not key-enter the routing number, account number, or checkserial number from the customer’s check. The information must be read electronically.


of 165

Example

<TRANSACTION_INDICATOR>M</TRANSACTION_INDICATOR>



0000

1010 √ √ √ √ √

1020 √

TRIAL_AMOUNT Request Element One-time amount for a trial period.

Type Length

N 12

Description

This field contains the one-time amount for a trial period. If a TRIAL_AMOUNT is being sent in, the transaction must also include the parameters for a trial period (i.e., FREQUENCY_INTERVAL with TYPE=TRIAL and FREQUENCY_TYPE with TYPE=TRIAL must also be included or the transaction will fail). The TRIAL_AMOUNT transaction is billed is on the SCHEDULE_START_DATE. If the SCHEDULE_START_DATE is the current date, the transaction will be billed immediately. The TRIAL_AMOUNT cannot be modified once a schedule has started.


The decimal is NOT implied, and merchants should send data that is rounded appropriately for the requested currency. For currency using a dollar as the base unit, amounts must be rounded to two decimal places.

Example

<TRIAL_AMOUNT>9.99</TRIAL_AMOUNT>



0000 √

1010 √

1020 √


of 165

UP_COMMODITYDISCOUNT Request Element Optional discounted amount based on a coupon or other discount method.

Type Length

N 12

Description

This field represents the discounted amount based on a coupon or other discount method. It indicates the difference between the original amount and the actual amount of the transaction. For example, if the original amount of the transaction is 100.00, and a 10% discount is given, the UP_COMMODITYDICOUNT value would be 10.00. This is an optional field.

Example

<UP_COMMODITYDISCOUNT>10.00</UP_COMMODITYDISCOUNT>



0000

1010 √

1020

Optional merchant’s order information.

Type Length

AN 256

Description

This field is the merchant’s order information. This is an optional field.

Example

<UP_COMMODITYNAME>test order info 54321</ UP_COMMODITYNAME >



0000

1010 √

1020


of 165

UP_COMMODITYQUANTITY Request Element Optional total quantity of goods for this purchase.

Type Length

N 10

Description

This field is the total quantity of goods for this UPOP purchase.

Note: See the iPay Gateway API Guide for UNIONPAY Secure (UPOP) Payments for more information.

Example

<UP_COMMODITYQUANTITY>5</UP_COMMODITYQUANTITY>



0000

1010 √

1020

UP_COMMODITYUNITPRICE Request Element Optional price of a single good for this purchase.

Type Length

N 12

Description

This field is the price of a single good for this UPOP purchase. This is an optional field.


Example

<UP_COMMODITYUNITPRICE>19.95</UP_COMMODITYUNITPRICE>


of 165



0000

1010 √

1020

UP_COMMODITYURL Request Element Optional merchant’s website URL where the goods are sold.

Type Length AN 1024

Description

This field is the merchant’s website URL where the goods are sold for a UPOP transaction.


Example

<UP_COMMODITYURL>https://shop.merchanturl.com</UP_COMMODITYURL>



0000

1010 √

1020

UP_CUSTOMERNAME Request Element Optional cardholder name.

Type Length

AN 20

Description

This field is the name of the cardholder for a UPOP transaction. This is an optional field.



of 165

Example

<UP_CUSTOMERNAME>Joseph Lee</UP_CUSTOMERNAME>



0000

1010 √

1020

UP_DEFAULTBANKNUMBER Request Element Optional default preferred issuer code.

Type Length

N 11

Description

This field is the default preferred issuer code for a UPOP transaction. It corresponds to the bankcard when the cardholder is shopping on the merchant’s website. This is an optional field.


Example

<UP_DEFAULTBANKNUMBER>…</UP_DEFAULTBANKNUMBER>



0000

1010 √

1020

UP_DEFAULTPAYTYPE Request Element Optional cardholder default preferred payment method.

Type Length

AN 20


of 165

Description

This field indicates the default preferred payment method of the cardholder for a UPOP transaction. This is an optional field.


Example

<UP_DEFAULTPAYTYPE>UP Card</UP_ DEFAULTPAYTYPE>



0000

1010 √

1020

UP_FRONTENDURL Request Element Optional URL of the merchant’s website for UPOP to redirect the cardholder after the cardholder has completed payment on UPOP’s website.

Type Length AN 256

Description

This field indicates the URL of the merchant’s website for UPOP to redirect the cardholder after the cardholder has completed the payment on UPOP’s website. This is an optional field.


Example

<UP_FRONTENDURL>https://shop.com/UPOPredir/</UP_FRONTENDURL>



0000

1010 √

1020


of 165

UP_FRONTENDFAILURL Request Element Optional URL of the merchant’s website for UPOP to redirect the cardholder, if a transaction fails on the UPOP website.

Type Length

AN 256

Description

Optional in the First-Pass Auth or Sale transaction. If provided in the API request, UPOP should display a “Return to Merchant” button to the user, when the transaction fails on the UPOP web site.

When the “Return to Merchant” button is clicked, the user will be directed to the URL provided in the UP_FRONTENDFAILURL field.


Example

<UP_FRONTENDFAILURL>https://shop.com/UPOPfail/</UP_FRONTENDURL>



0000

1010 √

1020

UP_TRANSFERFEE Request Element Optional information for transportation cost.

Type Length N 12

Description

This field provides information about the transportation cost for a UPOP transaction. This is an optional field.



of 165

Example

<UP_TRANSFERFEE>https://shop.com/UPOPredir/</UP_TRANSFERFEE>



0000

1010 √

1020

USER_DATA Request Element Optional additional user data fields to allow merchants to assign values to a transaction.

Type Length

AN 50

Description

These fields are the additional user data fields to allow merchants to assign values to a transaction. There are 20 USER_DATA fields available, indexed 0 through 19. This is an optional field.

Example

<USER_DATA_0>Golf Clubs</USER_DATA_0>


of 165



0000

1010 √ √ √ √

1020 √ √ √

VERBOSE_RESPONSE Request Element Optional request that the original TRANSACTION data be returned in the response message.

Type Length

N 1

Values

Value Definition 1 All transaction data provided in the original request is returned, along with

all Response Elements, provided that the conditions for those response elements were met in the original transaction.

Description

This field requests that the original TRANSACTION data be returned in the response message. If this field is not present, only the fields listed for Response Elements and the MRC Response Element are returned, depending on the transaction type and data provided in the original transaction. This is an optional field.

Example

<VERBOSE_RESPONSE>1</VERBOSE_RESPONSE>



0000 √ √ √ √ 1010 √ √ √ √ √

1020 √ √ √ √


of 165

XID Request Element Optional unique merchant-assigned tracking ID for Verified by Visa transactions.

Type Length

AN 20 characters fixed (28 character base64 encoded)

Description

This field contains a unique merchant-assigned tracking ID for Verified by Visa transactions. These data must be base64 encoded due to possible unprintable characters within this field. This field is used only with 3-D Secure transactions.


See also XID Response Element.

Example

<XID>clhaaHB3U0hveURrdFFsE5dPa00=</XID>



0000

1010 √ √

1020


of 165

CHAPTER 3 Transaction Response Messages Transaction requests generally return a response in fewer than five seconds. This number can increase based on the merchant's connection speed and the time in which the issuing bank returns a response from the authorization request. The issuing bank can return a response up to thirty seconds after the authorization request, so setting the timeout value in your application equal to this maximum allowable time is recommended. Merchants using value-added services such as fraud scoring or 3-D Secure may need to increase their timeout value (up to 45 seconds or more) to accommodate the additional processing time that these services require.

Response Elements Response messages vary depending on the merchant’s use of the VERBOSE_RESPONSE field in the original transaction. The iPay Gateway may return FIELD(S) not submitted in the original transaction. These FIELD(S) are only present when VERBOSE_RESPONSE is requested. The additional FIELD(S) are used internally and should and can be ignored.

The following table lists all response fields transmitted. The fields returned are conditional, based on the transaction type and the data provided in the transaction. See each field definition for conditions.

Note: To avoid the MRC ‘NF’ Trans Not Found error when performing transactions that require a TRANSACTION_ID, the merchant should leave a 3–5 second delay between the originating REQUEST and any REQUEST that requires the TRANSACTION_ID returned from that originating REQUEST. For example, a merchant performs an AUTH transaction at 11:50:22. The merchant should wait until at least 11:50:25 to perform a CAPTURE on the transaction. This allows enough time for the original transaction to be distributed throughout the iPay Gateway.

Response ELEMENT ELEMENT_VALUE Type Length

AAV Account holder Authentication Value. AN 32

AAV_RESPONSE Account holder Authentication Value Response. AN 1

ACCOUNT_DESCRIPTION Description of the account type for Wallet Insert transactions. AN 13

ACCOUNT_ID Unique account identifier. AN 19

AMOUNT Amount of the original transaction. N 18

APPROVAL_CODE Transaction approval code. AN 6


of 165


ARC Authorization response code from service provider. AN 2

AVS_RESPONSE Address Verification Response. AN 1

BATCH_ID Batch ID from original transaction. AN 40

BILLING_ID Unique billing template identifier. AN 19

CARD_TYPE Card type(s) applicable to the exchange rate. AN 40

CARDHOLDER_AMOUNT [PYC] The amount the cardholder will see on their statement. N 12

CARDHOLDER_CURRENCY_CODE [PYC] The cardholder’s home currency. AN 3

CLIENT_ID Unique client identifier. AN 19

COMMERCIAL_RESPONSE Commercial card response indicator. AN 1

COMPANY_KEY Unique number assigned to a merchant’s company. N 10

CVV_RESPONSE Card Verification response code. AN 1

EXCHANGE_RATE Present exchange rate applied to transaction. N 10

FINANCIAL_TRAN_ID Financial transaction identifier for WALLET and RECUR transactions.

AN 19

FRAUD_AUTO

Fraud system’s AUTO response value - drives soft decline decision if requested by merchant.

AN 1

FRAUD_ERROR(S) Fraud system’s error codes and descriptions. AN 50

FRAUD_GEOX

Fraud system’s GEOX response value - the worst country associated with the customer in the last 14 days.

AN 2

FRAUD_KAPT

Fraud system’s KAPT response value - indicates if a fraud scoring system message has a corresponding Kaptcha record.

AN 1

FRAUD_KYCF Fraud system’s KYCF response for “know your customer flag”. AN 1


of 165


FRAUD_REAS Fraud system’s REAS response that explains the reason for the AUTO response.

AN 4

FRAUD_REGN Fraud system’s REGN response for US State abbreviation or FIPS 10-4 region code.

AN 2

FRAUD_RULE(S) Fraud system’s rule codes and descriptions. AN 50

FRAUD_SCOR Fraud system’s fraud SCOR value – the numeric fraud risk score (1-99).

N 2

FRAUD_SESS Session ID associated with thefraud scoring system transaction. AN 32

FRAUD_TRAN Fraud system’s transaction ID. AN 32

FRAUD_VELO Fraud system’s VELO value – total number of prior sales by this customer in the last 14 days.

N 2

FRAUD_WARNING(S) Fraud system’s warning codes and descriptions. AN 50

FRC iPay’s fraud response code to indicate success or failure of fraud service call.

AN 2

FXASSURED_MARKUP

[PYC] The rate differential between the rate that the issuer would charge the cardholder for performing the transaction in the merchant currency and the rate charged by iPay.

N 10

LOCAL_DATE Local transaction date. N 8

LOCAL_TIME Local transaction time. N 6

MRC Message response code from the iPay Gateway. AN 2

P3D3_ACS_URL Fully qualified URL of the 3D Secure Access Control Server. AN 2083

P3D3_ARS Code describing 3D Secure authentication response status. AN 1

P3D3_CARD_ENROLLED Code describing 3D Secure enrollment status of card. AN 1


of 165


P3D3_PA_REQUEST

The encoded authentication request to be sent to the Access Control Server from the cardholders’ browser in order to complete 3-D Secure authentication.

AN 2048

P3D3_SRS Code describing the 3-D Secure signature response status. AN 1

P3D3_TRANSACTION_ID Transaction identifier received from the 3-D Secure provider. AN 20

PRODUCT_ID Unique product identifier. AN 19

PYC_EXCHANGE_RATE [PYC] The exchange rate for a PYC transaction. N 10

PYC_RATE_MARKUP [PYC] Markup expressed as a percentage value. N 10

RATE(S) Contains the report response data from CURRENCY RATE QUERY transaction.

AN -

RESPONSE_TEXT Text generated from response codes. AN 19

SCHEDULE_ID Unique schedule identifier. AN 19

SEQUENCE_NUMBER Sequence number from original transaction. N 6

TERMINAL_ID Terminal ID from original transaction. AN 15

TRANSACTION_ID Transaction identifier. AN 19

TRANSACTION_RESPONSECODE Response code of the queried transaction. N 2

TRANSACTION_RESPONSEMESSAGE Response message of thequeried transaction. AN 25

TRANSACTION_RESULTTYPE

Contains the transaction type of the original queried transaction (Authorization, Charge, Void, Refund).

AN 20

UP_ACTIONURL

The UPOP URL for the merchant to redirect the cardholder to complete the Auth or Sale transaction.

AN 256


of 165


UP_ORDERNNUMBER This is the unique order number for an Auth or Sale UPOP First-Pass transaction.

AN 32

UP_PAYLOAD The full HTML for the consumer redirect to UPOP. AN 3000

UP_SETTLEDATE The date (MMDD) in Beijing, China time zone that the UPOP transaction will settle.

N 4

XID Unique ID for Verified by Visa transactions. AN 20

AAV Response Element Authentication information for transactions that use Verified by Visa or MasterCard SecureCode.

Type Length AN Visa: 20 characters that equal a 28 alphanumeric string after base64 encoding

MC: 0 to 32 characters after base64 encoding

Description

This field holds the Account holder Authentication Value (AAV) information for transactions that have used the Verified by Visa or MasterCard SecureCode feature. For a complete description, see the AAV Request Element.

Example

<AAV>jFeqd/rqB4kdCBATUerPBJYAAAA=</AAV>

AAV_RESPONSE Response Element Whether the authentication value submitted by the merchant, can be validated by Visa or the issuer.

Type Length

AN 1


of 165

Values

Value Definition

0 AAV not validated because erroneous data were submitted.

1 AAV failed validation.

2 AAV passed validation.

3 AAV validation could not be performed; Issue attempt incomplete.

4 AAV validation could not be performed; Issuer system error.

5 Reserved for future use.

6 Reserved for future use.

7 AAV attempt – failed validation – issuer available (U.S.-issued card/non-U.S. acquirer).

8 AAV attempt –passed validation – issuer available (U.S.-issued card/non-U.S. acquirer).

9 AAV attempt – failed validation – issuer unavailable (U.S.-issued card/non-U.S. acquirer).

A AAV attempt – passed validation – issuer unavailable (U.S.-issued card/non-U.S. acquirer).

B AAV passed validation, information only, no liability shift.

Description

This field indicates whether the authentication value submitted by the merchant can be validated by Visa or the issuer. This field is only returned when provided by the authorization provider.

See also AAV Request Element.

Example

<AAV_RESPONSE>5</AAV_RESPONSE>

ACCOUNT_DESCRIPTION Response Element Summarizes the account type in relation to the new ACCOUNT_ID.

Type Length

AN 15


of 165

Values

Value Definition

VISA VISA credit card type.

MC Master Card credit card type.

DSC Discover credit card type.

AMEX AMEX credit card type.

JCB JCB credit card type.

CHECKING Checking account for ACH.

SAVINGS Savings account for ACH.

Description

This field summarizes the account type in relation to the new ACCOUNT_ID. This value is only returned on WALLET INSERT transactions and includes the abbreviated credit card type or ACH account type with the last 4 characters of the account.

Note: See the iPay Gateway API Guide for Secure Tokens for more information.

Example

<ACCOUNT_DESCRIPTION>CHECKING 1256</ACCOUNT_DESCRIPTION>

ACCOUNT_ID Response Element A unique iPay Gateway-generated identifier returned for a newly created ACCOUNT.

Type Length AN 19

Description

This field a unique identifier generated and returned by the iPay Gateway for a newly created ACCOUNT. This identifier is used for the life of the ACCOUNT. The ACCOUNT_ID can be used to create new recurring schedules or one time transactions for both ACH and CC transaction types. See the various transaction processing guides for additional information. The ACCOUNT_ID must be supplied for a MODIFY or DELETE of the ACCOUNT. This field is only returned on a successful creation of an ACCOUNT.

See also ACCOUNT_ID Request Element.

Example

<ACCOUNT_ID>0381B10ETW3YYDPWR5Q</ACCOUNT_ID>


of 165

AMOUNT Response Element Amount of the requested transaction.

Type Length

N 18

Description

This field contains the transaction amount of the requested transaction. The decimal point is NOT implied. The merchant must provide decimal point for all monetary transactions. This field is only returned when provided in the original transaction.

See also AMOUNT Request Element.

Example

<AMOUNT>1.00</AMOUNT>

APPROVAL_CODE Response Element Authorization code when a transaction has been approved.

Type Length AN 6

Description

This field contains an authorization code when a transaction has been approved. If the ARC response code indicates that the transaction is not approved, the contents of the field should be ignored. This field is only returned when provided by the authorization provider.

Note: Approval codes are case-sensitive and must be returned exactly as received or downgrades could result.

See also APPROVAL_CODE Request Element.

Example

<APPROVAL_CODE>042191</APPROVAL_CODE>


of 165

ARC Response Element Authorization response codes (ARC) provided by the service provider processing the transaction.

Type Length

AN 2

Values

Code Text Description 00 (zero-zero)

APPROVAL Approval.

01 CALL See RESPONSE_TEXT for issuer phone number.

02 CALL See RESPONSE_TEXT for issuer phone number.

03 TERM ID ERROR Invalid merchant ID.

04 HOLD – CALL Pick up card.

05* DECLINE Do not honor.

06 ERROR General error.

07 PICKUP CARD Do not honor.

08 HONOR WITH ID Honor with customer ID.

10 PARTIAL APPROVAL Partial approval for the authorized amount returned.

11 APPROVAL VIP approval.

12* INVALID TRANS Invalid transaction.

13* AMOUNT ERROR Invalid transaction amount.

14* CARD NO. ERROR Invalid card number.

15* NO SUCH ISSUER No such issuer.

17 CUST CANCELATION Customer cancellation.

19* RE ENTER Re-enter transaction.

21 NO ACTION TAKEN Unable to back out transaction.

25* NO RECORD FOUND Unable to locate record in file, or account number is missing from inquiry.

27* ERROR Issuer File Update field edit error.

28* NO REPLY Temporarily unavailable.


of 165

Code Text Description 30* CALL Format error.

32 PARTIAL REVERSAL Partial reversal.

40 NOT SUPPORTED Requested function not supported.

41 HOLD-CALL Pickup card—lost.

43 HOLD-CALL Pickup card—stolen.

51* DECLINE Insufficient funds.

52 NO CHECK ACCOUNT No checking account.

53 NO SAVE ACCOUNT No savings account.

54* EXPIRED CARD Expired card.

55 WRONG PIN Incorrect PIN.

57 SERV NOT ALLOWED Transaction not permitted—card.

58 SERV NOT ALLOWED Transaction not permitted—terminal.

59 DECLINE Suspected fraud.

61* DECLINE Exceeds withdrawal limit.

62 DECLINE Invalid service code, restricted.

63 SEC VIOLATION Security violation.

65* DECLINE Activity limit exceeded.

68 LATE RESPONSE Response received late.

75 PIN EXCEEDED PIN tries exceeded.

76* NO ACTION TAKEN Unable to locate.

77* NO ACTION TAKEN Inconsistent data, rev. or repeat.

78* NO ACCOUNT No account.

79 ALREADY REVERSED Already reversed.

80 DATE ERROR Invalid date.

81* ENCRYPTION ERROR Cryptographic error.

82 INCORRECT CVV CVV data incorrect.

83 CANT VERIFY PIN Cannot verify PIN.

84 BAD LIFE CYCLE Invalid authorization life cycle.

85 CARD OK No reason to decline.

86 CANT VERIFY PIN Cannot verify PIN.

87 DECLINE Network unavailable.

91* NO REPLY Issuer unavailable.


of 165

Code Text Description 92* INVALID ROUTING Destination not found

93 DECLINE Violation, cannot complete.

94* DECLINE Duplicate transmission detected.

96* SYSTEM ERROR Re-send, system error.

3D Authenticate3DSecur Merchant/Cardholder enrolled in 3DSecure

AX EXCEEDS AMOUNT Amount exceeds either the minimum or maximum allowed amount.

B1 SURCHARGE NOT ALLOWED Surcharge amount not permitted on Visa cards or Electronic Benefit Transfer (EBT) food stamps.

ER ERROR Error—see MRC response.

N0* FORCE STIP Force STIP.

N3 CASHBACK NOT AVAIL Cash back service not available.

N4* DECLINE Exceeds issuer withdrawal limit.

N7 CVV2 MISMATCH CVV2 value supplied is invalid.

P2 INVALID BILL INFO Invalid biller information.

P5 PIN CHARGE/UNBLOCK DECLINED PIN charge/unblock declined.

P6 UNSAFE PIN Unsafe PIN.

PE AUTHENTICATE UPOP First-pass UPOP approved. Possible on first pass of UPOP Auth or Sale.

PF TRANSACTION PENDING Inquiry response code if the original UPOP Auth or Sale transaction is not complete during a follow-up transaction (Capture, Void, Refund, or Inquiry Request). Re-submit the follow-up transaction.

Q1 AUTHENTIC FAILED Card authentication failed.

R0 STOP RECURRING Customer requested stop of specific recurring payment.

R1 STOP RECURRING Customer requested stop of all recurring payments from specific merchant.

R3 ALL AUTH REVOKED Revocation of All Authorizations Order.

SD SOFT DECLINE Transaction is declined by the iPay Gateway based on merchant’s settings for ACCOUNT_VALIDATION and CONSUMER_VALIDATION.


of 165

Code Text Description TO (Tee-oh)*

TIME OUT Re-submit.

XA* FORWARD 2 ISSUER Forward to issuer

XD* FORWARD 2 ISSUER Forward to issuer.

Z3* UNABLE TO ONLINE Unable to go online, declined.

*A recoverable ARC for recurring transactions. If any other ARC is returned for a recurringtransaction, the schedule is automatically canceled.

Description

This field contains the authorization response codes (ARC) provided by the service provider processing the transaction, which could be from iPay or the consumer’s issuing bank. This response code notifies the merchant of the success or failure of the request. This field is always returned.

Example

<ARC>00</ARC>


of 165

AVS_RESPONSE Response Element Result of an address verification check.

Type Length

AN 1

Values

Code Text Description

0 (zero) CAPTURE (or decline reason) AVS not performed.

A ADDRESS MATCH Address match only.

B* ADDRESS MATCH Street address match. Postal code not verified.

C* SERV UNAVAILABLE Street address and Postal code not verified.

D* EXACT MATCH Street address and Postal match.

F* EXACT MATCH, ADDRESS MATCH, or ZIP MATCH

International (UK) transactions only. Response will show type of data match.

G INFO NOT VERIFIED Global non-AVS participant-address information.

I* VER UNAVAILABLE Address information not verified.

N NO MATCH No address or postal code match.

P* ZIP MATCH Postal Code. Street address not verified.

R RETRY Issuer system unavailable.

S SVC UNAVAILABLE Service not supported.

U VER UNAVAILABLE Address unavailable.

X EXACT MATCH Exact match: address and 9 digit postal code.

Y EXACT MATCH Exact match: address and 5 digit postal code

W ZIP MATCH 9-digit postal code match only.

Z ZIP MATCH 5-digit postal code match only.

*Denotes an International code. Their availability is limited based on issuer participation.International issuers may also send non-international codes.

Description

This field provides the result of the address verification check. This field is conditional based on the merchant’s profile and the request of the original transaction. This field is only returned for credit card transactions and is only returned when provided by the authorization provider.

Example

<AVS_RESPONSE>X</AVS_RESPONSE>


of 165

BATCH_ID Response Element Merchant-assigned ID to group multiple transactions together.

Type Length

AN 40

Description

This field is a merchant-assigned ID to group multiple transactions together. This field is only returned when provided in the original transaction. Merchants sending real-time or batched transactions are encouraged to use this field to assist with reconciliation. See BATCH_ID Request Element for more information and examples.

BILLING_ID Response Element A unique iPay Gateway-generated identifier returned for a newly created billing template.

Type Length

AN 19

Description

This field a unique identifier generated and returned by the iPay Gateway for a newly created billing template. This identifier is used for the life of the billing template and must be supplied for a MODIFY or DELETE of the billing template or a CLIENT_INSERT, ACCOUNT_INSERT, or SCHEDULE_REPLACE transaction.


See also BILLING_ID Request Element.

Example

<BILLING_ID>0999B10ZZZ3YYDPWQ5R</BILLING_ID>

CARD_TYPE Response Element Card type(s) applicable to the exchange rate for a given currency returned in response to a PYC CURRENCY RATE QUERY.

Type Length

AN 40

Description

This field contains the card type(s) applicable to the exchange rate for a given currency, and is returned in the response of a PYC CURRENCY RATE QUERY transaction.


of 165

Note: See the iPay Gateway API Guide for Domestic and Multi Currency Payments for more information on currency rate queries.

Example

<CARD_TYPE>VISA</CARD_TYPE>

CARDHOLDER_AMOUNT Response Element Amount to be charged/refunded to the cardholder.

Type Length AN 18

Description

This field contains the amount that will be charged/refunded to the cardholder, and will be reflected on the cardholder’s credit card statement. The decimal point is NOT implied. This field is only returned with a PYC AUTH, SALE, and CURRENCY RATE QUERY transaction.

Note: See the iPay Gateway API Guide for Domestic and Multi Currency Payments for more information on PYC functionality.

Example

<CARDHOLDER_AMOUNT>19.41</CARDHOLDER_AMOUNT>

CARDHOLDER_CURRENCY_CODE Response Element Currency code of the cardholder’s home currency.

Type Length N 3

Description

This field contains the currency code of the cardholder’s home currency. This field is only returned with a PYC AUTH, SALE, and CURRENCY RATE QUERY transaction. The 3-digit alphabetic value of the currency code is represented in attribute “alpha” in response messages. See Selected ISO Currency and Country Codes for more information.

Note: See the iPay Gateway API Guide for Domestic and Multi Currency Payments for more information on PYC functionality.


of 165

Example

<CARDHOLDER_CURRENCY_CODE Alpha=”GBP”>826</CARDHOLDER_CURRENCY_CODE>

CLIENT_ID Response Element A unique iPay Gateway-generated identifier for a newly created CLIENT.

Type Length

AN 19

Description

This field indicates a unique identifier generated and returned by the iPay Gateway for a newly created CLIENT. This identifier is used for the life of the CLIENT and must be supplied for a MODIFY or DELETE of the CLIENT. This field is only returned on a successful insert of a RECUR CLIENT.


See also CLIENT_ID Request Element.

Example

<CLIENT_ID>0381B103TW3YYDPWQ5R</CLIENT_ID>

COMMERCIAL_RESPONSE Response Element Type of commercial card submitted in the original transaction.

Type Length AN 1

Values

Value Definition

0 (zero) Non-commercial card.

B Business card.

R Corporate card.

S Purchasing card.

<SP> Space Invalid request indicator received.


of 165

Description

This field indicates the type of commercial card submitted in the original transaction. This field is only returned for credit card transactions and is only returned when provided by the authorization provider.

Example

<COMMERCIAL_RESPONSE>0</COMMERCIAL_RESPONSE>

COMPANY_KEY Response Element The unique iPay-assigned number that identifies a merchant in the system.

Type Length

N 10

Description

This field is the unique iPay-assigned number that identifies a merchant in the iPay system. This is also referred to as the REQUEST KEY.

Example

<COMPANY_KEY>8990</COMPANY_KEY>

CVV_RESPONSE Response Element Response generated by the cardholder’s issuing bank to validate the card verification value (CVV).

Type Length

AN 1

Values

Value Definition M CVV match.

N CVV no match.

P Not processed.

S Merchant has indicated that CVV is not present on card.

U Issuer is not certified and/or has not provided Visa encryption keys.

Description

This field is the response generated by the cardholder’s issuing bank to validate the card verification value (CVV) sent in with the transaction. This field is conditional based on the request


of 165

of the original transaction and the participation of the issuing bank. This field is only returned for credit card transactions and is only returned when provided by the authorization provider.

Note: American Express currently does not return a CVV_RESPONSE for an authorization. If a transaction does not pass AMEX CID validation, the transaction is declined. See CVV for more information.

Example

CVV_RESPONSE>M</CVV_RESPONSE>

EXCHANGE_RATE Response Element Rate used to perform the currency conversion for MCP and domestic transactions.

Type Length

N 10

Description

This field is the rate that was used to perform the currency conversion for MCP and domestic transactions. The decimal point is NOT implied. This field is returned for successful financial transactions.

Example

<EXCHANGE_RATE>1</EXCHANGE_RATE>

FINANCIAL_TRAN_ID Response Element A unique iPay Gateway-generated identifier for a WALLET or RECUR financial transaction.

Type Length

AN 19

Description

This field is a unique identifier generated by the iPay Gateway for a financial transaction, and is returned when a WALLET or RECUR transaction initiates an immediate financial transaction. The response will contain the FINANCIAL_TRAN_ID to be used as the TRANSACTION_ID for matching transactions.

Note: See the iPay Gateway API Guide for Secure Tokens and the iPay Gateway API Guide for Recurring Payments for more information.

Example

<FINANCIAL_TRAN_ID>0381L2B32UEA0V9UHG8</FINANCIAL_TRAN_ID>


of 165

FRAUD_AUTO Response Element AUTO decision value from the fraud scoring system response.

Type Length

AN 1

Values

Value Definition

A Approve.

R Review.

M Manager Review.

D Decline.

Description

This field is the AUTO decision value from the fraud scoring system response, and is used as the marker for the Soft Decline functionality when the merchant requests in the FRAUD_VALIDATION field.

Note: See the iPay Gateway API Guide for Domestic and Multi Currency Payments for more information on the fraud scoring system.

Example

<FRAUD_AUTO>A</FRAUD_AUTO>

FRAUD_ERROR(S) Response Element Fraud scoring system’s error codes and descriptions.

Type Length N (CODE)

AN (DESCRIPTION)

3

50

Description

This field contains the fraud scoring system’s error codes and descriptions. A fraud score response that results in an error condition is considered fatal, and the fraud score is not generated for the transaction. The FRAUD_ERRORS element contains one to many FRAUD_ERROR elements; each FRAUD_ERROR element contains a CODE and a DESCRIPTION attribute. This field is only returned when provided by the fraud scoring system.



of 165

Example

<FRAUD_ERRORS> <FRAUD_ERROR CODE=”204” DESCRIPTION=”MISSING_SESS Field: [SESS], Value: []”/> <FRAUD_ERROR CODE=”221” DESCRIPTION=”MISSING_EMAL Field: [EMAL], Value: []”/> </FRAUD_ERRORS>

FRAUD_GEOX Response Element Fraud scoring system’s GEOX response value.

Type Length AN 2

Description

This field contains the fraud scoring system’s GEOX response value, which indicates the worst country associated with the consumer in the last 14 days. The GEOX is the location of the person making the online purchase.


Example

<FRAUD_GEOX>CA</FRAUD_GEOX>

FRAUD_KAPT Response Element Fraud scoring system’s KAPT response value.

Type Length

AN 1

Values

Value Definition Y Yes, the fraud score transaction has an associated Kaptcha record.

N No, the fraud score transaction does not have an associated Kaptcha record.

Description

This field contains the fraud scoring system’s KAPT response value, which indicates if the fraud score transaction has an associated Kaptcha record. The KAPT is a browser fingerprint collected by the fraud scoring system when the customer makes a purchase. It includes the type of browser along with browser settings, such as the user' language (e.g. French, English, or Japanese).


of 165


Example

<FRAUD_KAPT>Y</FRAUD_KAPT>

FRAUD_KYCF Response Element Fraud scoring system’s KYCF response value for Know Your Customer Flag.

Type Length AN 1

Values

Value Definition

Y Know Your Customer match.

N No Know Your Customer match.

Description

This field contains the fraud scoring system’s Know Your Customer Flag (KYCF) response value.


Example

<FRAUD_KYCF>Y</FRAUD_KYCF>

FRAUD_REAS Response Element Fraud scoring system’s reason description for the FRAUD_AUTO value.

Type Length AN 4

Description

This field contains the fraud scoring system’s reason description for the FRAUD_AUTO value.


Example

<FRAUD_REAS>SCOR</FRAUD_REAS>


of 165

FRAUD_REGN Response Element Fraud scoring system’s response for US state abbreviation or FIPS 10-4 region code.

Type Length

AN 2

Description

This field is the fraud scoring system’s response for US state abbreviation or Federal Information Processing Standards (FIPS) 10-4 region code.


Example

<FRAUD_REGN>US</FRAUD_REGN>

FRAUD_RULE(S) Response Element Rule codes and descriptions triggered in the fraud scoring system for a given transaction.

Type Length

N (CODE)

AN (DESCRIPTION)

4

50

Description

This field contains the rule codes and descriptions that were triggered in the fraud scoring system for a given transaction. The FRAUD_RULES element contains one to many FRAUD_RULE elements; each FRAUD_RULE element contains a CODE and DESCRIPTION attribute. This field is only returned when provided by the fraud scoring system.


Example

<FRAUD_RULES> <FRAUD_RULE CODE=”7798” DESCRIPTION=”Review Network Type”/> <FRAUD_RULE CODE=”7826” DESCRIPTION=”Device Location Review Countries”/>

</FRAUD_RULES>


of 165

FRAUD_SCOR Response Element Fraud score from the fraud scoring system.

Type Length

N 2

Description

This field is the numeric fraud score from the fraud scoring system (1-99).


Example

<FRAUD_SCOR>99</FRAUD_SCOR>

FRAUD_SESS Response Element Session ID from the associated Kaptcha record in the fraud scoring system.

Type Length AN 32

Description

This field contains the session ID from the associated Kaptcha record in the fraud scoring system.


Example

<FRAUD_SESS>tw2hgr45z2dicz55alcf4iek</FRAUD_SESS>

FRAUD_TRAN Response Element Transaction identifier from the fraud scoring system.

Type Length

AN 32

Description

This field contains the transaction identifier from the fraud scoring system.



of 165

Example

<FRAUD_TRAN>6ZH30R3M0XNJ</FRAUD_TRAN>

FRAUD_VELO Response Element Fraud scoring system’s customer velocity value.

Type Length N 2

Description

This field contains the fraud scoring system’s customer velocity value, which specifies the total number of prior sales by this customer in the last 14 days.


Example

<FRAUD_VELO>0</FRAUD_VELO>

FRAUD_WARNING(S) Response Element Fraud scoring system’s warning codes and descriptions.

Type Length AN (CODE)

AN (DESCRIPTION)

3

50

Type

Alphanumeric

Length

3 characters for CODE attribute 50 characters maximum for DESCRIPTION attribute

Description

This field contains the fraud scoring system’s warning codes and descriptions. Fraud warnings are not considered fatal, and a fraud score is generated for the transaction. The FRAUD_WARNINGS element contains one to many FRAUD_WARNING elements; each FRAUD_WARNING element contains a CODE and a DESCRIPTION attribute. This field is only returned when provided by the fraud scoring system.


of 165


Example

<FRAUD_WARNINGS> <FRAUD_WARNING CODE=”399” DESCRIPTION=” BAD_OPTNField:[B2CC],Value:[USA]”/>

</FRAUD_WARNINGS>

FRC Response Element iPay’s fraud response code, which indicates the success or failure of a fraud score transaction.

Type Length

AN 2

Values

Value Definition

00 The call to the fraud scoring system was successful.

TO The call to the fraud scoring system timed out.

ER The call to the fraud scoring system resulted in an error(s).

Description

This field is the iPay Gateway’s fraud response code to indicate the success or failure of the fraud score transaction. This code can be used to determine which of the various fraud response values to look for in the transaction response. For example, an FRC=TO means that the fraud score call timed-out, so none of the fraud response fields will be returned.


Example

<FRC>ER</FRC>

FXASSURED_MARKUP Response Element Rate differential between the rate that the issuer would charge the cardholder for performing a PYC transaction in the merchant currency and the rate charged by iPay.

Type Length

N 10


of 165

Description

This field is returned for a PYC transaction and is the rate differential between the rate that the issuer would charge the cardholder for performing the transaction in the merchant currency and the rate charged by iPay. The decimal point is NOT implied.

Example

<FXASSURED_MARKUP>-.0030000</FXASSURED_MARKUP>

LOCAL_DATE Response Element Local transaction date of the merchant’s location based on the merchant’s profile.

Type Length

N 8 digits maximum in format MMDDYYYY

Description

This field is the local transaction date of the merchant’s location based on the merchant’s profile. This field is always returned. The format is conditional based on how the data is submitted in the transaction request. If a LOCAL_DATE is supplied in the transaction request, the data are returned unaltered. If this field is not included in the transaction request, iPay generates a value based on the submission date of the transaction and returns it in the format MMDDYYYY.

Example

<LOCAL_DATE>10222015</LOCAL_DATE>

LOCAL_TIME Response Element Local transaction time of the merchant’s location based on the merchant’s profile.

Type Length

N 6 digits in format HHMMSS

Description

This field the local transaction time of the merchant’s location based on the merchant’s profile. This field is always returned. The format is HHMMSS, using a 24-hour clock (“military time”).

If a value for this field is passed in the request (see LOCAL_TIME Request Element), it is returned unaltered in the response. If no value for LOCAL_TIME is included in the request, iPay generates one and returns it in the format shown above.

Example

<LOCAL_TIME>233109</LOCAL_TIME>


of 165

MRC Response Element Message Response Code, which notifies the merchant of the success or failure of data validation at the transaction server level.

Type Length

AN 2

Values

Value Definition 00 (Zero, Zero) Payment server validation approved.

AE AUTH_EXPIRED authorizations are held for 30 days and then released.

AR ACCOUNT_NUMBER BIN is not setup to process.

AX Transaction amount value requirements exceeded; see response text for details.

CD Commercial data already associated.

CF Credit refused, must have a relevant sale in order to process credit.

DC Data conflict.

DF Data-Frequency mismatch. The combination of fields has violated the iPay Gateway frequency logic.

DR Delete refused—data integrity enforcement.

IB Invalid base64 encoding.

IC Missing/invalid COMPANY_KEY.

ID Missing/invalid transaction data.

IE Invalid encryption.

IK Invalid key (See RESPONSE_TEXT for the invalid key).

IS Inactive service.

IT Invalid XML transmission format.

IX Invalid XML transaction format.

IY Invalid type attribute.

IZ Invalid compression (future use).

LM Field LAST_FOUR did not match last four digits of cardholder’s account number contained in TRACK_DATA.

MK Missing key (See RESPONSE_TEXT for the missing key).

MY Missing type attribute.

NF Transaction not found.


of 165

Value Definition NM No data mapping; please call Planet Payment.

NS Transaction not settled.

NX No XML ‘FIELDS’ node present.

SE System error; please call Planet Payment.

SU System unavailable, retry.

TC Transaction already captured.

TD Transaction already deleted.

TR Transaction already reversed.

TS Transaction already settled.

TV Transaction already voided.

UP Unable to process at this time, retry.

VR VOID_REFUSED Merchants receiving a decline for a sale transaction will not be able to void it.

XE Currency conversion error; please call Planet Payment.

Description

This field is the Message Response Code (MRC), which notifies the merchant of the success or failure of data validation at the transaction server level. This field is always returned.

Note: iPay does not report on transactions that are rejected during data validation. It is the merchant's responsibility to log these transactions for troubleshooting purposes.

Example

<MRC>00</MRC>


of 165

P3DS_ACS_URL Response Element URL of the 3-D Secure access control server that the merchant will redirect their consumer to for 3-D Secure authentication.

Type Length

AN 2083

Description

This field is the fully qualified URL of the 3-D Secure access control server that the merchant will redirect their consumer to for 3-D Secure authentication.


Example

<P3DS_ACS_URL>…</P3DS_ACS_URL>

P3DS_ARS Response Element One-digit code describing the 3-D Secure authentication response status.

Type Length AN 1

Description

This field is a one-digit code describing the 3-D Secure authentication response status. This value is returned by the access control server URL after the consumer completes 3-D Secure authentication.


Example

<P3DS_ARS>…</P3DS_ARS>

P3DS_CARD_ENROLLED Response Element Code describing whether the consumer’s card is enrolled in 3-D Secure.

Type Length

AN 1


of 165

Values

Value Definition

E The card is enrolled.

U The card is NOT enrolled.

Description

This field is a one-digit code describing whether the consumer’s card is enrolled in 3-D Secure. This value is returned by the iPay Gateway after the first Authorization request.


Example

<P3DS_CARD_ENROLLED>…</P3DS_CARD_ENROLLED>

P3DS_PA_RESPONSE Response Element Data received by the merchant’s web page from the ACSUrl in response to a 3-D Secure authentication.

Type Length

AN 1000

Description

This field is data received by the merchant’s web page from the ACSUrl in response to a 3-D Secure authentication. This field should be returned in the second Authorization call to the iPay Gateway after 3-D Secure authentication has been performed by the consumer.


Example

<P3DS_PA_RESPONSE>…</P3DS_PA_RESPONSE>



0000

1010 √ √ √

1020


of 165

P3DS_SRS Response Element Transaction ID received from a 3-D Secure transaction supplied from the 3-D Secure provider.

Type Length

AN 1

Description

This field is a one-character code describing the signature response status.


Example

<P3DS_SRS>…</P3DS_SRS>

P3DS_TRANSACTION_ID Response Element Transaction ID received from a 3-D Secure transaction supplied from the 3-D Secure provider.

Type Length N 20

Description

This field is the transaction ID received from a 3-D Secure transaction supplied from the 3-D Secure provider.


See also P3DS_TRANSACTION_ID Request Element.

Example

<P3DS_TRANSACTION_ID>…</P3DS_TRANSACTION_ID>

PRODUCT_ID Response Element A unique iPay Gateway-generated identifier for a newly created (i.e., inserted) PRODUCT.

Type Length AN 19


of 165

Description

This field is a unique identifier generated and returned by the iPay Gateway for a newly created (i.e., inserted) PRODUCT. This identifier is used for the life of the PRODUCT and must be supplied for a MODIFY or DELETE of the PRODUCT or an INSERT of a TEMPLATE. A billing template must be linked to an active product by providing this value.

See also PRODUCT_ID Request Element.

Example

<PRODUCT_ID>0999B10ZZZ3YYDPWQ5R</PRODUCT_ID>

PYC_EXCHANGE_RATE Response Element Rate used to perform the PYC currency conversion.

Type Length N 10

Description

This field is the rate that was used to perform the currency conversion for PYC only. The decimal point is NOT implied.

Example

<PYC_EXCHANGE_RATE>1.021428</PYC_EXCHANGE_RATE>

PYC_RATE_MARKUP Response Element PYC markup rate expressed as a percentage.

Type Length N 10

Description

This field is the PYC markup rate expressed as a percentage. For example, a value of "1234" would be "12.34%". The markup rate should be printed on the cardholders receipt for PYC financial transactions. The decimal point is NOT implied.

Example

<PYC_RATE_MARKUP>-00.30</PYC_RATE_MARKUP>


of 165

RATE(S) Response Element Report response data from CURRENCY RATE QUERY transaction.

Description

This field contains the report response data from CURRENCY RATE QUERY transaction. The RATES element contains 1 to many RATE elements; each RATE element contains a CURRENCY_CODE and EXCHANGE_RATE element. This element is returned for CURRENCY RATE QUERY transactions with a QUERY_TYPE value of 1. This field is only returned when provided by the authorization provider.

Note: The format of this element does not vary based on the value passed in the FMT attribute of REQUEST. See the iPay Gateway API Guide for Domestic and Multi Currency Payments for more information on currency rate queries.

MCP Example

<RATES>

<RATE>

<CURRENCY_CODE alpha=”CAD”>124</CURRENCY_CODE>

<EXCHANGE_RATE>0.92102427</EXCHANGE_RATE>

</RATE>

<RATE>

<CURRENCY_CODE alpha=”HKG”>392</CURRENCY_CODE>


</RATE>

<RATE>

<CURRENCY_CODE alpha=”GBP”>826</CURRENCY_CODE>


</RATE>

<RATE>

<CURRENCY_CODE alpha=”EUR”>978</CURRENCY_CODE>


</RATE>

</RATES>

PYC Example

<RATES>

<RATE>

<CURRENCY_CODE alpha=”CAD”>124</CURRENCY_CODE>


of 165

<CARD_TYPE>Visa</CARD_TYPE>


</RATE>

<RATE>

<CURRENCY_CODE alpha=”HKD”>392</CURRENCY_CODE>

<CARD_TYPE>Visa</CARD_TYPE>


</RATE>

</RATES>

RESPONSE_TEXT Response Element Comprehensible text message concerning the transaction.

Type Length AN 19

Description

This field provides a comprehensible text message concerning the transaction. This field is always returned. Logic must not be built around this field as it can change without notice.

Example

<RESPONSE_TEXT>EXACT MATCH</RESPONSE_TEXT>


of 165

SCHEDULE_ID Response Element A unique iPay Gateway-generated identifier for a newly created SCHEDULE.

Type Length

AN 19

Description

This field a unique identifier generated and returned by the iPay Gateway for a newly created SCHEDULE. This identifier is used for the life of the SCHEDULE and must be supplied for a MODIFY or DELETE of the SCHEDULE. This field is only returned on a successful insert of a RECUR SCHEDULE.


See also SCHEDULE_ID Request Element.

Example

<SCHEDULE_ID>0681B10WTW3YYDPWQ5R</SCHEDULE_ID>

SEQUENCE_NUMBER Response Element A merchant-generated unique identifier.

Type Length N 6

Description

This field is a merchant-generated unique identifier. This number is echoed back to the merchant to assist in matching transaction requests to the response messages. This value is not stored and is only returned when provided in the original transaction.

See also SEQUENCE_NUMBER Request Element.

Example

<SEQUENCE_NUMBER>1</SEQUENCE_NUMBER>


of 165

TERMINAL_ID Response Element An iPay-assigned identification of the terminal requesting transaction.

Type Length

AN 15

Description

This field is an iPay-assigned identification of the terminal requesting transaction. For security reasons, if this field is not included in the original transaction request, it is not returned in the response.

See also TERMINAL_ID Request Element.

Example

<TERMINAL_ID>6177</TERMINAL_ID>

TRANSACTION_ID Response Element A unique iPay Gateway-generated identifier for each transaction.

Type Length AN 19

Description

This field a unique identifier generated by the iPay Gateway for each transaction. This field is always returned. This identifier is used in matching transactions (e.g., CAPTURE to an AUTH or REFUND to a SALE).

See also TRANSACTION_ID Request Element.

Example

<TRANSACTION_ID>0381L2B32UEA0V9UHG8</TRANSACTION_ID>


of 165

TRANSACTION_RESPONSECODE Response Element Response code of the transaction being queried for a UPOP Inquiry Request transaction.

Type Length N 2

Description

This field is the response code of the transaction being queried for a UPOP Inquiry Request transaction.


Example

<TRANSACTION_RESPONSECODE>00</TRANSACTION_RESPONSECODE>

TRANSACTION_RESPONSEMESSAGE Response Element Response message of the transaction being queried for a UPOP Inquiry Request transaction.

Type Length AN 25

Description

This field is the response message of the transaction being queried for a UPOP inquiry request transaction.


Example

<TRANSACTION_RESPONSEMESSAGE>00</TRANSACTION_RESPONSEMESSAGE>


of 165

TRANSACTION_RESULTTYPE Response Element Transaction type of the original queried transaction.

Type Length

AN 20

Description

This field is the transaction type of the original queried transaction (Auth, Sale, Void, or Refund).

Example

<TRANSACTION_RESULTTYPE>Refund</TRANSACTION_RESULTTYPE>

UP_ACTIONURL Response Element Uniform Resource Locator (URL) for the merchant to redirect the consumer to UPOP’s web site.

Type Length

AN 256

Description

This field contains the URL that the merchant will use to redirect the consumer to UPOP’s web site.


Example

<UP_ACTIONURL>…</UP_ACTIONURL>

UP_ORDERNUMBER Response Element A unique iPay Gateway-generated identifier returned on the initial UPOP Auth or Sale request.

Type Length

AN 32

Description

This field a unique identifier generated by the iPay Gateway for a UPOP transaction, and is returned on the initial UPOP Auth or Sale request. This value will need to be returned to the Gateway in the secondary UPOP Auth or Sale request for matching.


of 165


Example

<UP_ORDERNUMBER>UC098I3WPFGHOB23F70</UP_ORDERNUMBER>

UP_PAYLOAD Response Element Full HTML needed to perform the customer redirect to the UPOP web site.

Type Length AN 3000

Description

This field is the full HTML needed to perform the customer redirect to the UPOP web site, where the consumer will complete their payment before being redirected back to the merchant’s web site.


Example

<UP_PAYLOAD>…</UP_PAYLOAD>

UP_SETTLEDATE Response Element Date in Beijing China time zone that the money will settle for this transaction.

Type Length N 4 digits maximum in format MMDD

Description

This field is the date in Beijing China time zone that the money will move (settle) for this transaction. If a UP Secure (UPOP) DEBIT transaction needs to be cancelled, use the UP_SETTLEDATE to determine if a Void or Refund is needed. Issue a Void prior to this date and a Refund after.


Example

<UP_SETTLEDATE>0507</UP_SETTLEDATE>


of 165

XID Response Element Optional unique value used only with 3-D Secure for Verified by Visa transactions.

Type Length

AN 20 characters (28 character base64 encoded)

Description

This field contains a unique value for Verified by Visa transactions. This field is used only with 3-D Secure transactions.


Example <XID>clhaaHB3U0hveURrdFFsE5dPa00=</XID>


of 165

CHAPTER 4

Selected ISO Currency and Country Codes The table below shows the ISO 3166 and ISO 4217 standard codes for selected countries and currencies, respectively. The three-character code in the Country Code column should be used for the COUNTRY field. The three-digit number in the Currency Code column should be the value supplied for the CURRENCY_CODE field.

Note: Not all currencies are currently supported. Country Country

Code Currency Code

Algerian Dinar DZD 012

Argentine Peso ARS 032

Australian Dollar AUD 036

Bahamian Dollar BSD 044

Bahraini Dinar BHD 048

Thai Baht THB 764

Balboa PAB 590

Barbados Dollar BBD 052

Belize Dollar BZD 084

Bermudian Dollar BMD 060

Bolivar Fuerte VEF 937

Boliviano BOB 068

Brazilian Real BRL 986

Brunei Dollar BND 096

Canadian Dollar CAD 124

Cayman Islands Dollar KYD 136

Cedi GHS 936

CFA Franc BEAC XAF 950

Chilean Peso CLP 152

Colombian Peso COP 170

Costa Rican Colon CRC 188


of 165

Country Country Code

Currency Code

Czech Koruna CZK 203

Danish Krone DKK 208

Dominican Peso DOP 214

East Caribbean Dollar XCD 951

Egyptian Pound EGP 818

Euro EUR 978

Forint HUF 348

Guarani PYG 600

Hong Kong Dollar HKD 344

Hryvnia UAH 980

Iceland Krona ISK 352

Indian Rupee INR 356

Jamaican Dollar JMD 388

Jordanian Dinar JOD 400

Kuwaiti Dinar KWD 414

Kwanza AOA 973

Latvian Lats LVL 428

Lebanese Pound LBP 422

Loti LSL 426

Malaysian Ringgit MYR 458

Mauritius Rupee MUR 480

Mexican Peso MXN 484

Naira NGN 566

Namibia Dollar NAD 516

New Azerbaijanian Manat AZN 944

New Israeli Sheqel ILS 376

New Taiwan Dollar TWD 901

New Turkish Lira TRY 949

New Zealand Dollar NZD 554

Norwegian Krone NOK 578

Nuevo Sol PEN 604


of 165

Country Country Code

Currency Code

Pakistan Rupee PKR 586

Pataca MOP 446

Peso Uruguayo UYU 858

Philippine Peso PHP 608

Pound Sterling GBP 826

Pula BWP 072

Qatari Rial QAR 634

Quetzal GTQ 320

Rand ZAR 710

Rial Omani OMR 51

Rufiyaa MVR 462

Rupiah IDR 360

Russian Ruble RUB 643

Saudi Riyal SAR 682

Singapore Dollar SGD 702

Sri Lanka Rupee LKR 144

Swedish Krona SEK 752

Swiss Franc CHF 756

Syrian Pound SYP 760

Taka BDT 050

Tanzanian Shilling TZS 834

Tenge KZT 398

Trinidad and Tobago Dollar TTD 780

UAE Dirham AED 784

US Dollar USD 840

Won KRW 410

Japanese Yen JPY 392

Yuan Renminbi CNY 156

Zloty PL 98


of 165

CHAPTER 5

Frequently Asked Questions • What do I do when a "refer to issuer" response is returned?

• What happens if someone resubmits a transaction?

• What do I do if my transaction or file upload times out?

• What is TDES?

• How long does a credit card authorization hold funds on an account?

• How do I remove an authorization?

• If I get an approval code back, is my transaction approved for funds available?

• If I get an approval for funds available and a decline on AVS, will my transaction still go through?

What do I do when a "refer to issuer" response is returned?

You must call the toll-free number that appears on the screen to obtain a voice authorization. Security at the issuing bank does not want to give an electronic authorization. These are not usually declines. These transactions must be sent to the iPay Gateway as a CC DEBIT CAPTURE using the approval number that was given at the time of the call.

What happens if someone resubmits a transaction?

Presuming it is resubmitted without changing any information, and you did not receive a response on the first transaction, then the first transaction has been dropped from the iPay Gateway. The card for the original transaction could be authorized and the open-to-buy limit affected, but will not be settled.

What do I do if my transaction or file upload times out?

Re-submit the transaction or upload.

What is TDES?

TDES stands for Triple Data Encryption Standard and provides 168-bit security. This type of encryption is commonly used through the payment industry.

How long does a credit card authorization hold funds on an account?

It depends on the issuing bank, but the standard is 7–10 calendar days, with a maximum of 30 days. The iPay Gateway supports up to 30 days.


of 165

How do I remove an authorization?

If the processor and/or issuer for that card supports this, you can perform a DEBIT REVERSAL transaction. If they don’t support DEBIT REVERSALS, you must contact the issuing bank with the authorization number and ask for it to be removed or wait for the authorization to expire.

If I get an approval code back, is my transaction approved for funds available?

Only if the MRC and ARC responses are equal to 00. Some issuers give approval codes even when the card is declined.

If I get an approval for funds available and a decline on AVS, will my transaction still go through?

Yes, if you approve it. It is the merchant’s decision to proceed with the transaction.


of 165

Gateway Specification Version 7.3 | Update 1/16/19 · iPay Gateway API Guide for XML Gateway...

Documents

Transcript of Gateway Specification Version 7.3 | Update 1/16/19 · iPay Gateway API Guide for XML Gateway...