# Saferpay Fields The Saferpay Fields grant you the flexibility of your own HTML form. \ \ Simplest level of PCI DSS compliance (SAQ A). They're an extension of the [Transaction Interface](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface) and [Secure Alias Store](https://docs.saferpay.com/home/integration-guide/secure-card-data#standalone-secure-card-data-registration) and are used together with either one or both of these interfaces. {% hint style="info" %} Please consider our license chapter to determine if the Saferpay Fields are available for you. {% endhint %} The main idea is to split the classic card entry form into its components, namely the inputs for the PAN, CVC, Expiration, and Holder Name. These fields will be hosted on Saferpay's side, ensuring that the data is captured by a PCI DSS validated service provider, while offering you a level of flexibility and possibilities similar to using your own form. This chapter will cover the integration and preparations necessary to work with the Saferpay Fields. ## Supported Payment Methods * Visa/VPay * Mastercard * Maestro * American Express * Bancontact * Diners Club * JCB ## Basic Flow This is the basic Saferpay Fields flow. ![(click to enlarge)](https://3537448238-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fzpi9teY7Tm2pCZ1Bw8zO%2Fuploads%2FgBeoEQNZvL5HaxplchAZ%2Fsaferpay-fields-flow_WL.png?alt=media\&token=df38b826-045d-4a15-8174-6264b04f038d) 1. The card holder navigates to the checkout 2. The shop frontend calls **SaferpayFields.Init()** (See Integration and Initialization > Hosted Fields Initialization) and the Saferpay Fields Javascript library initializes the iFrames. 3. Once initialized, the library will replace the placeholders with the correct iFrame inputs, which then are presented to the card holder. 4. The card holder enters his card details and clicks "Submit", on which the Webshop executes the **SaferpayFields.submit()** function. 5. The Saferpay Fields Javascript library then submits the iFrames, which sends the card details towards Saferpay. 6. Saferpay caches the card details **for a maximum of 20 minutes** and generates a token, which is then used to reference said means of payment. 7. The token is forwarded and the **SaferpayFields.submit(); onSuccess callback** is called, so the token may be captured and processed further. 8. The token then has to be forwarded to serverside. How you do that, is up to you. Methods like for example a redirect or AJAX are possible. Once on serverside, the token is then used to continue with the next step, either [following the normal Transaction Interface flow](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface), or a [card registration](https://docs.saferpay.com/home/integration-guide/secure-card-data#saferpay-fields). Please refer to that chapter on further information, about how to submit the token through the JSON-API and execute the transaction itself. ## Preparation Before you can start integrating the Saferpay Fields, you need to create an Access Token. To do so, you need to log into the Saferpay Backoffice. Navigate to [Settings > Saferpay Fields Access Tokens](https://docs.saferpay.com/home/interfaces/backoffice/settings#saferpay-fields-access-tokens) and follow the instructions. {% hint style="warning" %} Once you move from the Test-Environment to the Live-Environment, you need to create a new Access Token on your live account! {% endhint %} {% hint style="info" %} On the Test-Environment you can use a self-signed SSL-certificate, if you wish. This is helpful, if you are coding and testing on a small, local machine, instead of a server. Furthermore, as a Source-URL, you can enter you Computer-/Host-name. Example ****. This works with local PCs, that do not have a public domain attached to them! {% endhint %} ## Integration and Initialization After you have created your API-Token, you can start integrating the Saferpay Fields into your site. ### Include the Saferpay Fields JavaScript library into your site ```markup ``` ### Define, where Saferpay should insert the Hosted Fields ```markup
``` The placeholder must be either `
`, ``, or ``, see: | Input-Field | id-Value | | ---------------- | ------------------ | | Card Holder Name | fields-holder-name | | Card Number | fields-card-number | | CVC | fields-cvc | | Expiration | fields-expiration | {% hint style="warning" %} The placeholder must have a height > 0, or the iframe will inherit this height! {% endhint %} {% hint style="info" %} The card holder field can be left out, if you do not want to capture the holder name. However, if it is initialized, it must be filled in! {% endhint %} {% hint style="info" %} The CVC is always mandatory, except on cards, that do not have a CVC! In these cases, Saferpay will deactivate the field! {% endhint %} {% hint style="info" %} If you set a "title"-attribute for your placeholders, Saferpay will also apply it to the iFrames. **Any other html-attributes are ignored.** {% endhint %} ### Saferpay Fields Initialization ```javascript SaferpayFields.init({ // access token accessToken: '[YOUR Access Token]', // api url url: 'https://test.saferpay.com/Fields/[YOUR CUSTOMERID]', style: { '.form-control': 'border: none; border-bottom: solid 1px #ccc; border-radius: unset;' }, paymentMethods: ["visa", "mastercard"], language: 'EN', onSuccess: function() { //Callback on successful Init }, onError: function(evt) { //Callback on unsuccessful Init }, placeholders: { //Custom Text for Input placeholders holdername: 'Card holder', cardnumber: '0000 0000 0000 0000', expiration: 'MM/YY', cvc: 'CVC' }, onBlur: function (evt) { //Callback on blur (Card Holder leaves field) }, onValidated: function(evt) { //Callback similar to on blur (Card Holder leaves field), but explicitly delivers validation data }, onFocus: function (evt) { //Callback on focus (Card Holder clicks into field) } }); // submit(); sends the entered hosted fields data to Saferpay. SaferpayFields.submit({ onSuccess: function(evt) { //Callback on successful Submit }, onError: function(evt) { //Callback on unsuccessful Submit } }); ``` ## SaferpayFields - Class functions ### .version() Returns a **string** containing the current library-version. ### .init({options}) Initializes the Saferpay Fields and replaces the placeholders, as defined before. #### Available options * **accessToken** *string* : Contains the Access Token, you have defined inside the Saferpay Backoffice earlier. * **url** *string* : Contains the API-Url, to define, where to post the data and initialize the Saferpay Fields. ```javascript // Test Environment url: 'https://test.saferpay.com/Fields/[YOUR CUSTOMERID]', // Live Environment url: 'https://www.saferpay.com/Fields/[YOUR CUSTOMERID]', ``` * **language** *string* : Specify the language that can be used by tools such as screen readers (WCAG). * **onBlur** *eventCallback* : Callback function, that is executed, should the customer leave the field. The event returns a **Callback message**. * **onValidated** *eventCallback* : Callback function, that is executed, should the customer leave the field. The event returns a **Callback message**, also containing field validation-data. * **onFocus** *eventCallback* : Callback function, that is executed, should the customer enter the field. The event returns a **Callback message**. * **onSuccess** *eventCallback* : Callback function, that is executed, every time, the Saferpay Fields have been loaded successfully. * **onError** *eventCallback* : Callback function, that is executed, every time, the initialization of the Saferpay Fields has not been successful. The event returns an **Error Callback Message**. * **style** *Object* : Object, that defines CSS rules, to be applied to all elements. **Example:** ```css style: { '.form-control': 'border: none; border-bottom: solid 1px #ccc; border-radius: unset;' } ``` * **paymentMethods** *String\[]* : A String-Array, containing a list of brands to be accepted! Currently accepted brands/values: mastercard, maestro, visa, jcb, diners, bancontact, amex * **cssUrl** *String* : Url to an external CSS, to be applied to all elements. * **placeholders** *Object* : Object, that contains custom placeholder text, to be applied to the inputs. **Example:** ```json placeholders: { //Custom Text for Input placeholders holdername: 'Card holder', cardnumber: '0000 0000 0000 0000', expiration: 'MM/YY', cvc: 'CVC' }, ``` ### .submit({options}) Submits the Saferpay Fields. #### Available options * **onSuccess** *eventCallback* : Callback function, that is executed, if the Saferpay Fields have been submitted successfully. The event returns a **Submit Success Callback Message**. * **onError** *eventCallback* : Callback function, that is executed, if the Saferpay Fields have not been successfully submitted. The event returns an **Error Callback Message**. ### Callback Messages Saferpay returns certain data to the application, in case of certain **eventCallback**s. **Callback Message** *Object* : Callback message on normal event, containing the following data: | Parameter | Type | Description | | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | event | String | Name of the event, that occured. | | fieldType | String | Type of the field affected. | | id | String | Id of the field affected. | | isValid | Boolean | Validity of the field affected. (**onValidated** callback only!) | | reason | String |

Reason, why a field is not valid! The following reasons can be returned:

  • invalid: The input given, is generally invalid!
  • empty: The input is empty!
  • unsupported: Thrown, when paymentMethods is used and a not listed brand is entered!
  • expired: The given card is expired!
  • undefined: If the field is valid, or hasn't been validated yet, the reason will be "undefined"!
| **Error Callback Message** *Object* : Callback message on error event, containing the following data: | Parameter | Type | Description | | --------- | ------ | ------------------------------------------------------------------------ | | message | String | A human-readable explanation specific to this occurrence of the problem. | **Submit Success Callback Message** *Object* : Callback message on a successful submit, containing the following data: | Parameter | Type | Description | | ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | token | String | The Saferpay Fields Token, later to be referenced by [Transaction Initialize](https://saferpay.github.io/jsonapi/index.html#Payment_v1_Transaction_Initialize), to execute the payment itself. | | holderName | String | Name of the cardholder | | maskedCardNumber | String | Masked card number (PAN) | | paymentMethod | String | Name of the payment method | ## Further steps It is important to understand, that the Saferpay Fields are just a way to capture the card details. Now, you have to decide, what to do, with this information. You have two options now: 1. Execute a transaction. If you want to use the captured card data for a normal transaction, then you have to refer to the [Transaction Interface Process](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface). By simply submitting the Fields Token via this API-Method, you can generate an API Token -note the difference- to trigger an Authorization and a RedirectUrl, for performing other steps, like DCC, or 3D Secure. 2. Save the card. If you want to just save the card for now, you can do that via the [Saferpay Secure Alias Store via standalone registration](https://docs.saferpay.com/home/integration-guide/secure-card-data#standalone-secure-card-data-registration). This allows you to obtain a card alias, to perform other actions, like recurring payments, or just enable your customers to save new payment means inside their shop account, for further use. The choice is yours. Once the **onSuccess** event is called, you need to forward the Saferpay Fields token to your server-backend, in order to initialize the next step (see above) and also gather the **RedirectUrl**, to perform things like 3D Secure and/or DCC. How you move the token to the backend is completely up to you. You can provide the onSuccess event with an AJAX-method, to execute the initialization in the background on a successful submit and forward the **RedirectUrl** to the fronend for a redirect this way, which you then can open in an iframe, Lightbox, or as a full redirect. However a redirect via GET, or POST, towards your initialize-script, is also an option. Refer to the above mentioned chapters, to learn, how to initialize a transaction, or just save a card, using a Saferpay Fields token. {% hint style="warning" %} This process has to be finished within 20 minutes, after the submission of the card details. Saferpay will discard the card details afterwards and the Saferpay Fields token becomes invalid! {% endhint %} ## Examples Here you can see some examples of how the Saferpay Fields may be integrated. Feel free to use this code, if you have trouble integrating. [Fully working example](https://shop.saferpay.eu/saferpayintegration/HostedFields.php). This example not only shows you the Saferpay Fields, but also how the API is supposed to work, as described in the [previous chapter](#further-steps). The design-Samples are hosted on JS-Fiddle, so you may edit them on-the-fly. {% hint style="info" %} Feel free to use this code, if you are stuck {% endhint %} {% embed url="" %} {% embed url="" %} {% embed url="" %}