Payzone Documentation

3D Secure Check

3D Secure encompasses both Visa’s Verified by Visa and MasterCard’s SecureCode security solutions for online ecommerce transactions. These solutions use personal passwords to help protect cardholders’ card numbers against unauthorized use. Once activated, a card-holder’s card number cannot be used for online purchases without providing a personal password.

3D Secure Flow

The 3D Secure request above must be used together with a sale API transaction in the following order:

1 - The cardholder completes the payment page as usual.

2 - The payment page saves all information in session variables.

3 - The payment page makes an API call 3dscheck to Payzone.

4 - The payment page receives an ACSUrl provided by the issuing bank and redirects the cardholder towards this URL via an HTTP POST request. The following parameters must be provided to this URL:

The variable PaReq containing the value of PaReq received from the 3dscheck call.
The variable TermUrl containing the value of a return URL for 3DS handling on your server.
The variable MD containing a unique value for the order (like an order ID).

5 - The customer fills out his code on the bank URL.

6 - The bank URL redirects the customer towards the 3DS handling URL specified by the merchant (in TermUrl) via an HTTP POST request with the following parameters:

7 - The PaRes variable must then be used in a CCSale/CCAuthorize API call along with the saved session variables for the initial transaction (identified by the orderid).

Great care must be taken when saving payment information during the 3D Secure authentication process. All Credit Card data must never be stored or transmitted in clear.

Endpoints

HTTP Method	API URL	API Version
POST	https://api.payzone.ma/transaction/3dscheck/creditcard	>= 002

Accepted parameters

Field	Type	Max Length	Required	Description	Version
customerIP	String	40	yes	Customer request IP
amount	Integer	10	yes	Number in minor unit, e.g. cents; 100 dollar cent equals to 1 dollar
currency	String	3	yes	ISO-4217 currency codes
orderID	String	100	yes	Unique reference to current transaction request
cardNumber	String	40	yes	Credit card number
cardSecurityCode	String	4	no	CVV number from credit card	Could be mandatory with some acquirers
cardExpireMonth	String	2	yes	Month of the card expire: 09
cardExpireYear	String	4	yes	Year of the card expire ie: 2017
cardHolderEmail	String	100	no	Customer email

Code samples

Note: Gateway API transactions are done with a different library than payment-page API. See the code sample comments for more info:

   
    /*
    *   Transaction name is '3DSCheck', once you create a new transaction passing this as parameter, 
    *   you need to set the mandatory data using the follow methods:
    *    setTransactionInformation() 
    *    set3DSecureCardInformation()
    *    setShopperInformation()
    */

    $client = new GatewayClient();

    $transaction = $client->newTransaction('3DSCheck', 'testMerchant', 'testPassword');
    $transaction->setTransactionInformation(200, 'USD', 'order1456', '10.10.254.10');
    $transaction->set3DSecureCardInformation('4111111111111111', '10', '2014', 'test@mail.com');

    $response = $transaction->send();

    if ('000' === $response->errorCode) {
        $transactionID = $response->transactionID;
        $ACSUrl        = $response->ACSUrl;
        $PaReq         = $response->PaReq;
    } else {
        echo "Error {$response->errorCode} with message {$response->errorMessage}";
    }

   
    PaymentGatewayConnector connector = new PaymentGatewayConnector(API_URL, ORIGINATOR, PASSWORD);

    ThreeDSCheckResponse response = null;
    ThreeDSCheckRequest request = new ThreeDSCheckRequest();
    request.setOrderId("order1456");
    request.setCustomerIP("10.10.254.10");
    request.setAmount(200).setCurrency("USD");
    request.setCardHolderEmail("test@mail.com");

    request.setCardNumber("4111111111111111");
    request.setCardExpireMonth("10").setCardExpireYear("2014");

    try {
        response = connector.doThreeDSCheckTransaction(request);
    } catch (Exception e) {
        e.printStackTrace();
    }

    if (response != null) {
        if (TransactionResultCode.TRANSACTION_SUCCESSFULLY.equals(response.getErrorCode()) {
        System.out.println("Success: " + response.getErrorMessage());
        } else {
        System.out.println("Failure: " + response.getErrorMessage());
        }
    }

   
    const gateway = require("payxpert")("123456", "GreatP4ssw0rd").gateway;

    const body = {
        customerIP: "8.8.4.4",
        amount: 1500,
        currency: "EUR",
        orderID: "HELLO NODEJS",

        cardNumber: "4111111111111111",
        cardSecurityCode: "000",
        cardHolderName: "CARDHOLDER NAME",
        cardExpireMonth: "10",
        cardExpireYear: "2024"
    };

    const response = await gateway.check3dSecure(body);

    if (response.code == "000") {
        // Success

        console.log("3DS: check: data received");
        console.log("To open page you need to perform following post request:\n");
        console.log("curl -X POST \\\nhttps://api.payxpert.com/mpi/pareq/45956209 \\\n  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \\");
        console.log("  -F 'PaReq=" + Check3DSResponse.PaReq + "' \\");
        console.log("  -F TermUrl=https://www.your-server.com \\\n  -F MD=" + orderId3ds + "\n");
        console.log("You can copy CURL command line code, in Postman call File -> Import -> Paste RAW text and paste it there\n");
    }

   
    var client = new GatewayClient(OriginatorConfig.ORIGINATOR_ID, OriginatorConfig.ORIGINATOR_PASSWORD);

    var check3ds = client.New3DSCheckTransaction();
    check3ds.SetTransactionInformation(1000, "EUR", "Order123", customerIP);
    check3ds.SetCardInformation("4111111111111111", "000", "hello@dolly.com", "10", "2024");

    var Check3DSResponse = await check3ds.Send();

    if (Check3DSResponse.IsSuccessfull())
    {
        Console.WriteLine("3DS: check: data received");
        Console.WriteLine("To open page you need to perform following post request:\n");
        Console.WriteLine("curl -X POST \\\nhttps://api.payxpert.com/mpi/pareq/45956209 \\\n  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \\");
        Console.WriteLine("  -F 'PaReq=" + Check3DSResponse.PaReq + "' \\");
        Console.WriteLine("  -F TermUrl=https://www.your-server.com \\\n  -F MD=" + orderId3ds + "\n");
        Console.WriteLine("You can copy CURL command line code, in Postman call File -> Import -> Paste RAW text and paste it there\n");
    } else
    {
        Console.WriteLine("3DS: check: failure. Please check network connection");
    }

Response

The body of the response is in JSON format.

The following fields are present in the response :