Skip to main content

Card Only (iframe)

Introduction​

This visual component allows you to carry out a transaction in two parts. First, capture the card to generate a temporary token called request_id.

The second step is to use the API in server-to-server mode to execute any available transaction. In this documentation, you should use the fastpay parameter to retrieve the original information of the token and specify the operation to perform.

Card Capture​

With this integration method, you can securely capture the card and then perform any type of operation supported by the API. At no time will card data pass through your server, ensuring full PCI DSS compliance.

The merchant should include a JavaScript file on the website for the sandbox environment:

sandbox
<script
  type="text/javascript"
  src="https://sandbox.sipay.es/fpay/v1/static/bundle/fastpay.js"
></script>

And replace it with this for the production environment:

live
<script
  type="text/javascript"
  src="https://live.sipay.es/fpay/v1/static/bundle/fastpay.js"
></script>
tip

It is recommended to include the JavaScript file in the <head> tag.

Additionally, don’t forget to include the following statement in the <head> section of the page to scale the content and make it adaptable to different devices.

<meta name="viewport" content="width=device-width, initial-scale=1" />

To use the script, a button (class="fastpay-btn") should be created on the web. This button has some mandatory attributes:

  • data-key (string, required): API identifier provided by Sipay.
  • data-amount (string, required): Transaction amount in integer format, examples: data-amount="1025" would be 10.25 € (if currency = EUR), data-amount="5" would be 0.05€ (if currency = EUR).
  • data-currency: Currency type. ISO 4217 three-letter code. For more options, see ISO 4217 data-currency="EUR".
  • data-template (enum[string]): Template to render. Available options can be found on this documentation page.

The button can render three types of templates configured with the data-template attribute. This option can be omitted to show the default classic template.

  • v1 (classic)
  • v2
  • v3
  • embedded

Depending on the template, various attributes can be customized.

To manage the iframe response data, one of these two exclusive attributes can be used:

  • data-callback (string): JavaScript function to be executed upon card capture completion (See responses).
  • data-redirect (string): URL to redirect the operation after card capture. The token received from Sipay’s service will be added as a query string https://example.com/commerce/fpay?request_id=1234567890 (See responses).

In addition to these mandatory fields, other attributes allow for customization:

  • data-lang (enum[string]): Language for non-editable texts. By default, it will be displayed in Spanish:
    • "es": Displays texts in Spanish.
    • "en": Displays texts in English.
  • data-notab (string): To block the pop-up window, add this attribute in the HTML code => data-notab = "1".
  • data-finish_cb (string): Optional function to execute upon transaction completion, runs before data-callback, and is used to reflect changes in the button after an operation (see customization).
  • data-autosave (string): Use true to hide the "remember me" button and false to show it. The default value is false.
  • data-remember (string): When autosave is enabled, you can choose between a 'slide' or 'checkbox' button. The default is slide.
  • data-remembertext (string): If autosave is enabled, you can set a custom text for "remember me."
  • data-paymentbutton (string): Allows modification of the payment button text.

Classic Template (v1)​

Acts like a pop-up but without opening a new window, so the consumer remains on the merchant's website while entering their information. View the pop-up behavior in this link and modify it in this link.

The following attributes can be configured:

  • data-notab (string): Modifies the pop-up style behavior by adding the attribute with the value "1". It will behave as an embedded component in the assigned HTML container.

  • data-finish_cb (string): Optional function to execute upon card capture completion. Runs before data-callback and is used to reflect changes in the button after an operation (see customization).

  • data-hiddenprice (string): Use true to hide the price within the payment button. Otherwise, the false value allows displaying the amount on the button itself. The default value is false.

  • data-autosave (string): Use true to hide the "remember me" button, and false to show it. The default value is false.

  • data-remember (string): When autosave is enabled, you can choose between a 'slide' or 'checkbox' button. The default is slide.

  • data-remembertext (string): If autosave is enabled, you can set a custom text for "remember me."

  • data-profile (string): Allows indicating a card-blocking profile by card BIN. Coordinate with your integrator to implement this block.

  • data-theme (string): Affects the appearance of the card input form (default="standard"). This option can be omitted to display the default blue template.

    • standard
    • red
    • grey

  • data-logo-style (enum[string]): Style of the logo shown in the iframe (default=circle).

    • circle
    • square
    • rectangle

    You can modify the size and transparency of the logo by adding “large,” “small,” or “transparent” to the attribute. Possible values for an example with “circle”:

    • circle_transparent
    • circle_small
    • circle_small_transparent
    • circle_large
    • circle_large_transparent

  • data-logo-url (string): Logo image URL. Preferably 75x75 or 150x75 in case of rectangular logo style data-logo-style="rectangle".

  • data-business-title (string): Ideal for indicating the name of your brand or business, for example, “BrandTitle.” If not specified, it will not display a title.

  • data-description (string): Ideal for indicating the purchase description. If not specified, no description is displayed.

The following example shows the same previous behavior, but this time using a JavaScript function to manage the callback:

Template (v2)​

With the dynamic template (data-template="v2"), in addition to the attributes configurable with the classic template, we have the following:

  • data-carholdername (string): Determines whether the cardholder name input field is rendered. Setting it to true will display the field.
  • data-header (string): Toggles the payment form header display.
  • data-autosave (string): Determines whether the "remember me" button is rendered.
    • false: displays the "remember me" button.
    • true: hides the text and card-saving option, and data.payload.consent returns as true. For more information, consult “Enable and customize 'Remember Me' button”.
  • data-remember (enum[string]): Allows selecting whether a slider (slide) or checkbox (checkbox) is rendered for the "remember me" function.
    • slide
    • checkbox
  • data-remembertext (string): Customizes the text for the "remember me" button. If you customize the "remember me" button text, Sipay’s legal disclaimer will not display, so the client must include it.
  • data-sipay (string): Allows displaying (true) or hiding (false) the Sipay logo.
  • data-paymentbutton (string): Customizes the text on the payment button.
  • data-hiddenprice (string): Use true to hide the price within the payment button. Otherwise, the false value allows displaying the amount on the button itself. The default value is false.

Template (v3)​

Inspired by another design for embedding on your webpage, you can use the same parameters as v2.

Embedded​

An optimized template for embedding in card capture processes. Check the customization parameters to tailor it to your needs.

Responses​

Callback - attribute: data-callback​

The iframe or card capture window response consists of a JSON message containing a transaction identifier called request_id. It must be used to complete the payment process.

This JSON has the following structure:

{
  "type": "success",
  "code": "0",
  "detail": "tokenization done successfully",
  "description": "Information saved and tokenized",
  "request_id": "ae8893641c7b4d5486f99279f16bb31b",
  "uuid": "04ebf843-6ac4-4fdc-aa1a-bc876c140dde",
  "payload": {
    "consent": false,
    "cardholder_name": null,
    "expiration": "**/**",
    "pan": "**** **** **** ****"
  }
}

Where:

  • type (string): Type of response
  • uuid (string): Unique request ID
  • detail (string): Response detail
  • description (string): Response description
  • code (string): Operation result code
  • payload (json): Response in JSON format
    • consent (string): "Remember me" button response. Value true when the user activates the button
    • cardholder_name (string): Cardholder name entered in the form
    • expiration (string): Card expiration date (month/year)
    • pan (string): Masked card number
  • request_id: Temporary card capture token. It is necessary to perform any additional operation (sale, tokenization, etc.) and lasts for five minutes.
Example of a JavaScript function for callback
function callbackFunction(data) {
  alert(data);
}

Redirect - attribute: data-redirect​

In this case, request_id will be appended to the URL specified in the data-redirect attribute in QueryString format with the key request_id. For example, if we use https://httpbin.org/get as the URL, after capturing the card, it will redirect to:

https://httpbin.org/get?request_id=12345677890

Your code should capture this value and complete the server-to-server operation with our API.

Customization​

The button appearance can be customized using standard CSS:

.fastpay-btn img {
  display: none;
}

.fastpay-btn {
  border: 1px solid black !important;
  background: #eaeaea !important;
  padding: 2px 5px;
}

.fastpay-btn {
  border: 1px solid black !important;
  background: #eaeaea !important;
  padding: 2px 5px;
}

If you hide the default button with this CSS:

.fastpay-btn img {
  display: none;
}

You can use this JavaScript function to load the form whenever you need:

document.addEventListener("DOMContentLoaded", function () {
  document.querySelector(".fastpay-btn").click();
});

Complete example:

Template V2​

The style of the payment sheet can be modified via JavaScript as follows:

Fastpay.customize({
  colors: {
    title: "#000000",
    description: "#ffffff",
    header_line: "#08b041",
    inputs_lines: "#08b041",
    icon: "#6f6f6f",
    info: "#08b041",
    button: "#08b041",
    cvv_info: "#6f6f6f",
    header_color: "#08b041",
  },
});

Embedded Template​

For the "embedded" template (data-template="embedded"), the following attributes can be customized:

Fastpay.customize({
  colors: {
    inputs_lines: "#08b041",
    info: "#08b041",
    button: "#08b041",
    cvv_info: "#08b041",
  },
});

Additionally, the data-finish_cb parameter can be used on the button to customize how it behaves based on the response. This callback will receive the button object and the response. The button object will contain the DOM element in an "el" parameter.

Usage example:

function finishcb(button, response) {
  button.el.innerText = "Finishcb: Payment Completed";
}

Using the Script in Asynchronous Environments​

If we need to use the script in environments where the button is not loaded at the start or require more integration flexibility, we can manually set a variable window.DONT_AUTOLOAD_FPAY.

DONT_AUTOLOAD_FPAY = true;

The Fastpay object provides the following method to load all available buttons:

  • loadAll: This method automatically loads all buttons with the .fastpay-btn class, even if DONT_AUTOLOAD_FPAY = true is set.

And the following methods to load individual buttons:

  • loadStyles: This method adds the FastPay CSS to the page; it should be called if DONT_AUTOLOAD_FPAY is set and loadAll is not called.
  • loadButton: This method receives a DOM element with the button on which Fastpay will be initialized and configures Fastpay to open on button click.
  • addButton: This method receives a DOM element with the button on which FastPay will be initialized and adjusts the button style to match FastPay's style.

Example usage to load all buttons:

Fastpay.loadAll();

Example usage to load a single button:

Fastpay.loadStyles();
FastPay.loadButton(document.getElementById("fastpay_button_1"));
FastPay.addButton(document.getElementById("fastpay_button_1"));