MasterCard In tern et Gatew ay Service (MIGS)

Transcription

1 Master Card Inter national MasterCard In tern et Gatew ay Service (MIGS) MIGS Payment Client Reference Manual Prepared By: Patrick Hayes Department: Principal Consultant, ebusiness Solutions Date Written: 2 July 2003 Software Versions: MIGS Payment Server 2.1, MIGS Payment Client 3.0 Document Revision #: 2.3

2 MasterCard Internet Gateway Service Before reading or using this Manual, please read our disclaimer. By accepting or reading this Manual you agree to be bound by the terms of the disclaimer. Disclaimer We may make improvements and/or changes to the products and services described in this Manual at any time. To the fullest extent permitted by any applicable law: We give no warranties of any kind whatsoever in relation to this Manual including without limitation in respect of quality, correctness, reliability, currency, accuracy or freedom from error of this Manual or the products it describes. All terms, conditions, warranties, undertakings, inducements or representations whether expressed, implied, statutory or otherwise relating in any way to this Manual are expressly excluded. Without limiting the generality of the previous sentence neither us nor our affiliates, employees, directors, officers or third party agents will be liable to you for any direct or indirect loss or damage (including without limitation consequential punitive or special loss or damage) however arising in respect of this Manual or any failure or omission by us, even if we are advised of the likelihood of such damages occurring. If we have to accept any liability our total aggregate liability to you, including any liability of our affiliates, employees, directors, officers and third party agents collectively, and regardless of whether such liability is based on breach of contract, tort, strict liability, breach of warranties, failure of essential purpose or otherwise, is limited to US While we have no reason to believe that the information contained in this Manual is inaccurate, we accept no responsibility for the accuracy, currency or completeness of the information in this Manual. We do not warrant or represent that we have checked any part of this Manual that is a copy of information we have received from a third party. We are merely passing that information on to you. License Agreement The software described in this Manual is supplied under a licence agreement and may only be used in accordance with the terms of that agreement. Copyright MasterCard owns the intellectual property in this Manual exclusively. You acknowledge that you must not perform any act which infringes the copyright or any other intellectual property rights of MasterCard and cannot make any copies of this Manual unless in accordance with these terms and conditions. Without our express written consent you must not: distribute any information contained in this Manual to the public media or quote or use such information in the public media; or allow access to the information in this Manual to any company, firm, partnership, association, individual, group of individuals or other legal entity other than your officers, directors and employees who require the information for purposes directly related to your business. Page ii

3 Contents 1. Preface What Is the Purpose Of This Guide Who Should Read This Guide Related Documents How This Guide is Structured Basic Transactions Input Requirements Merchant-Hosted Transaction MOTO or Internet Server-Hosted Transactions Basic Output Transaction Results Merchant & Server-Hosted Advanced Features Airline Ticket Number Digital Order Input Requirements Digital Receipt Output Details External Payment Selection (EPS) Digital Order Input Requirements Digital Receipt Output Details Payment Authentications Introduction Server-Hosted Authentication and Payment DO Input Requirements for a Server-Hosted Authentication and Payment DO Output Requirements for a Server-Hosted Authentication and Payment Merchant-Hosted Authentication and Payment DO Input Requirements for a Merchant-Hosted Authentication and Payment DO Output Requirements for a Merchant-Hosted Authentication and Payment Advanced Merchant Administration (AMA) Transactions Digital Receipt doadmincapture Digital Order Input Requirements Digital Receipt Output Details doadminrefund Digital Order Input Requirements Digital Receipt Output Details doadminvoidpurchase Digital Order Input Requirements Digital Receipt Output Details doadminvoidcapture Digital Order Input Requirements Digital Receipt Output Details doquerydr Page iii

4 5.6.1 Digital Order Input Requirements Digital Receipt Output Details Ancillary Commands echo nextresult pcerror getversion Appendix A - Result Details...33 A.1 Standard Digital Receipt Appendix B Appendix B Valid Field Values...35 B.1 QSI Response Code B.2 Card Security Code Response Code B.3 Transaction Code B.4 Transaction Source B.5 DigitalReceipt.ERROR and PaymentClient.Error fields Appendix C Sockets Command Reference...48 Page iv

5 List of Tables Table 1 Inputs to adddigitalorderfield Command (MOTO)... 2 Table 2 Inputs to sendmotodigitalorder Command... 3 Table 3 Inputs to adddigitalorderfield Command... 4 Table 4 Inputs to getdigitalorder Command... 5 Table 5 Fields extractable from GetDigitialResultField... 8 Table 6 Ticket Number Inputs for a 2/Server-Hosted transaction... 9 Table 7 EPS Inputs for a Server-Hosted transaction Table 8 DO fields for a Server-Hosted Authentication and Payment transaction Table 9 DO Input Fields for a Merchant-Hosted Authentication and Payment transaction Table 10 DO fields for a Merchant-Hosted Authentication and Payment transaction Table 11 Additional doadmincommandfield Input Data Fields Table 12 doadmincapture Input Data Fields Table 13 doadmincapture Output Data Fields Table 14 Additional doadminrefund Input Data Fields Table 15 doadminrefund Input Data Fields Table 16 doadminrefund Output Data Fields Table 17 Additional doadminvoidpurchase Input Data Fields Table 18 doadminvoidpurchase Input Data Fields Table 19 doadminvoidpurchase Output Data Fields Table 20 Additional doadminvoidcapture Input Data Fields Table 21 doadminvoidcapture Input Data Fields Table 22 doadminvoidcapture Output Data Fields Table 23 doquerydr Input Data Fields Table 24 doquerydr Output Data Fields Table 25 echo() Command Input Data Fields Table 26 nextresult Output Field Table 27 pcerror Output Field Table 28 getversion() Output Data Fields Page v

6 1.1 What Is the Purpose Of This Guide This document is a master reference for all inputs and outputs to and from the MIGS Payment Client in conjunction with MIGS Payment Server. 1.2 Who Should Read This Guide This guide is specifically aimed at Integrators who want to integrate the Payment Client into merchant applications. 1.3 Related Documents This Payment Client Reference Guide is designed to be used with the Payment Client Integration Guide which outlines the various types of transactions of the Payment Client s API methods. To understand the business logic surrounding transaction processing in MIGS, it is also recommended that you read this guide. 1.4 How This Guide is Structured This guide consists of the following sections: Preface Basic Transactions Payment and Authentication Transactions Advanced Feature Transactions An introduction to this guide. Details the requirements to perform a Merchant-Hosted (Mail Order Telephone Order (MOTO) or internet) transaction, and a Server-Hosted transaction. Details the requirements to perform a Merchant-Hosted and a Server-Hosted authentication and payment transaction using Verified by Visa and MasterCard SecureCode. Details the requirements to perform advanced features. AMA Transactions Appendix A Appendix B Details how to execute Advanced Merchant Administration features. Details the valid result field values used by the Payment Server. Details the valid field values and response codes used by Payment Server 2.1. Page 1

7 2.1 Input Requirements Merchant-Hosted Transaction MOTO or Internet MIGS requires a number of inputs to perform a Mail Order Telephone Order (MOTO) transaction. These values are passed from the merchant software into the MIGS Payment Client using two commands: adddigitalorderfield - adds supplementary data such as MerchTxnRef number and address verification data. sendmotodigitalorder - which generates and sends the Digital Order. adddigitalorderfield( FieldName, FieldValue) Input Value Input The Merchant Transaction Reference identifier the merchant assigns to the transaction. MerchTxnRef It can be used later to search for any lost receipts using the QueryDR command. 40 chars This identifier can use text made up of any of the base US ASCII characters in the range, decimal 20 to 126 excluding decimal 124, the character. CardNumber The Electronic Commerce Modelling Language (ECML) Standard card number, entered in the merchant s shop and buy application used for the transaction. 40 chars CardExpiry The expiry date of the card in the format YYMM. 4 chars Table 1 Inputs to adddigitalorderfield Command (MOTO) Page 2

8 sendmotodigitalorder(orderinfo, merchantid, amount, locale,) Input Value Input This is used to input any merchant/customer information for this transaction that is required to be stored. orderinfo A value must be passed as null values are not accepted 34 chars It uses text made up of any of the base US ASCII characters in the range, decimal 20 to 126 excluding decimal 124, the character. The merchant ID is an alphanumeric identifier that is given to the merchant during the merchant registration process and used to identify the merchant on the MIGS Payment Server. merchantid There is a unique Merchant ID for each merchant account/profile on the Payment Server. There may be more than one merchantid assigned for each physical merchant. 16 chars This identifier is not the same as the merchant number assigned to you by the Bank. amount The purchase amount of the transaction expressed as the lowest currency denominator. It does not contain any decimal points, thousands separators or currency symbols, for example, $12.50 is expressed as Positive Integer 10 chars locale Used in SSL type transactions for specifying the language that is used on the Payment Server pages that are displayed to the customer. Although the value is not used in this type of transaction, it must have a value. Set it to a value of en. 5 chars returnurl This is not used in a sendmotodigitalorder and can be left blank 0 chars Table 2 Inputs to sendmotodigitalorder Command Page 3

9 2.1.2 Server-Hosted Transactions The MIGS Payment Cartridge requires a number of inputs to perform a Server-Hosted type transaction. These values are passed from the merchant software into the MIGS Payment Client by two different commands: adddigitalorderfield - to add supplementary data such as MerchTxnRef number and address verification data. GetDigitalOrder - which generates the Digital Order. Another command, decryptdigitalreceipt is used to decrypt the encrypted Digital Receipt that is returned from the Payment Server via the customer s browser. adddigitalorderfield( FieldName, FieldValue) Input Value Input The Merchant Transaction Reference is an identifier the merchant assigns to the transaction. MerchTxnRef It can be used later to search for any lost receipts using the QueryDR command. 40 chars This identifier can use text made up of any of the base US ASCII characters in the range, decimal 20 to 126 excluding decimal 124, the character. Table 3 Inputs to adddigitalorderfield Command getdigitalorder(orderinfo, merchantid, amount, locale, returnurl) Input Value Input This is used to input any merchant/customer information for this transaction that can be stored. orderinfo A value must be passed as null values are not accepted. 34 chars It uses text made up of any of the base US ASCII characters in the range, decimal 20 to 126 excluding decimal 124, the character. merchantid The merchant ID is an alphanumeric identifier that is given to the merchant during the banks registration process, which is used to identify the merchant on the Payment Server. There is a unique MerchantId for each merchant account/profile on the Payment Server. There may be more than one merchantid assigned for each physical merchant. 16 chars Page 4

10 Input Value Input amount The purchase amount of the transaction expressed as the lowest currency denominator. It does not contain any decimal points, thousands separators or currency symbols, for example, $12.50 is expressed as Positive Integer 10 chars locale Used in SSL type transactions for specifying the language that is used on the Payment Server pages that are displayed to the customer. If the locale is not supplied the Payment Client or Payment Server defined default of en is used. 5 chars returnurl The URL that is displayed to the customer s browser when the Payment Server sends the Digital Receipt. If the return URL is not supplied, the default Merchant Client ReturnURL value in the Payment Server is used. 255 chars Table 4 Inputs to getdigitalorder Command Page 5

11 2.2 Basic Output Transaction Results Merchant & Server-Hosted Once a decryptdigitalreceipt command in a Server-Hosted transaction, or in a Merchant-Hosted/MOTO transaction a sendmotodigitalorder command has been successfully completed, the Payment Client is ready to be interrogated for the receipt details. These values are then passed from the Payment Client back into the merchant software. The outputs are obtained by using the supplementary command: getresultfield ( DigitalReceipt.FieldName ) MerchTxnRef Input Value Input The Merchant Transaction Reference is an identifier the merchant assigns to the transaction. It can be later used to search for any lost receipts using the QueryDR command. (Returned input value) 40 chars OrderInfo This is used to input any merchant/customer information for this transaction that is required to be stored. It must contain an empty string and cannot be a null value. (Returned input value) 34 chars MerchantId The merchant ID is an alphanumeric identifier that is given to the merchant during the banks registration process, which is used to identify the merchant on the Payment Server. There is a unique Merchant Id for each merchant account/profile on the Payment Server. There may be more than one merchantid assigned for each physical merchant. (Returned input value) 16 chars PurchaseAmountInteger The purchase amount of the transaction expressed as the lowest currency denominator. It does not contain any decimal points, thousands separators or currency symbols, for example, $12.50 is expressed as (Returned input value) 10 chars Locale Used in SSL type transactions for specifying the language that is used on the Payment Server pages that are displayed to the customer. Not used for MOTO transactions (Returned input value) 5 chars Page 6

12 ReceiptNo Input Value Input QSIResponseCode AcqResponseCode TransactionNo This is also known as the Reference Retrieval Number (RRN), which is a unique identifier generated by the MIGS server, used to retrieve the original transaction data. This value is passed back to the customer for their records if the merchant application does not generate its own receipt number. A response code that is generated by the Payment Server to indicate the status of the transaction. A QSIResponseCode of 0 (zero) indicates that the transaction was processed successfully and approved by the acquiring institution. Any other value indicates a transaction failure. A value of 7 indicates the Payment Server encountered an error and the merchant program should check for the error condition using the command DigitalReceipt.ERROR Although this was originally a response from the Acquirer of the transaction, in the MIGS system this is the response which comes directly from the issuer. The Response Code is generated by the issuing financial institution to indicate the status of the transaction. It is advisable to use the QSIResponseCode, and is only provided for reference. Payment Server Transaction Number is a unique number generated by the MIGS Payment Server. It is important to make sure the TransactionNo is stored for later retrieval if required to perform queries or Advanced Merchant Administration commands. For example it is required refund and capture transactions. 12 chars 1 char 3 chars 21 chars Page 7

13 AuthorizeId BatchNo Card Input Value Input Authorisation Identification Code is supplied by the issuing financial institution for an approved transaction. It should be recorded for reference only. Transaction Batch Number is the Batch number on the MIGS Payment Server that this transaction is to belong. This is generally the processing date of the transaction (e.g ). The Card is a code that details what type of card was used to carry out this transaction. They are detailed in Error! Reference source not found. on page Error! Bookmark not defined. of the guide. 12 chars 6 chars 2 chars Table 5 Fields extractable from GetDigitialResultField Page 8

14 3.1 Airline Ticket Number Ticket Number functionality allows the merchant to enter a ticket number in the digital order to be stored for that transaction. Although the ticket number was originally designed for the travel industry, it can be any alpha data about the transaction up to the maximum length of the field Digital Order Input Requirements For both 2 and Server-Hosted transactions, the Ticket data is sent using the adddigitalorderfield( FieldName, FieldValue) supplementary command. FieldName TicketNo Field Value The airline ticket number issued by an airline to a customer Input 15 chars Table 6 Ticket Number Inputs for a 2/Server-Hosted transaction Digital Receipt Output Details There are no special output details for the addition of a Ticket Number command in the Digital Receipt, as it is not returned in the Digital Receipt details. Page 9

15 3.2 External Payment Selection (EPS) EPS is used in a Server-Hosted transaction for bypassing the Payment Server page that displays the logos of all the cards the payment processor will accept. The EPS data is sent using the supplementary command adddigitalorderfield( FieldName, FieldValue) Digital Order Input Requirements FieldName Input gateway Used in External Payment Selection to determine what type of transaction is used. The field is case sensitive, and must comply with the gateways that are valid in the Payment Server. Valid values are shown in Appendix B. 6 chars card Used in External Payment Selection to determine what type of card is used. The field is case sensitive, and must comply with each of the card types valid in the Payment Server. This varies from Payment Server to Payment Server. The possible values are shown in Appendix B. To check the card types available, open the Server- Hosted card selection page in a browser and run the cursor over each card logo, In the bottom of the browser window the gateway and card values is displayed 15 chars Table 7 EPS Inputs for a Server-Hosted transaction Digital Receipt Output Details There are no special output details for the EPS command in the Digital Receipt, as gateway and card are not returned in the Digital Receipt details. Page 10

16 4.1 Introduction Verified by Visa (Visa 3-Domain Secure) and MasterCard SecureCode (MasterCard 3- Domain Secure) are Payment Authentications designed to stop credit card fraud by authenticating cardholders when performing transactions over the Internet. A 3-D Secure transaction is performed immediately before a merchant performs an payment transaction. Authenticating ensures that the card is being used by its legitimate owner. During a transaction, it allows the merchant to confirm that the customer is the cardholder by redirecting them to their card issuer where they enter a password that they had previously registered with their card issuer. 4.2 Server-Hosted Authentication and Payment DO Input Requirements for a Server-Hosted Authentication and Payment There are no additional inputs to a standard Server-Hosted payment request for authentication. If the merchant is enrolled for MasterCard SecureCode and/or Verified by Visa, appropriate authentication with be performed automatically by MIGS DO Output Requirements for a Server-Hosted Authentication and Payment For Authentication and Payment transactions, extra fields are returned in the Digital Receipt. The fields are not used by the merchant but are returned to allow the merchant to store them as a record of authentication for the transaction, which can be used in the event of a dispute. They cannot be used again for any future transactions. All Fieldnames are case sensitive and the outputs are obtained by using the supplementary command getresultfield ( DigitalReceipt.FieldName ). The Digital Receipt Output fields for a Server-Hosted Authentication and Payment transaction are listed on the next page. Page 11

17 Fieldname Ver Always 3DS. Y =The cardholder was successfully authenticated. E = N The cardholder is not enrolled. = The cardholder was not verified. U = The cardholder s Issuer was unable to authenticate due to a system error at the Issuer. F = An error exists in the format of the request from the MIGS. VerStatus A = Authentication of your Merchant ID and Password to the ACS Directory Failed. D Server. = Error communicating with the Directory The VerSecurityLevel and the VerToken is the only required data you need to provide to defend chargeback VerSecurityLevel VerToken 3DSXID 3DSECI 3DSenrolled 3DSstatus C = The card type is not supported for authentication. S = The response received from the Issuer was not consider authentic. P I = Invalid format message from Issuer. = Internal MIGS system error. This field contains the security level to be used in the payment message. Visa 05 - Visa 06 - Visa 07 - MasterCard 0 - MasterCard 1 - MasterCard 2 - Fully authenticated Not authenticated, (cardholder not participating), Not authenticated Merchant not participating (A merchant should never see this if they are configured for SecureCode) Cardholder not participating Cardholder authenticated The Accountholder Authentication Value (AVV MasterCard) or Cardholder Authentication Verification Value (CAVV - Visa) generated by the issuer s Access Control Server as a token to prove that the cardholder authenticated OK. It is a unique transaction identifier that is generated by the merchant to identify the transaction. The 3D Secure Electronic Commerce Indicator. This field is only included if the card is within an enrolled range. This is the value of the VERes.enrolled field. It will take values (Y - Yes, N - No, U Unavailable for Checking). This field is only included if 3-D Secure authentication was used and a PARes was received by the MPI. It will take values (Y Yes, N No, A Attempted Authentication, U Unavailable for Checking). Table 8 DO fields for a Server-Hosted Authentication and Payment transaction Page 12

18 4.3 Merchant-Hosted Authentication and Payment DO Input Requirements for a Merchant-Hosted Authentication and Payment All FieldNames are case sensitive and the data is sent using the supplementary command adddigitalorderfield( FieldName, FieldValue). The Digital Order input fields for a Merchant-Hosted Authentication and Payment transaction are: FieldName Input Maximu m gateway The value for a 3-D Secure Authentication and Payment transaction must be set to ssl. 32 chars card For Authentication and Payment transactions - the value will be the values available for the merchant. 15 chars CardNum The number of the card used for the transaction. It is the Electronic Commerce Modelling Language (ECML) standard card number, entered in the merchant s shop and buy application. Strin g 40 chars It must not contain white space or formatting characters. CardExp The expiry date of the card in the format YYMM. The value must be expressed as a 4-digit number (integer) with no white space or formatting characters, for example, an expiry date of May 2009 is Strin g 4 chars An optional field that the merchant may supply in the Digital Order as a description of the transaction. Desc Note: This is only used for Verified by Visa transactions and cannot be used for MasterCard Secure Code. The field can only be used if the merchant collects the card details. If the Payment Server is used to collect the card details, the merchant cannot use the field. 125 chars Table 9 DO Input Fields for a Merchant-Hosted Authentication and Payment transaction Page 13

19 4.3.2 DO Output Requirements for a Merchant-Hosted Authentication and Payment For Authentication and Payment transactions, extra fields are returned in the Digital Receipt. The fields are not used by the merchant but are returned to allow the merchant to store them as a record of authentication for the transaction, which can be used in the event of a dispute. They cannot be used again for any future transactions. All Fieldnames are case sensitive and the outputs are obtained by using the supplementary command getresultfield ( DigitalReceipt.FieldName ). The Digital Receipt Output fields for a Merchant-Hosted Authentication and Payment transaction are: Page 14

20 Fieldname Ver Always 3DS. Y E = N =The cardholder was successfully authenticated. The cardholder is not enrolled. = The cardholder was not verified. U = The cardholder s Issuer was unable to authenticate due to a system error at the Issuer. F = An error exists in the format of the request from the MIGS. VerStatus A = Authentication of your Merchant ID and Password to the ACS Directory Failed. D C = Error communicating with the Directory Server. = The card type is not supported for authentication. S = The response received from the Issuer was not consider authentic. VerSecurityLevel VerToken 3DSXID 3DSECI 3DSenrolled 3DSstatus P I = Invalid format message from Issuer. = Internal MIGS system error. This field contains the security level to be used in the payment message. Visa 05 - Fully authenticated Visa 06 - Not authenticated, (cardholder not participating), Visa 07 - Not authenticated MasterCard 0 - Merchant not participating (A merchant should never see this if they are configured for SecureCode) MasterCard 1 - Cardholder not participating MasterCard 2 - Cardholder authenticated The Accountholder Authentication Value (AVV MasterCard) or Cardholder Authentication Verification Value (CAVV - Visa) generated by the issuer s Access Control Server as a token to prove that the cardholder authenticated OK. It is a unique transaction identifier that is generated by the merchant to identify the transaction. The 3D Secure Electronic Commerce Indicator. This field is only included if the card is within an enrolled range. This is the value of the VERes.enrolled field. It will take values (Y - Yes, N - No, U Unavailable for Checking). This field is only included if 3-D Secure authentication was used and a PARes was received by the MPI. It will take values (Y Yes, N No, A Attempted Authentication, U Unavailable for Checking). Table 10 DO fields for a Merchant-Hosted Authentication and Payment transaction Page 15

21 Advanced Merchant Administration is used when the volume of transactions being too great to be economically viable or too difficult to be carried out manually. It allows the processing of certain administrative functions from the merchant s application via the Payment Client. Capture, Refund, Void Capture, Void Refund all return the same result. In all output string descriptors, the fields are returned in the sequences shown in Appendix A. 5.1 Digital Receipt The following Digital Receipt fields are retrieved in AMA transactions by doing a receipt enquiry: getresultfield("digitalreceipt.fieldname ) from the DR fields below. These fields apply to the following commands: AdminCapture AdminRefund AdminVoidCapture AdminVoidPurchase AdminVoidRefund The Digital Receipt is contains the following data: MerchantID ReceiptNo AcqResponseCode QSIResponse Code AuthorisationID TransactionNumber BatchNumber Not all of these fields is present for all AMA transactions, but the field for checking QSIResponse Code is present for all valid transactions, even when the transaction failed, there is a valid receipt (nextresult = True ) the QSIResponseCode is equal to doadmincapture The Admin Capture command allows a merchant to capture the funds from an Auth transaction. The MIGS Payment Cartridge requires a number of inputs to perform a doadmincapture transaction. These values are passed from the merchant software into the MIGS Payment Client by two different commands; addadmincommandfield To add supplementary data such as MerchTxnRef number. DoAdminCapture Generates and sends the Digital Order. Page 16

22 5.2.1 Digital Order Input Requirements The following data is sent using the supplementary command addadmincommandfield( FieldName, FieldValue). FieldName Input The Merchant Transaction Reference is an identifier the merchant assigns to the transaction. MerchTxnRef This field is used to later search for any lost receipts using the QueryDR command. 40 chars This identifier can use text made up of any of the base US ASCII characters in the range, decimal 20 to 126 excluding decimal 124, the character. Table 11 Additional doadmincommandfield Input Data Fields Page 17

23 FieldName Input merchantid The merchant ID is an alphanumeric identifier that is given to the merchant during the banks registration process, which is used to identify the merchant on the Payment Server. 16 chars There is a unique MerchantId for each merchant account/profile on the Payment Server. transactionnumber A unique number generated by the Payment Server for the transaction. Long 19 chars amount The purchase amount of the transaction expressed as the lowest currency denominator. It does not contain any decimal points, thousands separators or currency symbols, for example, $12.50 is expressed as Integer 10 chars username The user name for Advanced Merchant Administration. It cannot be used for Merchant Administration operations. 20 chars password The password used by the merchant to log in to Advanced Merchant Administration. It must be at least 8 characters long and contain at least one non-alphabetical character and must not be the same as the Merchant ID. 24 chars Table 12 doadmincapture Input Data Fields Digital Receipt Output Details These fields are retrieved using the supplementary command getresultfield( DigitalReceipt.FieldName ). FieldName Output Result The output result is a string list of 37 fields separated by the comma, character as defined in the Financial Transaction Result section in Appendix A. 450 chars Page 18

24 FieldName Output MerchantID The merchant ID is an alphanumeric identifier that is given to the merchant during the banks registration process, which is used to identify the merchant on the Payment Server. There is a unique MerchantId for each merchant account/profile on the Payment Server. (Returned Input Value) 16 chars ReceiptNo This is also known as the Reference Retrieval Number (RRN), which is a unique identifier, used to retrieve the original transaction data. This value is passed back to the customer for their records if the merchant application does not generate its own receipt number. 12 chars QSIResponseCode A response code that is generated by the Payment Server to indicate the status of the transaction. A QSIResponseCode of 0 (zero) indicates that the transaction was processed successfully and approved by the acquiring institution. Any other value indicates a transaction failure. 1 char A value of 7 indicates the Payment Server encountered an error and the merchant program should check for the error condition using the command DigitalReceipt.ERROR AcqResponseCode This Response Code is actually the issuer response code, generated by the issuing financial institution to indicate the status of the transaction.. The results can vary between institutions so it is advisable to use the QSIResponseCode as it is consistent across all acquirers. It is only included for fault finding purposes. 3 chars TransactionNo Payment Server Transaction Number is a unique number generated by the Payment Server. It is important to make sure the TransactionNo is stored for later retrieval if required to perform queries or Advanced Merchant Administration commands. For example it is required refund and capture transactions. 21 chars Page 19

25 FieldName Output AuthorizeId Authorisation Identification Code is issued by the issuring payment processor to approve or deny a transaction. 12 chars BatchNo Transaction Batch Number is the Batch number on the Payment Server that this transaction will be added to in order to be processed by the acquiring institution. 6 chars Table 13 doadmincapture Output Data Fields 5.3 doadminrefund The Admin Refund command allows a merchant to refund the funds from a previous run Purchase or Capture transaction. The MIGS Payment Client requires a number of inputs to perform a doadminrefund transaction. These values are passed from the merchant software into the MIGS Payment Client by two different commands: addadmincommandfield To add supplementary data such as MerchTxnRef number. doadminrefund generates and sends the Digital Order Digital Order Input Requirements The following data is sent using the supplementary command: addadmincommandfield ( FieldName, FieldValue). FieldName Input The Merchant Transaction Reference is an identifier the merchant assigns to the transaction. MerchTxnRef It can be later used to search for any lost receipts using the QueryDR command. 40 chars This identifier can use text made up of any of the base US ASCII characters in the range, decimal 20 to 126 excluding decimal 124, the character. Table 14 Additional doadminrefund Input Data Fields Page 20

26 FieldName Input merchantid The merchant ID is an alphanumeric identifier that is given to the merchant during the banks registration process, which is used to identify the merchant on the Payment Server. 16 chars There is a unique MerchantId for each merchant account/profile on the Payment Server. transactionnumber A unique number generated by the Payment Server for the transaction. Long 19 chars amount The purchase amount of the transaction expressed as the lowest currency denominator. It does not contain any decimal points, thousands separators or currency symbols, for example, $12.50 is expressed as Integer 4 bytes 10 chars username The user name for Advanced Merchant Administration. It cannot be used for Merchant Administration operations. 20 chars password The password used by the merchant to log in to Advanced Merchant Administration. It must be at least 8 characters long and contain at least one non-alphabetical character and must not be the same as the Merchant ID. 24 chars Table 15 doadminrefund Input Data Fields Digital Receipt Output Details These fields are retrieved using the supplementary command: getresultfield( DigitalReceipt.FieldName ). FieldName Output Result The output result from this operation is a sting list of 37 fields that are separated by the comma, character as defined in the Financial Transaction Result in Appendix A. 450 chars MerchantID The merchantid is an alphanumeric identifier that is given to the merchant during the banks registration process, which is used to identify the merchant on the Payment Server. There is a unique MerchantId for each merchant account/profile on the Payment (Returned Input Value) 16 chars Page 21

27 FieldName Server. Output ReceiptNo This is also known as the Reference Retrieval Number (RRN), which is a unique identifier, used to retrieve the original transaction data. This value is passed back to the customer for their records if the merchant application does not generate its own receipt number. 12 chars QSIResponseCode A response code that is generated by the Payment Server to indicate the status of the transaction. A QSIResponseCode of 0 (zero) indicates that the transaction was processed successfully and approved by the acquiring institution. Any other value indicates a transaction failure. 1 char A value of 7 indicates the Payment Server encountered an error and the merchant program should check for the error condition using the command DigitalReceipt.ERROR AcqResponseCode This Response Code is generated by the issuing financial institution to indicate the status of the transaction. The results can vary between institutions so it is advisable to use the QSIResponseCode as it is consistent across all acquirers. It is only included for fault finding purposes. 3 chars TransactionNo Payment Server Transaction Number is a unique number generated by the Payment Server. It is important to make sure the TransactionNo is stored for later retrieval if required to perform queries or Advanced Merchant Administration commands. For example it is required refund and capture transactions. 21 chars AuthorizeId Authorisation Identification Code is issued by the issuing financial institution to approve or deny a transaction. 12 chars BatchNo Transaction Batch Number is the Batch number on the Payment Server that this transaction will be added to in order to be processed by the acquiring institution. 6 chars Table 16 doadminrefund Output Data Fields Page 22

28 5.4 doadminvoidpurchase This command allows a merchant to void a purchase transaction. The MIGS Payment Client requires a number of inputs to perform a doadminvoidpurchase transaction. These values are passed from the merchant software into the MIGS Payment Client by two different commands, addadmincommandfield (to add supplementary data such as MerchTxnRef number, and doadminvoidpurchase, (which generates and sends the Digital Order) Digital Order Input Requirements The following data is sent using the supplementary command: addadmincommandfield( FieldName, FieldValue). FieldName Input The Merchant Transaction Reference is an identifier the merchant assigns to the transaction. MerchTxnRef It can be later used to search for any lost receipts using the QueryDR command. 40 chars This identifier can use text made up of any of the base US ASCII characters in the range, decimal 20 to 126 excluding decimal 124, the character. Table 17 Additional doadminvoidpurchase Input Data Fields FieldName Input merchantid The merchant ID is an alphanumeric identifier that is given to the merchant during the banks registration process, which is used to identify the merchant on the Payment Server. 16 chars There is a unique Merchant Id for each merchant account/profile on the Payment Server. transactionnumber A unique number generated by the Payment Server for the transaction. Long 19 chars username The user name for Advanced Merchant Administration. It cannot be used for Merchant Administration operations. 20 chars Page 23

29 FieldName Input password The password used by the merchant to log in to Advanced Merchant Administration. It must be at least 8 characters long and contain at least one non-alphabetical character and must not be the same as the Merchant ID. 24 chars Table 18 doadminvoidpurchase Input Data Fields Digital Receipt Output Details These fields are retrieved using the supplementary command: getresultfield( DigitalReceipt.FieldName ). FieldName Output Result The output result from this operation is a sting list of 37 fields that are separated by the comma, character as defined in the Financial Transaction Result in Appendix A. 450 chars MerchantID The merchant ID is an alphanumeric identifier that is given to the merchant during the banks registration process, which is used to identify the merchant on the Payment Server. There is a unique Merchant Id for each merchant account/profile on the Payment Server. (Returned Input Value) 16 chars ReceiptNo This is also known as the Reference Retrieval Number (RRN), which is a unique identifier, used to retrieve the original transaction data. This value is passed back to the customer for their records if the merchant application does not generate its own receipt number. 12 chars Page 24

30 FieldName Output QSIResponseCode A response code that is generated by the Payment Server to indicate the status of the transaction. A QSIResponseCode of 0 (zero) indicates that the transaction was processed successfully and approved by the acquiring institution. Any other value indicates a transaction failure. A value of 7 indicates the Payment Server encountered an error and the merchant program should check for the error condition using the command DigitalReceipt.ERROR 1 char AcqResponseCode This Response Code is generated by the issuing financial institution to indicate the status of the transaction. The results can vary between institutions so it is advisable to use the QSIResponseCode as it is consistent across all acquirers. It is only included for fault finding purposes. 3 chars TransactionNo Payment Server Transaction Number is a unique number generated by the Payment Server. It is important to make sure the TransactionNo is stored for later retrieval if required to perform queries or Advanced Merchant Administration commands. For example it is required refund and capture transactions. 21 chars AuthorizeId Authorisation Identification Code is issued by the issuing financial institution to approve or deny a transaction. 12 chars BatchNo Transaction Batch Number is the Batch number on the MIGS Payment Server that the original transaction was assigned. 6 chars Table 19 doadminvoidpurchase Output Data Fields Page 25

31 5.5 doadminvoidcapture This is a command to allow a merchant to void the funds from a previous run Capture transaction in an Auth/Capture mode of operation. This command does not function if the merchant is operating in a Purchase mode. The MIGS Payment Client requires a number of inputs to perform a doadminvoidcapture transaction. These values are passed from the merchant software into the MIGS Payment Client by two different commands, addadmincommandfield (to add supplementary data such as MerchTxnRef number, and doadminvoidcapture, (which generates and sends the Digital Order) Digital Order Input Requirements The following data is sent using the supplementary command: addadmincommandfield( FieldName, FieldValue). FieldName Input The Merchant Transaction Reference is an identifier the merchant assigns to the transaction. MerchTxnRef It can be used later to search for any lost receipts using the QueryDR command. 40 chars This identifier can use text made up of any of the base US ASCII characters in the range, decimal 20 to 126 excluding decimal 124, the character. Table 20 Additional doadminvoidcapture Input Data Fields FieldName Input merchantid The merchant ID is an alphanumeric identifier that is given to the merchant during the banks registration process, which is used to identify the merchant on the Payment Server. 16 chars There is a unique Merchant Id for each merchant account/profile on the Payment Server. transactionnumber A unique number generated by the Payment Server for the transaction. Long 19 chars Page 26

32 FieldName Input username The user name for Advanced Merchant Administration. It cannot be used for Merchant Administration operations. 20 chars password The password used by the merchant to log in to Advanced Merchant Administration. It must be at least 8 characters long and contain at least one non-alphabetical character and must not be the same as the Merchant ID. 24 chars Table 21 doadminvoidcapture Input Data Fields Digital Receipt Output Details This field is retrieved using the supplementary command: getresultfield( DigitalReceipt.FieldName ). FieldName Output Result The output result from this operation is a sting list of 37 fields that are separated by the comma, character as defined in the Financial Transaction Result in Appendix A. 450 chars MerchantID The merchant ID is an alphanumeric identifier that is given to the merchant during the banks registration process, which is used to identify the merchant on the Payment Server. There is a unique Merchant Id for each merchant account/profile on the Payment Server. (Returned Input Value) 16 chars ReceiptNo This is also known as the Reference Retrieval Number (RRN), which is a unique identifier, used to retrieve the original transaction data. This value is passed back to the customer for their records if the merchant application does not generate its own receipt number. Page 27

33 FieldName Output QSIResponseCode A response code that is generated by the Payment Server to indicate the status of the transaction. A QSIResponseCode of 0 (zero) indicates that the transaction was processed successfully and approved by the acquiring institution. Any other value indicates a transaction failure. 1 char A value of 7 indicates the Payment Server encountered an error and the merchant program should check for the error condition using the command DigitalReceipt.ERROR AcqResponseCode This Response Code is generated by the issuing financial institution to indicate the status of the transaction.. The results can vary between institutions so it is advisable to use the QSIResponseCode as it is consistent across all acquirers.. It is only included for fault finding purposes. 3 chars TransactionNo Payment Server Transaction Number is a unique number generated by the Payment Server. It is important to make sure the TransactionNo is stored for later retrieval if required to perform queries or Advanced Merchant Administration commands. For example it is required refund and capture transactions. 21 chars AuthorizeId Authorisation Identification Code is issued by the issuing financial institution to approve or deny a transaction. 12 chars BatchNo Transaction Batch Number is the Batch number on the MIGS Payment Server that the original transaction was assigned. 6 chars Table 22 doadminvoidcapture Output Data Fields Page 28

34 5.6 doquerydr This command allows a merchant to search for an Encrypted Digital Receipt for a transaction if the original receipt is lost. The search is performed on the key MerchTxnRef, so you should keep the MerchTxnRef field a unique value. If there are transactions with duplicate MerchTxnRef numbers, only the most recent transaction s encrypted digital receipt is returned, but a flag raised indicating there is more than one transaction. The MIGS Payment Cartridge requires a number of inputs to perform a doquerydr transaction. These values are passed from the merchant software into the MIGS Payment Client by doquerydr, command (which generates and sends the Digital Order) Digital Order Input Requirements!" FieldName Input merchantid The merchant ID is an alphanumeric identifier that is given to the merchant during the banks registration process, which is used to identify the merchant on the Payment Server. 16 chars There is a unique MerchantId for each merchant account/profile on the Payment Server. MerchTxnRef The search-identifier field this command uses to search. It returns the encrypted DR result that was used for the original transaction receipt. 40 chars username The user name for Advanced Merchant Administration. It cannot be used for Merchant Administration operations. 20 chars password The password used by the merchant to log in to Advanced Merchant Administration. It must be at least 8 characters long and contain at least one non-alphabetical character and must not be the same as the Merchant ID. 24 chars Table 23 doquerydr Input Data Fields Digital Receipt Output Details The result for an Admin QueryDR command will return a transaction receipt for a standard Merchant-Hosted or Server-Hosted transaction, or the standard AMA outputs with a comma delimited string for the appropriate AMA transaction. You must know what type of receipt you are expecting to enable you to generate the appropriate output. There are also a few extra keys values used in getresultfield supplementary command for QueryDR, that are not used elsewhere. This field is retrieved using the supplementary command: getresultfield( FieldName ). Page 29

35 FieldName Input QueryDR.DRExists This key is used to determine if the QueryDR command returned any search results. If the value is Y, then there is at least one MerchTxnRef number result matching the search criteria. 1 char For example, drexists = objpayclient.getresultfield("querydr.drexists"); QueryDR.FoundMultipleDRs This is used after the previous command to determine if there are multiple results. If the value is Y, then there are multiple MerchTxnRef numbers matching the search criteria. 1 char For example, multipledrs = objpayclient.getresultfield("querydr.foundmultipledrs"); Table 24 doquerydr Output Data Fields Once you have these details then you can use the supplementary command getresultfield( DigitalReceipt.FieldName ) to gather the output details you require for that transaction type, just as you would have for the original transaaction. Please see the preceding pages for the appropriate transaction type for the details that can be retrieved from the receipt. Page 30

36 !! " 6.1 echo This is a separate API method that only uses one variable and echo the value back to the Payment Client with echo: in the return value. It used to ensure the merchant application can communicate with the Payment Client. FieldName Input EchoValue The echo value the Payment Client uses to send back to the merchant application. Unspecified For example, echovalue = echo( Test ); The variable echovalue should return the result of echo:test Table 25 echo() Command Input Data Fields 6.2 nextresult This is a separate API method that does not require any variables and determines if there is a valid receipt. FieldName Input nextresult If the result of the principle command is true then you need to check if there is a result to retrieve. True is returned if results available, or false if no results are available Boolean True/False Table 26 nextresult Output Field 6.3 pcerror If the result of the primary or nextresult() commands returns false (for example, if there are no valid results), the command getresultfield("paymentclient.error"); is sent to the Payment Client to have the Payment Client return any details about the error. FieldName Input PcError Details of the error is sought if the result of the nextresult() returns false. A message nominally around 40 chars. If the error was an exception stack trace, it could be up to 2K bytes Table 27 pcerror Output Field Page 31