THIN CLIENT INTEGRATION GUIDE GREEN DOT MONEYPAK - CARDINAL CENTINELTM FOR MERCHANTS
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
a u t h e n t i c a t i o n s o f t w a r e
Cardinal CentinelTM for Merchants
Thin Client Integration Guide
Green Dot MoneyPak
8.0
Acknowledgements CardinalCommerce Corporation acknowledges with gratitude the contribution of its associates who developed the Cardinal Payment Authentication Platform. © 2006 by CardinalCommerce Corporation. All rights reserved. Trademark Information CardinalCommerce, Cardinal Centinel Authentication Software for Merchants, and Centinel are trade- marks 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 trade- mark 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 Cor- poration. Contact Information CardinalCommerce Corporation 6119 Heisley Rd. Mentor, OH 44060 USA www.cardinalcommerce.com Thin Client Integration Guide - Green Dot MoneyPak (Revision 01) 2
TABLE OF CONTENTS
1 Introduction........................................................................................................................... 4
2 Transaction Overview...........................................................................................................5
2.1 The Green Dot MoneyPak Transaction Using Centinel......................................................................... 5
3 Implementation Checklist.................................................................................................... 6
4 Thin Client............................................................................................................................. 7
4.1 Thin Client Architecture......................................................................................................................... 7
5 Thin Client Integration.........................................................................................................9
5.1 Lookup Message Integration.................................................................................................................. 9
5.1.1 cmpi_lookup.................................................................................................................................10
5.2 Authenticate Message Integration........................................................................................................ 14
5.2.1 cmpi_authenticate........................................................................................................................ 14
5.3 Authorization Message Integration.......................................................................................................16
5.3.1 cmpi_authorize.............................................................................................................................16
5.4 Capture Message Integration................................................................................................................ 17
5.4.1 cmpi_capture................................................................................................................................ 18
5.5 Sale Message Integration...................................................................................................................... 19
5.5.1 cmpi_sale..................................................................................................................................... 20
5.6 Refund Message Integration................................................................................................................. 21
5.6.1 cmpi_refund................................................................................................................................. 21
6 Integration Notes.................................................................................................................24
7 Integration Configuration.................................................................................................. 25
7.1 Configuring Centinel Test for Green Dot MoneyPak Transactions..................................................... 25
7.2 Configuring Production for Green Dot MoneyPak Transactions......................................................... 28
8 Integration Testing..............................................................................................................33
8.1 Integration Test Cases...........................................................................................................................33
9 Moving To Production........................................................................................................37
10 Integration Error Handling............................................................................................. 38
10.1 Common Centinel MAPS Errors........................................................................................................ 38
10.2 cmpi_lookup....................................................................................................................................... 38
10.3 cmpi_authenticate............................................................................................................................... 41
10.4 cmpi_authorize................................................................................................................................... 43
10.5 cmpi_capture.......................................................................................................................................45
10.6 cmpi_sale............................................................................................................................................ 46
10.7 cmpi_refund........................................................................................................................................ 47
11 Appendix A - ISO Codes.................................................................................................. 51
11.1 ISO 4217 Currency Codes.................................................................................................................. 51
11.2 ISO 3166 Country Codes....................................................................................................................57
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
31 Introduction This guide is intended for Merchants that are implementing Green Dot MoneyPak acceptance and pro- cessing 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 num- ber. 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. Thin Client Integration Guide - Green Dot MoneyPak (Revision 01) 4
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 Con-
sumer.
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 pro-
cessing. 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 sys-
tem. 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.
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
53 Implementation Checklist
A successful implementation is dependent on a few key components. The following checklist is inten-
ded 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 in-
structions.
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 informa-
tion.
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 pay-
ment 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.
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
64 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 Cli-
ent integration enables merchants to quickly communicate with the CardinalCommerce Application
Service Provider (ASP) platform. This communication allows all the changing business rules and con-
figuration 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 tem-
plates for integration and provide code samples for processing the API messages with the hosted ser-
vice. The code samples include comments, which highlight error handling and general usage ex-
amples.
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 re-
quest message creation, the sending and receiving of transaction data, and response message interpret-
ation.
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-
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
7turned 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
Method Description
GetValue 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 pur-
poses.
Usage :
String GetUnparsedResponse()
Parameters :
none
Returns :
String value of the XML response
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
85 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 Description
cmpi_lookup This message provides the order information to the Centinel platform to facil-
itate the processing of the Green Dot MoneyPak transaction.
cmpi_authenticate This message returns the status of the MoneyPak Number collection process
to the Merchant.
cmpi_authorize 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 trans-
action.
This message is available for systems that do not support a sale transaction.
cmpi_capture This message returns the same results as the previous authorization.
This message is available for systems that do not support a sale transaction.
cmpi_sale 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 trans-
action.
cmpi_refund 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 cur-
rency 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 re-
quires 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 com-
plete 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 in-
formation and the Green Dot MoneyPak option has been selected by the consumer as the method of
payment.
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
9The 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 Y the ACSUrl ele-
ment 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.
5.1.1 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 Required
Definition
MsgType cmpi_lookup AN(50) Y
Version Application message version identifier. "1.7" AN(3) Y
ProcessorId Merchant processor identification code. This value is AN(20) Y
assigned to the Merchant.
MerchantId Merchant identification code. This value is assigned AN(50) Y
to the Merchant.
TransactionPwd A password to secure and verify the transaction ori- AN(50) Y
ginated from merchant represented by the transaction
details. The password value is configured through the
merchant profile. Limit 50 characters
TransactionType Identifies the Transaction Type used for processing. AN(2) Y
GD - Green Dot MoneyPak
Amount Unformatted Total transaction amount without any N(20) Y
decimalization.
For example, $100.00 = 10000, $123.67 = 12367,
$.99 = 99
CurrencyCode 3 digit numeric, ISO 4217 currency code for the sale N(3) Y
amount.
Green Dot MoneyPak Supported Currency Codes
840 - U.S. Dollar
OrderNumber Order Number or transaction identifier from the Mer- AN(50) Y
chant commerce website.
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
10OrderDescription Brief description of items purchased. AN(125) N
EMail Consumer's email address. AN(255) Y
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. AN(50) N
For example: Ohio - OH, Texas - TX.
BillingPostalCode Consumer's postal code of their billing address. AN(10) N
BillingCountryCode Consumer's country code of their billing address. A(3) N
Complete list of ISO 3166 country codes are avail-
able in the appendix of this guide. For example,
United States - US
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 ad- AN(50) N
dress. For example: Ohio - OH, Texas - TX. Limit 50
characters.
ShippingPostalCode Consumer's postal code of their shipping address. AN(10) N
ShippingCountryCode Consumer's country code of their shipping address. AN(3) N
For example, United States - US
IPAddress The IP Address of the consumer. Format AN(20) Y
NNN.NNN.NNN.NNN
Sample Message
cmpi_lookup
1.7
100
123456
passw0rd
GD
992397541265
12399
840
Order #182397541265
buyer@cardinalcommerce.com
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
11Joe
User
2333 Main Street
Mentor
OH
44060
US
4402554444
Joe
User
2333 Main Street
Mentor
OH
44060
US
4402554444
207.48.141.20
Response Message
This message is generated as a response to the cmpi_lookup message.
Field Name Description Field Required
Definition
ErrorNo Application error number(s). A non-zero value rep- AN(500) Y
resents the error encountered while attempting to pro-
cess the message request.
ErrorDesc Application error description for the associated error AN(500) Y
number(s).
TransactionId Centinel transaction identifier. This value identifies AN(20) Y
the transaction within the Centinel system. To com-
plete the transaction, the value is required to be
passed on the Authenticate message to link the Look-
up and Authenticate message together.
Enrolled Status of availability. AN(2) Y
Y - Green Dot MoneyPak processing available
U - Green Dot MoneyPak processing is unavailable
ACSUrl The fully qualified URL to redirect the consumer to AN(2083) N
collect a MoneyPak Number in order to complete the
Green Dot MoneyPak transaction. Available if En-
rolled = Y.
Payload The encoded payment request. Available if En- AN(7000) N
rolled = Y.
Sample Message
0
75f986t76f6fd5h68f5d
eNpVUk1TwjAQ/SsM402nSUuKwSC/3gSoH5PL
Y
https://www.somewebsite.com/acs
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
12Processing the Response Message
Verify the payment can be processed by evaluating the Enrolled element on the cmpi_lookup re-
sponse message. In the event that the Enrolled element contains a Y 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 popu-
lated with the values returned on the cmpi_lookup response message.
Note: The form field names are case sensitive.
Form Field Descriptions
Field Name Description Field Required
Definition
ACSUrl The fully qualified URL to redirect the consumer to AN(2083) Y
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.
PaReq The encoded authentication or payment request. AN(7000) Y
Value should be retrieved from the cmpi_lookup re-
sponse message and inserted into the form.
TermUrl The fully qualified URL of the Merchant webpage AN(2083) Y
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.
MD Merchant session tracking identifier. The value will AN(1024) Y
be returned to the TermUrl when the consumer is re-
turned 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.
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
135.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 return-
ing 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 Y, indic-
ating 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.
5.2.1 cmpi_authenticate
Second message of the Lookup/Authenticate pair used in processing the Green Dot MoneyPak trans-
action.
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 Required
Definition
MsgType cmpi_authenticate AN(50) Y
Version Application message version identifier. "1.7" AN(3) Y
ProcessorId Merchant processor identification code. This value is AN(20) Y
assigned to the Merchant.
MerchantId Merchant identification code. This value is assigned AN(50) Y
to the Merchant.
TransactionType Identifies the Transaction Type used for processing. AN(2) Y
GD - Green Dot MoneyPak
TransactionPwd A password to secure and verify the transaction ori- AN(50) Y
ginated from merchant represented by the transaction
details. The password value is configured through the
merchant profile.
PAResPayload PARes generated by the external system that pro- AN(10000) Y
cessed the payment or authentication with the con-
sumer.
Sample Message
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
141.7
cmpi_authenticate
100
123456
W
Passw0rd
7fDSaySnCmDGCjPglzqX
********* Payload Message *********
Response Message
This message is generated in response to the cmpi_authenticate request message.
Field Name Description Field Required
Definition
ErrorDesc Application error description for the associated error AN(500) Y
number.
ErrorNo Application error number. A non-zero value repres- AN(500) Y
ents the error encountered while attempting the pro-
cess the message request.
PAResStatus Transaction status result identifier. AN(2) Y
P - Pending Transaction
X - Canceled Transaction
E - Error Processing Transaction
SignatureVerification Transaction Signature status identifier. AN(2) Y
Y - 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 N(16) Y
identify the Green Dot MoneyPak order within the
Centinel system.
Sample Message
0
Y
P
4563218654876248
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
155.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 Con-
sumer's MoneyPak to the Merchant. More than one authorization transaction can be processed against
an original Green Dot MoneyPak transaction.
5.3.1 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 suc-
cessfully.
Request Message
Field Name Description Field Required
Definition
MsgType cmpi_authorize AN(50) Y
Version Application message version identifier. "1.7" AN(3) Y
ProcessorId Merchant processor identification code. This value is AN(20) Y
assigned to the Merchant.
MerchantId Merchant identification code. This value is assigned AN(50) Y
to the Merchant.
TransactionPwd A password to secure and verify the transaction ori- AN(50) Y
ginated from merchant represented by the transaction
details. The password value is configured through the
merchant profile.
TransactionType Identifies the Transaction Type used for processing. [ AN(2) Y
GD ]
GD Green Dot MoneyPak
OrderId Centinel generated order identifier. N(16) N
TransactionId Centinel generated transaction identifier. AN(20) N
Amount Unformatted transaction amount without any decim- N(20) Y
alization.
For example, $100.00 = 10000, $123.67 = 12367,
$.99 = 99
CurrencyCode 3 digit numeric, ISO 4217 currency code for the sale N(3) Y
amount.
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
16Green Dot MoneyPak Supported Currency Codes
840 - U.S. Dollar
Description Brief description of items purchased, limited to 125 AN(125) N
characters.
Sample Message
cmpi_authorize
1.7
100
123456
Passw0rd
GD
7fDSaySnCmDGCjPglzqX
34920
840
Goods Shipped to Consumer
Response Message
This message is generated in response to the cmpi_authorize message.
Field Name Description Field Required
Definition
ErrorNo Application error number. A non-zero value repres- AN(500) Y
ents the error encountered while attempting the pro-
cess the message request.
ErrorDesc Application error description for the associated error AN(500) Y
number.
StatusCode Status Result of the transaction. AN(2) Y
Y Transaction successful
E Transaction resulted in Error
TransactionId Centinel generated transaction identifier. AN(20) Y
Sample Message
0
Y
7fDSaySnCmDGCjPglzqX
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-
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
17thorization transaction.
5.4.1 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 trans-
ferred 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 success-
fully.
Request Message
Field Name Description Field Required
Definition
MsgType cmpi_capture AN(50) Y
Version Application message version identifier. "1.7" AN(3) Y
ProcessorId Merchant processor identification code. This value is AN(20) Y
assigned to the Merchant.
MerchantId Merchant identification code. This value is assigned AN(50) Y
to the Merchant.
TransactionPwd A password to secure and verify the transaction ori- AN(50) Y
ginated from merchant represented by the transaction
details. The password value is configured through the
merchant profile.
TransactionType Identifies the Transaction Type used for processing. [ AN(2) Y
GD ]
GD Green Dot MoneyPak
OrderId Centinel generated order identifier. N(16) N
TransactionId Centinel generated transaction identifier. AN(20) N
Amount Unformatted transaction amount without any decim- N(20) Y
alization.
For example, $100.00 = 10000, $123.67 = 12367,
$.99 = 99
CurrencyCode 3 digit numeric, ISO 4217 currency code for the sale N(3) Y
amount.
Green Dot MoneyPak Supported Currency Codes
840 - U.S. Dollar
Description Brief description of items purchased, limited to 125 AN(125) N
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
18characters.
Sample Message
cmpi_capture
1.7
100
123456
Passw0rd
GD
7fDSaySnCmDGCjPglzqX
34920
840
Goods Shipped to Consumer
Response Message
This message is generated in response to the cmpi_capture message.
Field Name Description Field Required
Definition
ErrorNo Application error number. A non-zero value repres- AN(500) Y
ents the error encountered while attempting the pro-
cess the message request.
ErrorDesc Application error description for the associated error AN(500) Y
number.
StatusCode Status Result of the transaction. AN(2) Y
Y Transaction successful
E Transaction resulted in Error
TransactionId Centinel generated transaction identifier. AN(20) Y
Sample Message
0
Y
7fDSaySnCmDGCjPglzqX
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.
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
195.5.1 cmpi_sale
The cmpi_sale message is used to settle a previously created Green Dot MoneyPak transaction. Dur-
ing processing of the sale message, funds are transferred from the consumer's MoneyPak to the mer-
chant.
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 success-
fully.
Request Message
Field Name Description Field Required
Definition
MsgType cmpi_sale AN(50) Y
Version Application message version identifier. "1.7" AN(3) Y
ProcessorId Merchant processor identification code. This value is AN(20) Y
assigned to the Merchant.
MerchantId Merchant identification code. This value is assigned AN(50) Y
to the Merchant.
TransactionPwd A password to secure and verify the transaction ori- AN(50) Y
ginated from merchant represented by the transaction
details. The password value is configured through the
merchant profile.
TransactionType Identifies the Transaction Type used for processing. [ AN(2) Y
GD ]
GD Green Dot MoneyPak
OrderId Centinel generated order identifier. N(16) N
TransactionId Centinel generated transaction identifier. AN(20) N
Amount Unformatted transaction amount without any decim- N(20) Y
alization.
For example, $100.00 = 10000, $123.67 = 12367,
$.99 = 99
CurrencyCode 3 digit numeric, ISO 4217 currency code for the sale N(3) Y
amount.
Green Dot MoneyPak Supported Currency Codes
840 - U.S. Dollar
Description Brief description of items purchased, limited to 125 AN(125) N
characters.
Sample Message
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
20cmpi_sale
1.7
100
123456
Passw0rd
GD
7fDSaySnCmDGCjPglzqX
34920
840
Goods Shipped to Consumer
Response Message
This message is generated in response to the cmpi_sale message.
Field Name Description Field Required
Definition
ErrorNo Application error number. A non-zero value repres- AN(500) Y
ents the error encountered while attempting the pro-
cess the message request.
ErrorDesc Application error description for the associated error AN(500) Y
number.
StatusCode Status Result of the transaction. AN(2) Y
Y Transaction successful
E Transaction resulted in Error
TransactionId Centinel generated transaction identifier. AN(20) Y
Sample Message
0
Y
7fDSaySnCmDGCjPglzqX
5.6 Refund Message Integration
The Refund message (cmpi_refund) is responsible for crediting the consumer some portion of the ori-
ginal settlement amount. Multiple refunds can be processed against the original Green Dot MoneyPak
transaction.
5.6.1 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.
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
21Either 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 success-
fully.
Request Message
Field Name Description Field Required
Definition
MsgType cmpi_refund AN(50) Y
Version Application message version identifier. "1.7" AN(3) Y
ProcessorId Merchant processor identification code. This value is AN(20) Y
assigned to the Merchant.
MerchantId Merchant identification code. This value is assigned AN(50) Y
to the Merchant.
TransactionPwd A password to secure and verify the transaction ori- AN(50) Y
ginated from merchant represented by the transaction
details. The password value is configured through the
merchant profile.
TransactionType Identifies the Transaction Type used for processing. [ AN(2) Y
GD ]
GD Green Dot MoneyPak
OrderId Centinel generated order identifier. N(16) N
TransactionId Centinel generated transaction identifier. AN(20) N
Amount Unformatted transaction amount without any decim- N(20) Y
alization.
For example, $100.00 = 10000, $123.67 = 12367,
$.99 = 99
CurrencyCode 3 digit numeric, ISO 4217 currency code for the sale N(3) Y
amount.
Green Dot MoneyPak Supported Currency Codes
840 - U.S. Dollar
Description Brief description of items purchased, limited to 125 AN(125) N
characters.
Sample Message
cmpi_refund
1.7
100
123456
Passw0rd
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
22GD
7fDSaySnCmDGCjPglzqX
34920
840
Goods Shipped to Consumer
Response Message
This message is generated in response to the cmpi_refund message.
Field Name Description Field Required
Definition
ErrorNo Application error number. A non-zero value repres- AN(500) Y
ents the error encountered while attempting the pro-
cess the message request.
ErrorDesc Application error description for the associated error AN(500) Y
number.
StatusCode Status Result of the transaction. AN(2) Y
Y Transaction successful
E Transaction resulted in Error
TransactionId Centinel generated transaction identifier. AN(20) Y
Sample Message
0
Y
7fDSaySnCmDGCjPglzqX
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
236 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 transac- tion. Please refer to the Green Dot MoneyPak Integration materials for additional information. Thin Client Integration Guide - Green Dot MoneyPak (Revision 01) 24
7 Integration Configuration
To support integration testing the Centinel Test system (https://centineltest.cardinalcommerce.com) 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
(https://centineltest.cardinalcommerce.com) and login to your test Merchant account.
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
25Step 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 Initiat- ive Configuration Select Green Dot MoneyPak from the dropdown box and click the enter button. Note that if your pro- file 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. Thin Client Integration Guide - Green Dot MoneyPak (Revision 01) 26
The Green Dot MoneyPak configuration requires the following information.
Configuration Description
Green Dot MoneyPak Partner Id Green Dot provided partner identifier.
Green Dot MoneyPak Settle- Group name provided by Green Dot that is used during settlement.
ment Group
Green Dot MoneyPak Payment Green Dot provided code that identifies the type of payment that is being
Type Code made.
Merchant Display Name The name that will be displayed to the Consumer on the MoneyPak Num-
ber collection form.
Merchant Address1 Business address that will be displayed to the Consumer on the MoneyPak
Number collection form.
Merchant Address2 Business address that will be displayed to the Consumer on the MoneyPak
Number collection form.
Merchnat City Business city that will be displayed to the Consumer on the MoneyPak
Number collection form.
Merchant State Business state that will be displayed to the Consumer on the MoneyPak
Number collection form.
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
27Merchant Country Business country that will be displayed to the Consumer on the MoneyPak
Number collection form.
Merchant Postal Code Business postal code that will be displayed to the Consumer on the
MoneyPak Number collection form.
Merchant Phone 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 Email Ad- Merchant support email address that will be displayed to the Consumer on
dress the MoneyPak Number collection form. Consumers should be able to use
this email 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.
Your username and password for your production account are provided to you through the registration
Welcome Pack email. Please contact Cardinal Merchant support if you have any difficulties accessing
your account.
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
28Step 2 - Configure your Merchant Profile for Green Dot MoneyPak.
The Centinel platform requires specific configuration settings to enable the Green Dot MoneyPak pay-
ment processing. Once you are logged into the Production Centinel website, Click thru the following :
Manage Profile > Manage Payment Initiative Configuration > Create Payment Initiat-
ive Configuration
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
29Select Green Dot MoneyPak from the dropdown box and click the enter button. Note that if your pro- file 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. Thin Client Integration Guide - Green Dot MoneyPak (Revision 01) 30
The Green Dot MoneyPak configuration requires the following information.
Configuration Description
Green Dot MoneyPak Partner Id Green Dot provided partner identifier.
Green Dot MoneyPak Settle- Group name provided by Green Dot that is used during settlement.
ment Group
Green Dot MoneyPak Payment Green Dot provided code that identifies the type of payment that is being
Type Code made.
Merchant Display Name The name that will be displayed to the Consumer on the MoneyPak Num-
ber collection form.
Merchant Address1 Business address that will be displayed to the Consumer on the MoneyPak
Number collection form.
Merchant Address2 Business address that will be displayed to the Consumer on the MoneyPak
Number collection form.
Merchnat City Business city that will be displayed to the Consumer on the MoneyPak
Number collection form.
Merchant State Business state that will be displayed to the Consumer on the MoneyPak
Number collection form.
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
31Merchant Country Business country that will be displayed to the Consumer on the MoneyPak
Number collection form.
Merchant Postal Code Business postal code that will be displayed to the Consumer on the
MoneyPak Number collection form.
Merchant Phone 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 Email Ad- Merchant support email address that will be displayed to the Consumer on
dress the MoneyPak Number collection form. Consumers should be able to use
this email address to contact the merchant's customer service department.
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
328 Integration Testing
Testing is critical to successful implementations. It is important that all the positive and negative re-
sponse 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 sys-
tems, 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 pre-
defined 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 sec-
tion.
Note: Centinel Test Transaction URL : https://centineltest.cardinalcommerce.com/maps/txns.asp
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 mak-
ing 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 Description Messages Merchant Action
1
BillingFirst- Consumer places order cmpi_lookup response Display order confirma-
Name = with Green Dot ErrorNo = 0 tion status message to the
Test1 MoneyPak as method of ErrorDesc = consumer. Ship the
payment. The consumer Enrolled = Y goods to the consumer
enters a valid MoneyPak Payload= when the cmpi_sale re-
Number on the collection ACSUrl = sponse results in a suc-
form and the transaction TransactionId = cess.
is created. The transac-
tion is successfully cmpi_authenticate response
settled by the merchant. PAResStatus = P
SignatureVerification = Y
ErrorNo = 0
ErrorDesc =
OrderId =
cmpi_sale response
StatusCode = Y
ErrorNo = 0
ErrorDesc =
TransactionId =
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
33Test Case Description Messages Merchant Action
2
BillingFirst- Consumer places order cmpi_lookup response Display order confirma-
Name = with Green Dot ErrorNo = 0 tion status message to the
Test2 MoneyPak as method of ErrorDesc = consumer. Ship the
payment. The consumer Enrolled = Y goods to the consumer
enters multiple valid pins Payload= when the cmpi_sale re-
on the collection form in ACSUrl = sponse results in a suc-
order to complete the TransactionId = cess.
transaction. The transac-
tion is successfully cmpi_authenticate response
settled by the merchant. PAResStatus = P
SignatureVerification = Y
ErrorNo = 0
ErrorDesc =
OrderId =
cmpi_sale response
StatusCode = Y
ErrorNo = 0
ErrorDesc =
TransactionId =
Test Case Description Messages Merchant Action
3
BillingFirst- Green Dot MoneyPak cmpi_lookup response Display message indicat-
Name = payments are currently ErrorNo = 0 ing that Green Dot
Test3 unavailable. ErrorDesc = MoneyPak is currently
Enrolled = U unavailable for payment
Payload= processing. Prompt the
ACSUrl = consumer for another
TransactionId = form of payment to com-
plete the purchase.
Test Case Description Messages Merchant Action
4
BillingFirst- An error was en- cmpi_lookup response Display message indicat-
Name = countered processing the ErrorNo = ing that Green Dot
Test4 cmpi_lookup message. ErrorDesc = MoneyPak is currently
Enrolled = U unavailable for payment
Payload= processing. Prompt the
ACSUrl = consumer for another
TransactionId = form of payment to com-
plete the purchase.
Test Case Description Messages Merchant Action
5
BillingFirst- Consumer places order cmpi_lookup response Display a message to the
Name = with Green Dot ErrorNo = 0 consumer indicating that
Test5 MoneyPak as method of ErrorDesc = the payment was unable
payment, however, the Enrolled = Y to complete and prompt
authenticate message res- Payload= for another form of pay-
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
34ACSUrl =
ults in an error. ment to complete the
TransactionId =
purchase.
cmpi_authenticate response
PAResStatus = E
SignatureVerification = Y
ErrorNo =
ErrorDesc =
Test Case Description Messages Merchant Action
6
BillingFirst- Consumer places order cmpi_lookup response Display a message to the
Name = with Green Dot ErrorNo = 0 consumer indicating that
Test6 MoneyPak as method of ErrorDesc = the payment was unable
payment. The consumer Enrolled = Y to complete and prompt
enters a valid MoneyPak Payload= for another form of pay-
Number on the collection ACSUrl = ment to complete the
form, however, an error TransactionId = purchase.
is encountered pro-
cessing the cmpi_sale cmpi_authenticate response
message. PAResStatus = P
SignatureVerification = Y
ErrorNo = 0
ErrorDesc =
OrderId =
cmpi_sale response
StatusCode = E
ErrorNo =
ErrorDesc =
TransactionId =
Test Case Description Messages Merchant Action
7
BillingFirst- Consumer places order cmpi_lookup response Display order confirma-
Name = with Green Dot ErrorNo = 0 tion status message to the
Test7 MoneyPak as method of ErrorDesc = consumer. Ship the
payment. The consumer Enrolled = Y goods to the consumer
enters a valid MoneyPak Payload= because the authorize re-
Number on the collection ACSUrl = sponse resulted in a suc-
form and the authorize TransactionId = cess and the funds have
results in a success to been transferred from the
transfer funds from the cmpi_authenticate response MoneyPak Number. Re-
MoneyPak Number, PAResStatus = P view the error codes
however, the capture res- SignatureVerification = Y from the capture re-
ults in an error. ErrorNo = 0 sponse and resubmit the
ErrorDesc = transaction if necessary.
OrderId =
cmpi_authorize response
StatusCode = Y
ErrorNo = 0
ErrorDesc =
TransactionId =
cmpi_capture response
StatusCode = E
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
35ErrorNo =
ErrorDesc =
TransactionId =
Test Case Description Messages Merchant Action
8
BillingFirst- Consumer places order cmpi_lookup response Review the error codes
Name = with Green Dot ErrorNo = 0 returned from the refund
Test8 MoneyPak as method of ErrorDesc = response, and resubmit
payment. The consumer Enrolled = Y the transaction if needed.
enters a valid MoneyPak Payload=
Number on the collection ACSUrl =
form and the transaction TransactionId =
is created. The transac-
tion is successfully cmpi_authenticate response
settled by the merchant, PAResStatus = P
however, and error oc- SignatureVerification = Y
curs when the transaction ErrorNo = 0
is attempted to be refun- ErrorDesc =
ded. OrderId =
cmpi_sale response
StatusCode = Y
ErrorNo = 0
ErrorDesc =
TransactionId =
cmpi_refund response
StatusCode = E
ErrorNo =
ErrorDesc =
TransactionId =
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
369 Moving To Production
Once the integration testing is complete and you are ready to go live with Green Dot MoneyPak pay-
ments, the same configurations defined within the Centinel Test system must be configured within the
production Centinel platform. In addition to the configuration information, it is important to use the
implementation checklist in section 3 to verify that all implementation tasks are complete.
The final step before releasing Green Dot MoneyPak as a payment option on your Merchant website is
to run a Live Transaction Test. To perform this test, make a purchase on the Merchant website using
the Green Dot MoneyPak payment option. Ensure that all steps necessary to carrying out a successful
Green Dot MoneyPak transaction are performed.
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
3710 Integration Error Handling
The following list of Centinel MAPS error codes, descriptions and explanations are provided to assist
merchants with error code handling during integration. When an error is returned by the cmpi_lookup
or cmpi_authenticate messages, the simplest approach is to retry the authentication process. If an error
is received on the cmpi_authenticate, the cmpi_authenticate should not be resubmitted. The entire au-
thentication must be retried starting with a new cmpi_lookup message being sent. For those merchants
integrating with a more enhanced error handling model, all error codes are provided with a suggested
merchant action. It is possible for multiple error codes to be returned. These will be in a comma-sep-
arated form, and merchant decisions only need to be based on the first error code in the list.
10.1 Common Centinel MAPS Errors
Error Code Error Description Explanation Merchant Action
2001 Unsupported Message Type The MsgType element value Complete transaction
within the message does not without authentication, con-
meet the API requirements. tact technical support.
2003 Internal Error: Unable to The message could not be Complete transaction
handle message type at this handled properly by the without authentication, con-
time Centinel MAPS server. This tact technical support
error only occurs when the
Centinel MAPS Server has
not been configured prop-
erly.
2006 Unsupported Message Ver- The Version element value Complete transaction
sion within the message does not without authentication,
meet the API requirements. check message values.
The value specified in Ver-
sion is either not recognized
or not supported.
2007 Message Group Disabled Transaction messages have Complete transaction
been disabled. If they should without authentication, con-
be enabled, contact technical tact technical support.
support.
2009 Invalid Request Format: In- Transaction message was not Complete transaction
valid XML valid XML. without authentication,
check message values.
2010 Invalid Request Format: Transaction message was Complete transaction
Empty Request empty. without authentication,
check message values.
10.2 cmpi_lookup
Error Code Error Description Explanation Merchant Action
Thin Client Integration Guide - Green Dot MoneyPak (Revision 01)
38You can also read
