Thin Client Integration Guide Green Dot MoneyPak 8.0

Transcription

1 a u t h e n t i c a t i o n s o f t w a r e Cardinal Centinel TM for Merchants Thin Client Integration Guide Green Dot MoneyPak 8.0

2 Acknowledgements CardinalCommerce Corporation acknowledges with gratitude the contribution of its associates who developed the Cardinal Payment Authentication Platform by CardinalCommerce Corporation. All rights reserved. Trademark Information CardinalCommerce, Cardinal Centinel Authentication Software for Merchants, and Centinel are trademarks of CardinalCommerce Corporation. Green Dot MoneyPak is a registered trademark of Green Dot Corporation. Microsoft is a registered trademark of Microsoft Corporation. Microsoft Internet Explorer is a trademark of the Microsoft Corporation. All other trademarks are the properties of their respective owners. This manual may not, in whole or in part, be copied, photocopied, reproduced, translated, or converted to any electronic or machine readable form without prior written consent of CardinalCommerce Corporation. Contact Information CardinalCommerce Corporation 6119 Heisley Rd. Mentor, OH USA 2

3 TABLE OF CONTENTS 1 Introduction Transaction Overview The Green Dot MoneyPak Transaction Using Centinel Implementation Checklist Thin Client Thin Client Architecture Thin Client Integration Lookup Message Integration cmpi_lookup Authenticate Message Integration cmpi_authenticate Authorization Message Integration cmpi_authorize Capture Message Integration cmpi_capture Sale Message Integration cmpi_sale Refund Message Integration cmpi_refund Integration Notes Integration Configuration Configuring Centinel Test for Green Dot MoneyPak Transactions Configuring Production for Green Dot MoneyPak Transactions Integration Testing Integration Test Cases Moving To Production Integration Error Handling Common Centinel MAPS Errors cmpi_lookup cmpi_authenticate cmpi_authorize cmpi_capture cmpi_sale cmpi_refund Appendix A - ISO Codes ISO 4217 Currency Codes ISO 3166 Country Codes

4 1 Introduction This guide is intended for Merchants that are implementing Green Dot MoneyPak acceptance and processing through the use of the Cardinal Centinel Thin Client. This guide outlines the integration and testing procedures for completing the Thin Client implementation within an ecommerce system. Thin Client Versions The Cardinal Thin Client version number does not correspond to the Cardinal Centinel version number. The Thin Client version is specific to the respective Thin Client. The most recent version of all Thin Clients are available for download from the software downloads section of the Centinel Merchant Administration portal. 4

5 2 Transaction Overview 2.1 The Green Dot MoneyPak Transaction Using Centinel Green Dot MoneyPak is an easy to use online payment solution that gives the consumer the choice to pay for web based purchases through the use of a Green Dot MoneyPak Number. Green Dot MoneyPak Transaction Steps 1. Consumer shops online at Merchant website. At checkout, the Consumer selects the Green Dot MoneyPak payment type to complete the purchase. 2. Based on the payment information, the Merchant, via the Thin Client, passes a Lookup message to Centinel identified as a Green Dot MoneyPak transaction request. Centinel will store the transaction details and provide the URL of the Green Dot MoneyPak collection page on the Lookup Response. 3. The Merchant interprets the Lookup response and redirects the Consumer with a HTTP Form POST to the Green Dot MoneyPak collection URL. The redirect URL represents a Centinel website that will present the Green Dot MoneyPak collection form to the Consumer. 4. Centinel constructs the collection form and prompts the Consumer to enter a MoneyPak Number in order to complete the transaction. 5. Consumer submits a MoneyPak Number using the collection form and is redirected back to the Merchant's website. 6. The Merchant receives the Consumer's redirect from the Centinel website. 7. The Merchant formats and sends an Authenticate request message to Centinel for processing. Centinel will return the status of the MoneyPak Number collection process to the Merchant on the Authenticate response message. 8. Based on Authenticate response values, the Merchant updates their order management system. In the event that the Consumer has successfully entered a valid MoneyPak Number, the payment status will be pending. If the Consumer cancelled while at the collection form, the status will reflect the cancellation. In the case of a cancellation, the Consumer should be prompted for another form of payment to complete the transaction. 9. In the event that the Authenticate response values indicates the Consumer entered a valid MoneyPak Number successfully, the Merchant will send an Authorization/Sale request message to Centinel platform for processing. In the event that the processing with Green Dot completes successfully, funds will be transferred from the Consumer's MoneyPak. 5

6 3 Implementation Checklist A successful implementation is dependent on a few key components. The following checklist is intended to highlight these items to define a clear implementation task list covering installation, integration and configuration. During the implementation process, please use this checklist to track progress and address any remaining open items prior to deployment. Implementation Checklist 1. Perform Thin Client installation on test and production servers. Refer to the installation guide for the specific Thin Client(s) used for detailed installation instructions. 2. Register for Green Dot MoneyPak merchant account. Contact your sales representative for additional information. 3. Perform Green Dot MoneyPak API integration with your website. Refer to the integration samples provided in the Thin Client download and section 5 of this guide for detailed information on completing this task. 4. Update your website with the required Green Dot MoneyPak messaging and branding details. Refer to section 6 of this guide for detailed information on completing this task. 5. Configure the Centinel Test platform with your Green Dot MoneyPak merchant information. Refer to section 7.1 of this guide for detailed information on completing this task. 6. Complete all integration test cases using the Centinel Test environment. Refer to section 8 of this guide for detailed information on completing this task. 7. Configure the Production Centinel platform with your Green Dot MoneyPak merchant information. Refer to section 7.2 of this this guide for detailed information on completing this task. 8. From your test environment, execute transactions using the Centinel production environment to verify your profile configuration information. 9. From your Merchant website, run Live Test Transactions using the Green Dot MoneyPak payment option to verify that all components are in place and working correctly. Refer to section 8 of this guide for more information on completing this task. 10. Ensure that all business and operation requirements have been met before releasing the Green Dot MoneyPak payment option. 11. Release the website changes to production enabling the Green Dot MoneyPak payment option to your consumers. 6

7 4 Thin Client To assist merchants with the integration of our services with their ecommerce website, the Thin Client technology is available to minimize any custom development required by the Merchant. The Thin Client integration enables merchants to quickly communicate with the CardinalCommerce Application Service Provider (ASP) platform. This communication allows all the changing business rules and configuration information to be managed centrally within the ASP platform. As business rules or payment initiative programs evolve, these modifications are made centrally and do not effect the Merchant's ecommerce website directly. The hosted services minimize any ongoing maintenance, further allowing Merchants to focus on their business objectives instead of maintaining software. The following Centinel Thin Clients are currently available: Cold Fusion COM Java Microsoft.NET Perl PHP Included with the Thin Client technology are integration samples. These samples can be used as templates for integration and provide code samples for processing the API messages with the hosted service. The code samples include comments, which highlight error handling and general usage examples. Note: If one of the available Thin Clients does not meet your system requirements a direct XML integration solution is available. A XML Integration Guide is available for Merchants who wish to explore this option. 4.1 Thin Client Architecture The Thin Client has a common API for message handling. Each Thin Client exposes methods for request message creation, the sending and receiving of transaction data, and response message interpretation. Note: Detailed API information is available for each Thin Client in the Thin Client installation guides. Request Object Method Description Add Adds name / value pairs used to construct the XML Messages. Usage : void Add(String name, String value) Parameters : name - name of the parameter value - value of the parameter Returns : void SendHTTP Sends the request message to the Centinel MAPS. MAPS returns a response message. The response message is deserialized into name / value pairs and re- 7

8 turned from the method in the form of a Thin Client response object. Usage : ResponseObject SendHTTP(String transactionurl) Parameters : transactionurl - fully qualified transaction URL Returns : ResponseObject Note: The various platform versions of the Thin Client may overload this method and allow you to specify optional timeout parameters for the MAPS message communication. Response Object GetValue Method Description Returns the value for a named element returned on the response message. Usage : String GetValue(String name) Parameters : name - name of the parameter Returns : String value of the name parameter GetUnparsedResponse Returns the entire raw XML response message. Useful for debugging purposes. Usage : String GetUnparsedResponse() Parameters : none Returns : String value of the XML response 8

9 5 Thin Client Integration The Thin Client provides a communication shell that accepts name / value pairs. The name / value pairs are serialized to an XML message and communicated to the Centinel MAPS. The Centinel MAPS communicates the response message to the Thin Client, which makes the message elements available to the Merchant as name / value pairs. Centinel supports six transaction messages for Green Dot MoneyPak payment processing and post payment management. Message Name cmpi_lookup cmpi_authenticate cmpi_authorize cmpi_capture cmpi_sale cmpi_refund Description This message provides the order information to the Centinel platform to facilitate the processing of the Green Dot MoneyPak transaction. This message returns the status of the MoneyPak Number collection process to the Merchant. This message is used to settle a Green Dot MoneyPak payment transaction and obtain payment for either the full or partial amount of the previous transaction. This message is available for systems that do not support a sale transaction. This message returns the same results as the previous authorization. This message is available for systems that do not support a sale transaction. This message is used to settle a Green Dot MoneyPak payment transaction and obtain payment for either the full or partial amount of the previous transaction. This message performs a refund on a previously settled transaction. Both full and partial refunds are available. Note: Note that all API elements are case sensitive. Note: All Green Dot MoneyPak transactions must be processed in USD currency. Currently no other currency types are supported. The core transaction integration involves implementation of three messages, the Lookup (cmpi_lookup), Authenticate (cmpi_authenticate), and Sale (cmpi_sale) messages. Each message requires the Merchant to construct the message using the Thin Client and send the request message on to the Centinel platform. Merchants must utilize the response values to control the flow of the consumer's transaction. Included with the Thin Clients are integration samples, documentation and logos needed to complete the Green Dot MoneyPak integration. Within the code samples are additional comments on how to construct and process the required API messages. 5.1 Lookup Message Integration The Lookup Message (cmpi_lookup) is responsible for initiating the Green Dot MoneyPak payment. The integration point for the Lookup Message is immediately following the capture of the order information and the Green Dot MoneyPak option has been selected by the consumer as the method of payment. 9

10 The Lookup Message is constructed and sent to the Centinel platform for processing. The Lookup Message requires transaction specific data elements to be formatted on the request message. Please refer to the Message API section for the complete list of required message elements. The response message is returned from the Centinel platform, and the merchant integration utilizes the Thin Client to reference the response values. In the event that the Enrolled value is the ACSUrl element will contain a fully qualified URL that the consumer must be redirected to complete the Green Dot MoneyPak collection form. The url will represent a Centinel website that will use the data passed on the cmpi_lookup message to construct the MoneyPak Number collection form cmpi_lookup First transaction of the Lookup/Authenticate pair that is used to process the Green Dot MoneyPak transaction. In the event that the consumer selects Green Dot MoneyPak as a method of payment, the transaction will initiate the payment transaction. Request Message Field Name Description Field Definition Required MsgType cmpi_lookup AN(50) Version Application message version identifier. "1.7" AN(3) ProcessorId Merchant processor identification code. This value is assigned to the Merchant. AN(20) MerchantId Merchant identification code. This value is assigned to the Merchant. AN(50) TransactionPwd A password to secure and verify the transaction originated from merchant represented by the transaction details. The password value is configured through the merchant profile. Limit 50 characters AN(50) TransactionType Identifies the Transaction Type used for processing. AN(2) GD - Green Dot MoneyPak Amount Unformatted Total transaction amount without any decimalization. N(20) For example, $ = 10000, $ = 12367, $.99 = 99 CurrencyCode 3 digit numeric, ISO 4217 currency code for the sale amount. N(3) Green Dot MoneyPak Supported Currency Codes U.S. Dollar OrderNumber Order Number or transaction identifier from the Merchant commerce website. AN(50) 10

11 OrderDescription Brief description of items purchased. AN(125) N Consumer's address. AN(255) BillingFirstName Consumer's first name. AN(50) N BillingLastName Consumer's last name. AN(50) N BillingAddress1 Consumer's billing address information. AN(50) N BillingAddress2 Consumer's billing address information. AN(50) N BillingCity Consumer's city of their billing address. AN(50) N BillingState Consumer's state or province of their billing address. For example: Ohio - OH, Texas - TX. AN(50) N BillingPostalCode Consumer's postal code of their billing address. AN(10) N BillingCountryCode Consumer's country code of their billing address. Complete list of ISO 3166 country codes are available in the appendix of this guide. For example, United States - US A(3) N ShippingFirstName Consumer's first name. AN(50) N ShippingLastName Consumer's last name. AN(50) N ShippingAddress1 Consumer's shipping address information. AN(50) N ShippingAddress2 Consumer's shipping address information. AN(50) N ShippingCity Consumer's city of their shipping address. AN(50) N ShippingState Consumer's state or province of their shipping address. For example: Ohio - OH, Texas - TX. Limit 50 characters. AN(50) N ShippingPostalCode Consumer's postal code of their shipping address. AN(10) N ShippingCountryCode Consumer's country code of their shipping address. For example, United States - US AN(3) N IPAddress The IP Address of the consumer. Format NNN.NNN.NNN.NNN AN(20) Sample Message <CardinalMPI> <MsgType>cmpi_lookup</MsgType> <Version>1.7</Version> <ProcessorId>100</ProcessorId> <MerchantId>123456</MerchantId> <TransactionPwd>passw0rd</TransactionPwd> <TransactionType>GD</TransactionType> <OrderNumber> </OrderNumber> <Amount>12399</Amount> <CurrencyCode>840</CurrencyCode> <OrderDescription>Order # </OrderDesc> < >buyer@cardinalcommerce.com</ > 11

12 <BillingFirstName>Joe</BillingFirstName> <BillingLastName>User</BillingLastName> <BillingAddress>2333 Main Street</BillingAddress> <BillingCity>Mentor</BillingCity> <BillingState>OH</BillingState> <BillingPostalCode>44060</BillingPostalCode> <BillingCountryCode>US</BillingCountryCode> <BillingPhone> </BillingPhone> <ShippingFirstName>Joe</ShippingFirstName> <ShippingLastName>User</ShippingLastName> <ShippingAddress>2333 Main Street</ShippingAddress> <ShippingCity>Mentor</ShippingCity> <ShippingState>OH</ShippingState> <ShippingPostalCode>44060</ShippingPostalCode> <ShippingCountryCode>US</ShippingCountryCode> <ShippingPhone> </ShippingPhone> <IPAddress> </IPAddress> </CardinalMPI> Response Message This message is generated as a response to the cmpi_lookup message. Field Name Description Field Definition Required ErrorNo Application error number(s). A non-zero value represents the error encountered while attempting to process the message request. AN(500) ErrorDesc Application error description for the associated error number(s). AN(500) TransactionId Centinel transaction identifier. This value identifies the transaction within the Centinel system. To complete the transaction, the value is required to be passed on the Authenticate message to link the Lookup and Authenticate message together. AN(20) Enrolled Status of availability. AN(2) - Green Dot MoneyPak processing available U - Green Dot MoneyPak processing is unavailable ACSUrl The fully qualified URL to redirect the consumer to collect a MoneyPak Number in order to complete the Green Dot MoneyPak transaction. Available if Enrolled =. AN(2083) N Payload The encoded payment request. Available if Enrolled =. AN(7000) N Sample Message <CardinalMPI> <ErrorNo>0</ErrorNo> <ErrorDesc></ErrorDesc> <TransactionId>75f986t76f6fd5h68f5d</TransactionId> <Payload>eNpVUk1TwjAQ/SsM402nSUuKwSC/3gSoH5PL</Payload> <Enrolled></Enrolled> <ACSUrl> 12

13 </CardinalMPI> Processing the Response Message Verify the payment can be processed by evaluating the Enrolled element on the cmpi_lookup response message. In the event that the Enrolled element contains a value, the Green Dot MoneyPak payment is available and the consumer should be redirected to complete the transaction. The ACSUrl element contains the URL that the consumer should be redirected to in order to initiate the next step of the transaction. HTTP POST Redirect the consumer to the ACSUrl via a HTTP Form POST. Construct the following form populated with the values returned on the cmpi_lookup response message. Note: The form field names are case sensitive. <HTML> <BOD onload="document.frmlaunch.submit();"> <FORM name="frmlaunch" method="post" action="acsurl Value"> <input type=hidden name="pareq" value="payload Value"> <input type=hidden name="termurl" value="fully Qualified URL"> <input type=hidden name="md" value="session Tracking Value"> </FORM> </BOD> </HTML> Form Field Descriptions Field Name Description Field Definition Required ACSUrl The fully qualified URL to redirect the consumer to collect a MoneyPak Number in order to complete the Green Dot MoneyPak transaction. Value should be retrieved from the cmpi_lookup response message and inserted into the form. AN(2083) PaReq The encoded authentication or payment request. Value should be retrieved from the cmpi_lookup response message and inserted into the form. AN(7000) TermUrl The fully qualified URL of the Merchant webpage configured to receive the consumer returning from completing the Green Dot MoneyPak collection form. This URL will represent the webpage that will process the cmpi_authenticate message. AN(2083) MD Merchant session tracking identifier. The value will be returned to the TermUrl when the consumer is returned after completing the Green Dot MoneyPak collection form. The field is available if necessary. If not needed, simply pass an empty value on the form. AN(1024) 13

14 5.2 Authenticate Message Integration The Centinel platform will then redirect the consumer back to the TermUrl representing a web page on the Merchant's website. At that point, the merchant will process the Authenticate message (cmpi_authenticate) to retrieve the status from the MoneyPak Number collection process. The Authenticate Message is responsible for processing the Green Dot MoneyPak payment and returning the payment status to the merchant. The message will return the status of the payment, enabling the merchant to handle the order according to the outcome. In the event that the ErrorNo element is 0 (zero) and the SignatureVerification element is, indicating all fraud checks were satisfied, then the PAResStatus value will define how the transaction should be processed. Based on the transaction outcome the Merchant's order mangement system should be updated and the appropriate message should be displayed to the consumer. In the event that a non zero ErrorNo value is returned or the SignatureVerification element is N, the consumer should be prompted for an alternate form of payment cmpi_authenticate Second message of the Lookup/Authenticate pair used in processing the Green Dot MoneyPak transaction. Centinel will determine the outcome from the collection of the MoneyPak Number from the consumer and return the results on the response message. The PaRes value will be passed on the PAResPayload field of the request message. Request Message Field Name Description Field Definition Required MsgType cmpi_authenticate AN(50) Version Application message version identifier. "1.7" AN(3) ProcessorId Merchant processor identification code. This value is assigned to the Merchant. AN(20) MerchantId Merchant identification code. This value is assigned to the Merchant. AN(50) TransactionType Identifies the Transaction Type used for processing. AN(2) GD - Green Dot MoneyPak TransactionPwd A password to secure and verify the transaction originated from merchant represented by the transaction details. The password value is configured through the merchant profile. AN(50) PAResPayload PARes generated by the external system that processed the payment or authentication with the consumer. AN(10000) Sample Message 14

15 <CardinalMPI> <Version>1.7</Version> <MsgType>cmpi_authenticate</MsgType> <ProcessorId>100</ProcessorId> <MerchantId>123456</MerchantId> <TransactionType>W</TransactionType> <TransactionPwd>Passw0rd</TransactionPwd> <TransactionId>7fDSaySnCmDGCjPglzqX</TransactionId> <PAResPayload>********* Payload Message *********</PAResPayload> </CardinalMPI> Response Message This message is generated in response to the cmpi_authenticate request message. Field Name Description Field Definition Required ErrorDesc Application error description for the associated error number. AN(500) ErrorNo Application error number. A non-zero value represents the error encountered while attempting the process the message request. AN(500) PAResStatus Transaction status result identifier. AN(2) P - Pending Transaction X - Canceled Transaction E - Error Processing Transaction SignatureVerification Transaction Signature status identifier. AN(2) - Indicates that the signature of the PARes has been validated successfully and the message contents can be trusted. N - Indicates that for a variety of reasons; tampering, certificate expiration, etc. the PARes could not be validated, and the result should not be trusted. OrderId Centinel generated order identifier that is used to identify the Green Dot MoneyPak order within the Centinel system. N(16) Sample Message <CardinalMPI> <ErrorDesc></ErrorDesc> <ErrorNo>0</ErrorNo> <PAResStatus></PAResStatus> <SignatureVerification>P</SignatureVerification> <OrderId> </OrderId> </CardinalMPI> 15

16 5.3 Authorization Message Integration The Authorization message (cmpi_authorize) is available for order management systems that do not support a sale transaction. The authorize message is responsible for processing the settlement of the Green Dot MoneyPak transaction. Upon successful completion, funds are transferred from the Consumer's MoneyPak to the Merchant. More than one authorization transaction can be processed against an original Green Dot MoneyPak transaction cmpi_authorize The cmpi_authorize message is used to settle a previously created Green Dot MoneyPak transaction. During processing of the authorize message, funds are transferred from the consumer's MoneyPak to the merchant. This message is available for systems that do not support a sale transaction. Either the TransactionId returned on the cmpi_lookup response must be passed in the TransactionId field in the cmpi_authorize request, or the OrderId returned on the cmpi_authenticate response must be passed in the OrderId field of the cmpi_authorize request in order for the transaction to process successfully. Request Message Field Name Description Field Definition Required MsgType cmpi_authorize AN(50) Version Application message version identifier. "1.7" AN(3) ProcessorId Merchant processor identification code. This value is assigned to the Merchant. AN(20) MerchantId Merchant identification code. This value is assigned to the Merchant. AN(50) TransactionPwd A password to secure and verify the transaction originated from merchant represented by the transaction details. The password value is configured through the merchant profile. AN(50) TransactionType Identifies the Transaction Type used for processing. [ GD ] GD Green Dot MoneyPak AN(2) OrderId Centinel generated order identifier. N(16) N TransactionId Centinel generated transaction identifier. AN(20) N Amount Unformatted transaction amount without any decimalization. N(20) For example, $ = 10000, $ = 12367, $.99 = 99 CurrencyCode 3 digit numeric, ISO 4217 currency code for the sale amount. N(3) 16

17 Green Dot MoneyPak Supported Currency Codes U.S. Dollar Description Brief description of items purchased, limited to 125 characters. AN(125) N Sample Message <CardinalMPI> <MsgType>cmpi_authorize</MsgType> <Version>1.7</Version> <ProcessorId>100</ProcessorId> <MerchantId>123456</MerchantId> <TransactionPwd>Passw0rd</TransactionPwd> <TransactionType>GD</TransactionType> <TransactionId>7fDSaySnCmDGCjPglzqX</TransactionId> <Amount>34920</Amount> <CurrencyCode>840</CurrencyCode> <Description>Goods Shipped to Consumer</Description> </CardinalMPI> Response Message This message is generated in response to the cmpi_authorize message. Field Name Description Field Definition Required ErrorNo Application error number. A non-zero value represents the error encountered while attempting the process the message request. AN(500) ErrorDesc Application error description for the associated error number. AN(500) StatusCode Status Result of the transaction. AN(2) Transaction successful E Transaction resulted in Error TransactionId Centinel generated transaction identifier. AN(20) Sample Message <CardinalMPI> <ErrorNo>0</ErrorNo> <ErrorDesc></ErrorDesc> <StatusCode></StatusCode> <TransactionId>7fDSaySnCmDGCjPglzqX</TransactionId> </CardinalMPI> 5.4 Capture Message Integration The Capture message (cmpi_capture) is available for order management systems that do not support a sale transaction. The Capture transaction will return the same results as the previously processed au- 17

18 thorization transaction cmpi_capture The cmpi_capture message can be used to return the same results as the previous authorization that was processed for those systems that do not support the use of a sale transaction. Since funds are transferred from the consumer's MoneyPak Number during the processsing of the cmpi_authorize message, no funds are transferred during the cmpi_capture processing. Either the TransactionId returned on the cmpi_lookup response must be passed in the TransactionId field in the cmpi_capture request, or the OrderId returned on the cmpi_authenticate response must be passed in the OrderId field of the cmpi_capture request in order for the transaction to process successfully. Request Message Field Name Description Field Definition Required MsgType cmpi_capture AN(50) Version Application message version identifier. "1.7" AN(3) ProcessorId Merchant processor identification code. This value is assigned to the Merchant. AN(20) MerchantId Merchant identification code. This value is assigned to the Merchant. AN(50) TransactionPwd A password to secure and verify the transaction originated from merchant represented by the transaction details. The password value is configured through the merchant profile. AN(50) TransactionType Identifies the Transaction Type used for processing. [ GD ] GD Green Dot MoneyPak AN(2) OrderId Centinel generated order identifier. N(16) N TransactionId Centinel generated transaction identifier. AN(20) N Amount Unformatted transaction amount without any decimalization. N(20) For example, $ = 10000, $ = 12367, $.99 = 99 CurrencyCode 3 digit numeric, ISO 4217 currency code for the sale amount. N(3) Green Dot MoneyPak Supported Currency Codes U.S. Dollar Description Brief description of items purchased, limited to 125 AN(125) N 18

19 characters. Sample Message <CardinalMPI> <MsgType>cmpi_capture</MsgType> <Version>1.7</Version> <ProcessorId>100</ProcessorId> <MerchantId>123456</MerchantId> <TransactionPwd>Passw0rd</TransactionPwd> <TransactionType>GD</TransactionType> <TransactionId>7fDSaySnCmDGCjPglzqX</TransactionId> <Amount>34920</Amount> <CurrencyCode>840</CurrencyCode> <Description>Goods Shipped to Consumer</Description> </CardinalMPI> Response Message This message is generated in response to the cmpi_capture message. Field Name Description Field Definition Required ErrorNo Application error number. A non-zero value represents the error encountered while attempting the process the message request. AN(500) ErrorDesc Application error description for the associated error number. AN(500) StatusCode Status Result of the transaction. AN(2) Transaction successful E Transaction resulted in Error TransactionId Centinel generated transaction identifier. AN(20) Sample Message <CardinalMPI> <ErrorNo>0</ErrorNo> <ErrorDesc></ErrorDesc> <StatusCode></StatusCode> <TransactionId>7fDSaySnCmDGCjPglzqX</TransactionId> </CardinalMPI> 5.5 Sale Message Integration The Sale message (cmpi_sale) is responsible for processing the settlement of the Green Dot MoneyPak transaction. Upon successful completion, funds are transferred from the Consumer's MoneyPak to the Merchant. More than one sale transaction can be processed against an original Green Dot MoneyPak transaction. 19

20 5.5.1 cmpi_sale The cmpi_sale message is used to settle a previously created Green Dot MoneyPak transaction. During processing of the sale message, funds are transferred from the consumer's MoneyPak to the merchant. Either the TransactionId returned on the cmpi_lookup response must be passed in the TransactionId field in the cmpi_sale request, or the OrderId returned on the cmpi_authenticate response must be passed in the OrderId field of the cmpi_sale request in order for the transaction to process successfully. Request Message Field Name Description Field Definition Required MsgType cmpi_sale AN(50) Version Application message version identifier. "1.7" AN(3) ProcessorId Merchant processor identification code. This value is assigned to the Merchant. AN(20) MerchantId Merchant identification code. This value is assigned to the Merchant. AN(50) TransactionPwd A password to secure and verify the transaction originated from merchant represented by the transaction details. The password value is configured through the merchant profile. AN(50) TransactionType Identifies the Transaction Type used for processing. [ GD ] GD Green Dot MoneyPak AN(2) OrderId Centinel generated order identifier. N(16) N TransactionId Centinel generated transaction identifier. AN(20) N Amount Unformatted transaction amount without any decimalization. N(20) For example, $ = 10000, $ = 12367, $.99 = 99 CurrencyCode 3 digit numeric, ISO 4217 currency code for the sale amount. N(3) Green Dot MoneyPak Supported Currency Codes U.S. Dollar Description Brief description of items purchased, limited to 125 characters. AN(125) N Sample Message 20

21 <CardinalMPI> <MsgType>cmpi_sale</MsgType> <Version>1.7</Version> <ProcessorId>100</ProcessorId> <MerchantId>123456</MerchantId> <TransactionPwd>Passw0rd</TransactionPwd> <TransactionType>GD</TransactionType> <TransactionId>7fDSaySnCmDGCjPglzqX</TransactionId> <Amount>34920</Amount> <CurrencyCode>840</CurrencyCode> <Description>Goods Shipped to Consumer</Description> </CardinalMPI> Response Message This message is generated in response to the cmpi_sale message. Field Name Description Field Definition Required ErrorNo Application error number. A non-zero value represents the error encountered while attempting the process the message request. AN(500) ErrorDesc Application error description for the associated error number. AN(500) StatusCode Status Result of the transaction. AN(2) Transaction successful E Transaction resulted in Error TransactionId Centinel generated transaction identifier. AN(20) Sample Message <CardinalMPI> <ErrorNo>0</ErrorNo> <ErrorDesc></ErrorDesc> <StatusCode></StatusCode> <TransactionId>7fDSaySnCmDGCjPglzqX</TransactionId> </CardinalMPI> 5.6 Refund Message Integration The Refund message (cmpi_refund) is responsible for crediting the consumer some portion of the original settlement amount. Multiple refunds can be processed against the original Green Dot MoneyPak transaction cmpi_refund The cmpi_refund message is used to refund a previously settled Green Dot MoneyPak transaction. During processing of the refund message, funds are transferred from the merchant to the consumer's MoneyPak. 21

22 Either the TransactionId returned on the cmpi_lookup response must be passed in the TransactionId field in the cmpi_refund request, or the OrderId returned on the cmpi_authenticate response must be passed in the OrderId field of the cmpi_refund request in order for the transaction to process successfully. Request Message Field Name Description Field Definition Required MsgType cmpi_refund AN(50) Version Application message version identifier. "1.7" AN(3) ProcessorId Merchant processor identification code. This value is assigned to the Merchant. AN(20) MerchantId Merchant identification code. This value is assigned to the Merchant. AN(50) TransactionPwd A password to secure and verify the transaction originated from merchant represented by the transaction details. The password value is configured through the merchant profile. AN(50) TransactionType Identifies the Transaction Type used for processing. [ GD ] GD Green Dot MoneyPak AN(2) OrderId Centinel generated order identifier. N(16) N TransactionId Centinel generated transaction identifier. AN(20) N Amount Unformatted transaction amount without any decimalization. N(20) For example, $ = 10000, $ = 12367, $.99 = 99 CurrencyCode 3 digit numeric, ISO 4217 currency code for the sale amount. N(3) Green Dot MoneyPak Supported Currency Codes U.S. Dollar Description Brief description of items purchased, limited to 125 characters. AN(125) N Sample Message <CardinalMPI> <MsgType>cmpi_refund</MsgType> <Version>1.7</Version> <ProcessorId>100</ProcessorId> <MerchantId>123456</MerchantId> <TransactionPwd>Passw0rd</TransactionPwd> 22

23 <TransactionType>GD</TransactionType> <TransactionId>7fDSaySnCmDGCjPglzqX</TransactionId> <Amount>34920</Amount> <CurrencyCode>840</CurrencyCode> <Description>Goods Shipped to Consumer</Description> </CardinalMPI> Response Message This message is generated in response to the cmpi_refund message. Field Name Description Field Definition Required ErrorNo Application error number. A non-zero value represents the error encountered while attempting the process the message request. AN(500) ErrorDesc Application error description for the associated error number. AN(500) StatusCode Status Result of the transaction. AN(2) Transaction successful E Transaction resulted in Error TransactionId Centinel generated transaction identifier. AN(20) Sample Message <CardinalMPI> <ErrorNo>0</ErrorNo> <ErrorDesc></ErrorDesc> <StatusCode></StatusCode> <TransactionId>7fDSaySnCmDGCjPglzqX</TransactionId> </CardinalMPI> 23

24 6 Integration Notes In addition to the API integration to facilitate the Green Dot MoneyPak process, the Merchant must also make some important enhancements to the website to support the Green Dot MoneyPak transaction. Please refer to the Green Dot MoneyPak Integration materials for additional information. 24

25 7 Integration Configuration To support integration testing the Centinel Test system ( is available. This allows merchants to integrate and maintain test systems separate from their production deployments. To test the Centinel transaction processing specific configuration parameters must be defined within the Centinel Test system. 7.1 Configuring Centinel Test for Green Dot MoneyPak Transactions To support the Green Dot MoneyPak payment processing, specific parameters must be defined within the Centinel Test Merchant profile. The following steps detail the configuration process and cover all parameters that must be configured to support the integration. The test environment has been pre-configured with Green Dot MoneyPak profile information collected during the Centinel registration process. Step 1 - Login to your Centinel Test Merchant account. By default your username/password credential to login to the test system is your assigned MerchantId value and the password "changeit." Go to the Centinel Test Website ( and login to your test Merchant account. 25

26 Step 2 - Configure your test Merchant Profile for Green Dot MoneyPak. The Centinel Test system requires specific configuration settings to enable the Green Dot MoneyPak payment processing. Once you are logged into the Centinel Test website, Click through the following : Manage Profile > Manage Payment Initiative Configuration > Create Payment Initiative Configuration Select Green Dot MoneyPak from the dropdown box and click the enter button. Note that if your profile already has a Green Dot MoneyPak configuration defined, an error message will be returned. If configuration updates must be made go to the Update Payment Inititive Configuration section. 26

27 The Green Dot MoneyPak configuration requires the following information. Configuration Green Dot MoneyPak Partner Id Green Dot MoneyPak Settlement Group Green Dot MoneyPak Payment Type Code Merchant Display Name Merchant Address1 Merchant Address2 Merchnat City Merchant State Description Green Dot provided partner identifier. Group name provided by Green Dot that is used during settlement. Green Dot provided code that identifies the type of payment that is being made. The name that will be displayed to the Consumer on the MoneyPak Number collection form. Business address that will be displayed to the Consumer on the MoneyPak Number collection form. Business address that will be displayed to the Consumer on the MoneyPak Number collection form. Business city that will be displayed to the Consumer on the MoneyPak Number collection form. Business state that will be displayed to the Consumer on the MoneyPak Number collection form. 27

28 Merchant Country Merchant Postal Code Merchant Phone Merchant Support Address Business country that will be displayed to the Consumer on the MoneyPak Number collection form. Business postal code that will be displayed to the Consumer on the MoneyPak Number collection form. Contact phone number that will be displayed to the Consumer on the MoneyPak Number collection form. Consumers should be able to use this phone number to contact the merchant's customer service department. Merchant support address that will be displayed to the Consumer on the MoneyPak Number collection form. Consumers should be able to use this address to contact the merchant's customer service department. 7.2 Configuring Production for Green Dot MoneyPak Transactions To support the Green Dot MoneyPak payment processing, specific parameters must be defined within the Production Centinel Merchant profile. The following steps detail the configuration process and cover all parameters that must be configured to support the integration. Step 1 - Login to your Production Centinel Merchant account. our username and password for your production account are provided to you through the registration Welcome Pack . Please contact Cardinal Merchant support if you have any difficulties accessing your account. 28

29 Step 2 - Configure your Merchant Profile for Green Dot MoneyPak. The Centinel platform requires specific configuration settings to enable the Green Dot MoneyPak payment processing. Once you are logged into the Production Centinel website, Click thru the following : Manage Profile > Manage Payment Initiative Configuration > Create Payment Initiative Configuration 29

30 Select Green Dot MoneyPak from the dropdown box and click the enter button. Note that if your profile already has a Green Dot MoneyPak configuration defined, an error message will be returned. If configuration updates must be made go to the Update Payment Inititive Configuration section. 30

31 The Green Dot MoneyPak configuration requires the following information. Configuration Green Dot MoneyPak Partner Id Green Dot MoneyPak Settlement Group Green Dot MoneyPak Payment Type Code Merchant Display Name Merchant Address1 Merchant Address2 Merchnat City Merchant State Description Green Dot provided partner identifier. Group name provided by Green Dot that is used during settlement. Green Dot provided code that identifies the type of payment that is being made. The name that will be displayed to the Consumer on the MoneyPak Number collection form. Business address that will be displayed to the Consumer on the MoneyPak Number collection form. Business address that will be displayed to the Consumer on the MoneyPak Number collection form. Business city that will be displayed to the Consumer on the MoneyPak Number collection form. Business state that will be displayed to the Consumer on the MoneyPak Number collection form. 31

32 Merchant Country Merchant Postal Code Merchant Phone Merchant Support Address Business country that will be displayed to the Consumer on the MoneyPak Number collection form. Business postal code that will be displayed to the Consumer on the MoneyPak Number collection form. Contact phone number that will be displayed to the Consumer on the MoneyPak Number collection form. Consumers should be able to use this phone number to contact the merchant's customer service department. Merchant support address that will be displayed to the Consumer on the MoneyPak Number collection form. Consumers should be able to use this address to contact the merchant's customer service department. 32

33 8 Integration Testing Testing is critical to successful implementations. It is important that all the positive and negative response codes be tested and handled according to the recommended guidelines. Included in this guide is a list of specific test cases that cover the testing of these scenarios. Each of these scenarios should be verified using the Centinel Test system. Note: Each of these scenarios can be processed through production Centinel and Green Dot MoneyPak systems, however, actual funds will be transferred and the respective transaction fees will apply. 8.1 Integration Test Cases To assist your integration efforts, the Centinel Testing Facility is available to perform various predefined integration tests. Once you have completed integration with your site, testing can begin by sending messages to the test platform using the defined test case parameters outlined within this section. Note: Centinel Test Transaction URL : Note: The Centinel Test system requires merchants to use their assigned ProcessorId and MerchantId values for transaction processing. Test cases cover the processing of the Green Dot MoneyPak, TransactionType = GD, transactions within the Centinel platform. These integration test cases apply to the cmpi_lookup, cmpi_authenticate, cmpi_authorize, cmpi_capture, cmpi_sale, and cmpi_refund message types. The integration testing uses the First Name (BillingFirstName API field) of the consumer making the purchase to determine the test case to be executed. Each test case outlines the expected BillingFirstName value and the corresponding test case outcome below. Test Case 1 Description Messages Merchant Action BillingFirst- Name = Test1 Consumer places order with Green Dot MoneyPak as method of payment. The consumer enters a valid MoneyPak Number on the collection form and the transaction is created. The transaction is successfully settled by the merchant. cmpi_lookup response ErrorNo = 0 ErrorDesc = <blank> Enrolled = Payload= <value> ACSUrl = <value> TransactionId = <value> cmpi_authenticate response PAResStatus = P SignatureVerification = ErrorNo = 0 ErrorDesc = <blank> OrderId = <value> Display order confirmation status message to the consumer. Ship the goods to the consumer when the cmpi_sale response results in a success. cmpi_sale response StatusCode = ErrorNo = 0 ErrorDesc = <blank> TransactionId = <value> 33

34 Test Case 2 Description Messages Merchant Action BillingFirst- Name = Test2 Consumer places order with Green Dot MoneyPak as method of payment. The consumer enters multiple valid pins on the collection form in order to complete the transaction. The transaction is successfully settled by the merchant. cmpi_lookup response ErrorNo = 0 ErrorDesc = <blank> Enrolled = Payload= <value> ACSUrl = <value> TransactionId = <value> cmpi_authenticate response PAResStatus = P SignatureVerification = ErrorNo = 0 ErrorDesc = <blank> OrderId = <value> Display order confirmation status message to the consumer. Ship the goods to the consumer when the cmpi_sale response results in a success. cmpi_sale response StatusCode = ErrorNo = 0 ErrorDesc = <blank> TransactionId = <value> Test Case 3 Description Messages Merchant Action BillingFirst- Name = Test3 Green Dot MoneyPak payments are currently unavailable. cmpi_lookup response ErrorNo = 0 ErrorDesc = <blank> Enrolled = U Payload= <blank> ACSUrl = <blank> TransactionId = <value> Display message indicating that Green Dot MoneyPak is currently unavailable for payment processing. Prompt the consumer for another form of payment to complete the purchase. Test Case 4 Description Messages Merchant Action BillingFirst- Name = Test4 An error was encountered processing the cmpi_lookup message. cmpi_lookup response ErrorNo = <value> ErrorDesc = <value> Enrolled = U Payload= <blank> ACSUrl = <blank> TransactionId = <value> Display message indicating that Green Dot MoneyPak is currently unavailable for payment processing. Prompt the consumer for another form of payment to complete the purchase. Test Case 5 Description Messages Merchant Action BillingFirst- Name = Test5 Consumer places order with Green Dot MoneyPak as method of payment, however, the authenticate message rescmpi_lookup response ErrorNo = 0 ErrorDesc = <blank> Enrolled = Payload= <value> Display a message to the consumer indicating that the payment was unable to complete and prompt for another form of pay- 34

35 ults in an error. ACSUrl = <value> TransactionId = <value> cmpi_authenticate response PAResStatus = E SignatureVerification = ErrorNo = <value> ErrorDesc = <value> ment to complete the purchase. Test Case 6 Description Messages Merchant Action BillingFirst- Name = Test6 Consumer places order with Green Dot MoneyPak as method of payment. The consumer enters a valid MoneyPak Number on the collection form, however, an error is encountered processing the cmpi_sale message. cmpi_lookup response ErrorNo = 0 ErrorDesc = <blank> Enrolled = Payload= <value> ACSUrl = <value> TransactionId = <value> cmpi_authenticate response PAResStatus = P SignatureVerification = ErrorNo = 0 ErrorDesc = <blank> OrderId = <value> Display a message to the consumer indicating that the payment was unable to complete and prompt for another form of payment to complete the purchase. cmpi_sale response StatusCode = E ErrorNo = <value> ErrorDesc = <value> TransactionId = <value> Test Case 7 Description Messages Merchant Action BillingFirst- Name = Test7 Consumer places order with Green Dot MoneyPak as method of payment. The consumer enters a valid MoneyPak Number on the collection form and the authorize results in a success to transfer funds from the MoneyPak Number, however, the capture results in an error. cmpi_lookup response ErrorNo = 0 ErrorDesc = <blank> Enrolled = Payload= <value> ACSUrl = <value> TransactionId = <value> cmpi_authenticate response PAResStatus = P SignatureVerification = ErrorNo = 0 ErrorDesc = <blank> OrderId = <value> Display order confirmation status message to the consumer. Ship the goods to the consumer because the authorize response resulted in a success and the funds have been transferred from the MoneyPak Number. Review the error codes from the capture response and resubmit the transaction if necessary. cmpi_authorize response StatusCode = ErrorNo = 0 ErrorDesc = <blank> TransactionId = <value> cmpi_capture response StatusCode = E 35