Applies to API Package: Equity Crowdfunding Portals (v3.0+)

This article provides a quick reference on how to create Card Tokens to enable Card Payments with Fabrick Platform Solution for Equity Crowdfunding Portals provided by Banca Sella and Axerve.

The intended reader for the following contents is a CTO or a developer working to integrate the Equity Crowdfunding Portal backend.

The following sections assume that you have successfully onboarded on Fabrick Platform and have subscribed at least the following API packages:

• Equity Crowdfunding Portals (v3.0+)
• Axerve eCommerce Solution - Payments

You will also need the following data in order to successfully create Card Tokens for the Investors of your Equity Crowdfunding Portal:

• Your portalId: the identification code of your portal that must be used to interact with the Equity Crowdfunding Portals solution. This has been released by Fabrick after the activation of the Equity Crowdfunding Portals solution, and looks like the following: PRTWNP603529756.
• Your merchantId: the identification code of your portal that must be used to interact with the Axerve eCommerce Solution. This has been released by Axerve after the activation of the your Gestpay account, and looks like the following: 9091234. Please note that you must have two distinct merchantId codes (one to be used for Token creation and one to be used for Payment creation).

We also assume that you have already created an Investor on your Equity Crowdfunding Portal.

Creating Card Tokens for Investors

Each Investor on your Equity Crowdfunding Portal may be associated with one or more Card Tokens, in order to enable faster payments and a better user experience. The idea is the same with respect to what can be found in many online marketplaces, where each user may register one or more payment methods to enable 1-click shop, for example.

Since you may not want to directly handle your investor's card PAN (this would require full compliance to PCI-DSS standards), you must create a Token for each Card that your Investor may want to use as payment method for his Orders.

To successfully create the Card Token, you are required to process an authorization transaction on the Card of your Investor. The authorization transaction will actually request the authentication and authorization from your Investor (for example, the 3DS code) but will not charge any money, since, once authorized, it will be automatically deleted on the following day by Axerve eCommerce Solution as default.

The following API calls refer to the endpoints of the Axerve eCommerce Solution - Payments API package.

Step 1. Create the Authorization Transaction

The Authorization Transaction is created by invoking the POST Create Payment endpoint. Please pay attention to use the correct merchantId code enabled for token creation for the following calls.

Typically, an Authorization Transaction is a symbolic transaction that is created just to let the cardholder to perform the authorization steps. So you should create a transaction with a symbolic amount of - for example - 1€ cent.

The input body should look like the following:

{
  "buyer": {
    "name": "John Doe",
    "email": "john.doe@myemail.com",
    "preferredLanguageId": "EN"
  },
  "amount": 0.01,
  "currency": "EUR",
  "tokenTemplate": "MASKEDPAN"
}

The field tokenTemplate is important, since it is the "switch" that let you to actually request the Token creation. You may provide different values to that field:

• MASKEDPAN if you just want a Token that resembles a card PAN. This is the most used setting.
• otherwise, you may provide a custom string if you want to customize the pattern used to generate the token. If so, the string must satisfy the following requirements: min length 10 chars/digits; max length 25 chars/digits; in any case, it must contain max 8 digits.

The response will look like the following:

{
  "paymentId": "21548546985",
  "paymentToken": "0bf2598e-54f3-465d-bd77-aa43949f4c5a",
  "buyer": {
    "name": "John Doe",
    "email": "john.doe@myemail.com",
    "preferredLanguageId": "EN"
  },
  "amount": 0.01,
  "currency": "EUR",
  "tokenTemplate": "MASKEDPAN"
}

Step 2. Authorize the transaction

The Authorization Transaction should be authorized by the investor. In order to perform this step, you are required to integrate Axerve Lightbox solution to avoid PCI-DSS requirements.

The Axerve Lightbox should be integrated in the frontend pages of your website by including the following JavaScript source:

SANDBOX:
https://sandbox.gestpay.net/pagam/javascript/axerve.js

LIVE:
https://ecomm.sella.it/pagam/javascript/axerve.js

Once included the source, you should initialize the Lightbox with the following parameters:

axerve.lightBox.shop = <merchantId>;
axerve.lightBox.open(<paymentId>, <paymentToken>, callback);

Using as merchantId your merchant identification code for token creation, and the paymentId and paymentToken parameters as obtained by the preceeding POST Create Payment.

The lightbox page will show up, asking the customer for credit card information. In the sandbox environment, you can use one of Axerve's test credit cards.

The callback object is a function that allows you to handle the result of the authentication. When the authorization is completed, the callback function is called with a response object as argument, like the following:

{ 
  paymentId: "21548546985",  
  status: "OK",
  error: { 
    code: null,
    description: null
  }
}

Based on the status field value, you can inform your investor of having concluded successfully (or not) the registration of the card.

Step 3. Retrieving the Card Token

After having successfully concluded the authentication, the last step is to retrieve the Card Token. You should invoke the GET Payment endpoint using the correct merchantId and paymentId values in order to retrieve all the payment details.

The response body will be like the following:

{
  "paymentId": "21548546985",
  "bankPaymentCode": "54326",
  "authorizationCode": "42153285",
  "statusInfo": {
    "status": "APPROVED",
    "code": "0",
    "description": "Transazione correttamente effettuata"
  },
  "buyer": {
    "name": "John Doe",
    "email": "john.doe@myemail.com"
  },
  "tokenInfo": {
    "token": "541238MYTOKEN123",
    "expiryMonth": "04",
    "expiryYear": "27"
  },
  "events": [
    {
      "datetime": "2019-04-23T10:23:07",
      "type": "AUTHORIZATION",
      "amount": 0.01,
      "currency": "EUR"
    }
  ],
  "nextScheduledEvent": {
    "date": "2019-04-24",
    "type": "CANCELLATION",
    "amount": 0.01,
    "currency": "eur"
  },
  ...
}

The Card Token is contained in the tokenInfo object, together with other useful information that you should persist in your system like the expiration month and year of the token.

You are now ready to create Card Payments for your Equity Crowdfunding Portal orders, following this article: Accepting Card Payments on Equity Crowdfunding Campaigns