Introduction

Documentation for the available operations at the Cardlink gateway can be found here. This gateway allows create card charges only in EUR currency.

3D Secure 2

The implementation using the PSD2 standard (The 3D Secure version 2) according to European standards.

The process for 3D Secure version 2 allows the “frictionless authentication”, So on some charges, no user authentication is required to accept the payment. If authentication is required, the authentication form will be displayed without redirecting to your card issuer.

The complete steps for the 3D Secure version 2 integration are as follows:

Card tokenization

Definition

POST /v1/{MERCHANT_ID}/tokens

Sample request

{
   "card_number":"37075510000002",
   "holder_name":"test",
   "expiration_year":"20",
   "expiration_month":"12",
   "cvv2":"1234",
   "address":{
      "line1":"Required",
      "line2":"Optional",
      "line3":"Optional",
      "postal_code":"Required",
      "city":"Required",
      "state":"Required",
      "country_code":"Required"
   }
}

Response example

{
   "id":"kknwbnfka9xy8u5yp05d",
   "card":{
      "card_number":"370755XXXX0002",
      "holder_name":"test",
      "expiration_year":"20",
      "expiration_month":"12",
      "address":{
         "line1":"Av 5 de Febrero",
         "line2":"Roble 207",
         "line3":"col carrillo",
         "state":"Queretaro",
         "city":"Queretaro",
         "postal_code":"76900",
         "country_code":"MX"
      },
      "creation_date":null,
      "brand":"visa"
   }
}

The card tokenization does not change compared to a regular card charge.

A token must be created directly from the website after the user enters their card information, using JavaScript to send this information to Openpay. This prevents the card data from being transmitted to your back-end servers.

In order to create a token, you can use the JavaScript library provided by Openpay (Openpay.js), or you can implement your own JavaScript using the API definition found at the general API documentation.

Charge with 3D Secure

Example request

{
    "source_id": "kknwbnfka9xy8u5yp05d",
    "method": "card",
    "amount": 100,
    "currency": "EUR",
    "description": "Credit Card Charge with 3DS2",
    "order_id": "2RARVJ-1518431",
    "customer": {
        "name": "Juan",
        "last_name": "Perez",
        "phone_number": "11111111",
        "email": "juan.perez@example.com"
    },
    "affiliation": {
        "name": "ALP_WEB"
    },
    "redirect_url": "http://www.example.com/bookingresult",
    "use_3d_secure": "true"
}

Example response

{
    "id": "trqqmnm74csv2krixjbj",
    "authorization": null,
    "operation_type": "in",
    "transaction_type": "charge",
    "card": {
        "type": "credit",
        "brand": "american_express",
        "address": {
            "line1":"Av 5 de Febrero",
            "line2":"Roble 207",
            "line3":"col carrillo",
            "state":"Queretaro",
            "city":"Queretaro",
            "postal_code":"76900",
            "country_code":"MX"
        },
        "card_number": "370755XXXX0002",
        "holder_name": "test",
        "expiration_year": "20",
        "expiration_month": "12",
        "allows_charges": true,
        "allows_payouts": false,
        "bank_name": null,
        "bank_code": "000"
    },
    "status": "charge_pending",
    "conciliated": true,
    "creation_date": "2020-04-15T17:46:10-05:00",
    "operation_date": "2020-04-15T17:46:10-05:00",
    "description": "Credit Card Charge with 3DS2",
    "error_message": null,
    "order_id": "2RARVJ-1518431",
    "method": "card",
    "amount": 100,
    "currency": "EUR",
    "payment_method": {
        "type": "redirect",
        "url": "https://sandbox-api.openpay.mx/v1/mlvlvqvhaqxxwlutqgij/charges/trqqmnm74csv2krixjbj/redirect/"
    },
    "customer": {
        "name": "Juan",
        "last_name": "Perez",
        "phone_number": "11111111",
        "email": "juan.perez@example.com",
        "address": null,
        "creation_date": "2020-04-15T17:46:10-05:00",
        "external_id": null,
        "clabe": null
    },
    "fee": {
        "amount": 0.02,
        "tax": 0,
        "currency": "USD"
    }
}

In order to use 3D Secure version 1 or 2, two additional parameters must be sent in the request:

Property Description
use_3d_secure boolean (required)
Value indicating that the charge must be 3D Secure. Send as true
redirect_url string (required)
URL to where the user should be redirected to after 3D Secure process is finished.

 Redirecting the User

After receiving the response, if the transaction was received with a status of charge_pending, the merchant must retrieve the URL contained in the field payment_method.url, and redirect the customer to this URL. From then on, Openpay will handle the process to call the Alpha Bank API for 3D Secure and authorization.

Retrieving the transaction status

After the user finishes the 3D Secure process, if successful, Openpay will send the authorization request to Alpha Bank. Once the result is received and the transaction updated accordingly, the user will be redirected to the URL received in the field redirect_url sent in the original charge request. The parameter id will be added to this URL, containing the value of the transaction ID.

The merchant must then use this ID to retrieve the current transaction status from Openpay. For this the API to get a charge can be used. The response to this API will be the transaction object as is usually returned during a direct charge.

Testing values

For testing Worldpay integration, please use the following values:

Card Holdername Expiration CVV2 Result
37075510000002 test 12/20 1234 Success
4012000000012011012 test 12/20 123 Fail

Confirmation Webhook

Once that a payment is completed or failed, Openpay sends a notification to the Merchant’s configured webhook.