MPI Class

Properties   Methods   Events   Configuration Settings   Errors  

The MPI class is used to implement a 3-D Secure 1.0.2 MPI (Merchant Plug-In).

Class Name

IPWorks3DS_MPI

Procedural Interface

 ipworks3ds_mpi_open();
 ipworks3ds_mpi_close($res);
 ipworks3ds_mpi_register_callback($res, $id, $function);
 ipworks3ds_mpi_get_last_error($res);
 ipworks3ds_mpi_get_last_error_code($res);
 ipworks3ds_mpi_set($res, $id, $index, $value);
 ipworks3ds_mpi_get($res, $id, $index);
 ipworks3ds_mpi_do_checkauthenticationresponse($res, $responsedata);
 ipworks3ds_mpi_do_config($res, $configurationstring);
 ipworks3ds_mpi_do_getauthenticationpacket($res);
 ipworks3ds_mpi_do_getresponsevar($res, $name);
 ipworks3ds_mpi_do_interrupt($res);
 ipworks3ds_mpi_do_requestcardranges($res);
 ipworks3ds_mpi_do_reset($res);
 ipworks3ds_mpi_do_verifyenrollment($res);

Remarks

This class is based on the 3-D Secure 1.0.2 specification, and simplifies the creation and handling of all messages to and from 3-D Secure Compliant Directory and Access Control servers. This is accomplished by adding an additional layer of abstraction between the developer and the 3-D Secure protocol. There is no need to deal with raw sockets, SSL handshakes, or XML packet formatting. All SSL communications to and from the Directory and Access Control servers are handled by the class.

This class can be easily integrated with an online payment system or shopping cart. There are three steps to integrating this class with an existing online payment system or shopping cart.

For help getting started and Visa Product Integration Testing (PIT) please see the following tutorials:

Before making any transactions the following properties must be set with values acquired from Visa:

Card Range Request (CRReq)

The class allows you to query the Directory Server for credit card ranges enrolled in the 3-D Secure program. This step is optional. If a submitted card is not within the currently retrieved ranges, then the card is not enrolled in 3-D Secure. Once the above configuration properties are set, sending a Card Range Request is simple. Set the MessageId (each message requires a unique MessageId), and then call the method RequestCardRanges. The card ranges will be returned in the properties CardRangeBegin, CardRangeEnd, and CardRangeAction. After a successful Card Range Request the SerialNumber property will contain a serial number which indicates to the Directory Server the current state of your local cache. When submitting another Card Range Request, only the ranges which have changed since the last SerialNumber will be returned.

Verify Enrollment Request (VEReq)

Even if a card number is included in the ranges returned in the previous step, there is no guarantee that this card is actually enrolled in 3-D Secure. To determine if a card number is actually enrolled in the program, you must send a Verify Enrollment Request (VEReq). Update the MessageId and then set the CardNumber. Now call the VerifyEnrollment method. If the CardNumber is enrolled , the CardEnrolled property will contain "Y" (Yes). Otherwise it will contain "N" (No) or "U" (Service Unavailable). In addition, the ACSURL property will contain the URL for the Access Control Server to which a Payer Authentication Request must be sent.

Payer Authentication Request (PAReq)

After determining that the CardNumber in question is enrolled, a Payer Authentication Request (PAReq) must be sent to the ACSURL that was returned in the previous step. This request must be sent through the cardholder's browser, and thus cannot be sent by the class itself. The GetAuthenticationPacket method will return the compressed Payer Authentication Request (PAReq) packet, which can then be submitted through the cardholder's browser using the Javascript below.

The TermUrl is the location of a page that will handle the rest of the ordering process. The Visa Access Control Server will post back to the URL entered in this field with the results of the Payer Authentication Request. The MD field should contain any additional information needed by the merchant to complete the transaction. This may include information such as a TransactionId, MessageId, or any other data needed to match the response with a pending authentication. This may be raw text, XML, or any other data type. It is not recommended that sensitive data such as a CardNumber be contained in this field. If this is unavoidable, such sensitive data must be encrypted.

Once a Payer Authentication Response (PARes) is received by the web page indicated in the TermUrl field, use the CheckAuthenticationResponse to decompress, verify, and parse the response. The result of the transaction will be contained in the AuthenticationStatus property. The Payer Authentication Response is digitally signed by the Access Control Server, and the certificate used to sign the response will be contained in the AuthenticationCertificate property. If this certificate does not match the RootCertificate the authentication fails and the class will throw an error. Likewise, if the information in the Payer Authentication Response does not exactly match that given in the original Authentication Request the class will throw an error. The properties that must be identical include MerchantBankId, MerchantNumber, TransactionId, TransactionAmount, CurrencyCode, and CurrencyExponent.

In addition to the previously set Merchant Properties, the following fields are required to validate a Payer Authentication Response packet: