Log in to the Enterprise Business Centre

1. Log in to the Enterprise Business Centre (at https://admin.smartpayfuse-test.barclaycard/ebc2) using the credentials created in Getting Started Step 1:

   

2. Use the username and password you created in Getting Started Step 1 when requesting your sandbox account. Note: you will be asked to set a new password when you first log on to the Enterprise Business Centre.

3. Once logged in to the Enterprise Business Centre proceed to Getting Started Step 3 to configure your Flex Microform service and retrieve credentials for the implementation.

Create Flex Microform API keys

An API Key is required to authenticate flex Microform requests on Smartpay Fuse. Once logged in to the Smartpay Fuse EBC portal, head to the sidebar menu and select the Payment Configuration > Key Management menu item, which will display the main key management page. The initial view displays any keys already created on the account and allows you to search for keys by type and created date range.

To create a new key, you will need to select the ‘Generate Key’ button on the top right-hand side of the page:

A “Create Key” window will be displayed, offering a range of different key types. For REST API integration you will need to select a key type from the “REST APIs” section at the head of this page:

There are two options for REST key creation:

• Shared Secret: creates a key id and shared secret keypair used to sign HTTP requests 

• Certificate: creates a PKCS12 certificate used for digitally signing API requests

For this guide select REST – Shared Secret.

When you’ve chosen your preferred key type, scroll to the bottom of the page and select ‘Generate Key’. Your new keys will be generated and displayed, ready to copy and download:

You now have the two parameters required for Flex Microform authentication:

• A key id used to identify your new REST key in API requests

• A shared secret used to digitally sign API requests

Important: these REST keys must be stored securely within your back-end service. They allow API access to your service and must be treated as highly sensitive information. Research and implement appropriate API key management best practices when considering how to store and manage these keys.

Note: clicking “Generate another key” at this stage will return you to the “Create Key” screen in readiness to create a fresh set of keys. Your keys have already been generated if this window is displayed, so it is safe to click “Cancel” or visit other screens via the menu at this stage.

You have now created the keys you need to initiate a Flex Microform request, go to Getting Started Step 4 to test the integration.

Test your integration - tokenize a payment card using Flex Microforms

Now that you have set up your API keys, you have all the information you require to perform a quick test integration using some of our sample code.

Note: Smartpay Fuse has been created in partnership with VISA Cybersource. You may notice some  resources feature the Cybersource brand – these are still part of connecting to Barclaycard Payments.

We provide sample integration code in a variety of languages to get a basic integration up and running. The code will require modifying to work with your specific payment journey, but the following examples will get your very first Flex Microform payment card tokenization working with the profile you created in the previous steps:

NodeJS             DotNet              PHP                  Java

Each repository above will have README content associated, with instructions on how to deploy, configure and run the examples.

NOTE: be sure to use the Microform sample code and microform approach when implementing Hosted Fields. The sample code references flexjs, which is a different integration approach that does not provide the low PCI overheads of Microforms. If you would like to discuss using the flexjs integration approach please get in contact first to discuss whether this is right for your use case and PCI appetite.

The first step is to create the server-side request that generates the “capture context”. The capture context is a digitally signed JSON Web Token (JWT) that provides authentication and the one-time key required by the Flex Microform front-end.

1. Firstly, ensure that you have PHP installed such that you can successfully run a phpinfo test:
     — Ensure that you are using PHP version 5.6 or greater.
     — Install cURL, JSON and APCU extensions.
     — Have created your test account (see Getting Started Step 1).
     — Have generated your API keys (see Getting Started Step 3).

2. Download and unpack the sample code above.

3. Unpack the example code and check all file permissions.

4. Edit the file ExternalConfiguration.php and replace the apiKeyId, secretKey and merchantID defaults with the values generated when you created and set-up your credentials in Getting Started Step 3.

   

5. Update currency used during transaction processing:
   a. Edit php-microform/paymentWithFlexTransientToken.php.
   b. Change the value of "currency" from "USD" to "GBP".

6. Upload the edited PHP sample code to your web server OR simply run on localhost.
   Note: if deploying somewhere other than http://localhost you will need to set the value of targetOrigins when creating the server side content, as discussed in the full guide here.

7. Use composer to ensure dependencies are up to date (see README.md).

8. Deploy to your webserver or run standalone (see README.md).

9. Navigate to the URL hosting the application to see the sample web-page with embedded microform fields, for example if running on localhost:
   https://localhost:8000/checkout.php

10. On navigating to the target URL you’ll see a payment form presented, with input fields for the usual payment form field.

11. Enter some TEST payment card details (please see test card numbers here) and press Pay.

Pressing Pay will POST the sensitive card details directly to Smartpay Fuse and initiate the generation of a PCI safe “transient token” that will be safe to pass through your back office systems.

In this demo the transient token is returned and displayed on the response page. You can proceed to Step 5 and use the transient token to perform a transaction, or, just hit the “Make a Payment with Transient Token” button in the demo to process a transaction.

In a live system you will want to capture this token in the browser and return it to your back-office systems and continue the payment process using our REST API.

Next Step: to process the transaction further you will need to use our REST API to send these encrypted payment details to Smartpay Fuse.

Test your integration - process a payment with the back-end API using a tokenized payment card

In Getting Started Step 4 you used Flex Microforms to successfully tokenize a payment card. You now have a transient token that can be safely passed through your back-end infrastructure and used by your service to make a payment. Because this transient token is a representation of a payment card, and not the card itself, it is safe to pass this information through your service without incurring anything more than SAQ A PCI overheads.

To process a payment using the transient token, you need to use our REST based transaction processing API. This will allow you to progress and control the lifecycle state of a transaction fully from your own back-office servers.

Please note that there may be additional steps that require further consumer and browser interactions; fraud and Strong Customer Authentication are examples. These can be complex flows to navigate, so you may wish to consider using our fully hosted payment page solution (Secure Acceptance Hosted Checkout - see the Quick Start Guide here).

To process a payment using the transient token created in Getting Started Step 4, use the standard ‘process payment’ REST message but replace the card details with the transient token JWT, an example request is shown below:

{                                    
      "clientReferenceInformation": {
      "code": "TC50171_3"
   },
      "processingInformation": {
      "commerceIndicator": "internet"
   },
      "orderInformation": {
         "amountDetails": {
            "totalAmount": "22",
            "currency": "GBP"
         },
         "billTo": {
            "firstName": "John",
            "lastName": "Doe"
         }
      },
      "tokenInformation": {
         "transientTokenJwt": ""
      }
   }

You can actually test this in the “live console”, using the credentials you created in Getting Started Step 3 and the transient token you generated in Getting Started Step 4.

An introduction to the request builder is available here.

To demonstrate use of this tool we will perform a simple sale transaction using the POST method on the /payments endpoint.

1. Open the Process a Payment page in the request builder, you should see the following screen:

   

2. Configure the type of operation you would like to perform by clicking on the “Configuration” tab that is placed at the top of the “Request Builder” window. This pane allows you to configure key transaction parameters including:
     — The target API URL; destination endpoint of any API requests generated by the request builder
     — The reqeuest type; triggers the request builder to populate the request with appropriate fields
     — The payment processor; select Barclays Merchant Services
   

See the example below for the simple authentication transaction we will run in this example: 



In this example we will be performing a simple authorization of the card that you tokenised using the Microform; the card that is now represented by your “transient token” JWT.

3. Continue on to configure API credentials by scrolling further down in the “Configuration” tab to the Authentication section: 

   

   Here you can enter the credentials required to authenticate any request to Smartpay Fuse. The key parameters here are:
     — The merchant ID generated during your account creation
     — The REST API Key ID you created in Getting Started Step 3
     — The REST API Secret you created in Getting Started Step 3
   

   Because the standard live console test is set-up to process a card number, you will need to modify the JSON payload in the “Request: Live Console” window as follows: 

   {
      "clientReferenceInformation": {
         "code": "TC50171_3"
      },
      "orderInformation": {
         "amountDetails": {
            "totalAmount": "102.21",
            "currency": "GBP"
         },
         "billTo": {
            "firstName": "John",
            "lastName": "Doe",
            "address1": "1 Wokes Street",
            "locality": "Fleet",
            "postalCode": "GU51 WKS",
            "country": "GB",
            "email": "[email protected]",
            "phoneNumber": "4158880000"
         }
      },
      "tokenInformation": {
         "transientTokenJwt": "THE JWT RETURNED FROM YOUR MICROFORM     INTERACTIONT"
      }
   }

Click on the Send button to send the request to Smartpay Fuse.

The live console takes care of the message digests, the required HTTP headers and message signatures allowing you to test transactions without actually coding the exchange in an application.

The authorization should complete successfully. It may fail if you did not enter a valid card expiry date or use test cards outside of those defined in the sandbox testing guide here.

As a final step, log in to the Enterprise Business Centre and check that the transaction ran in the Transaction Management view:

Congratulations, you should now have processed a transaction using a Flex Microform test application and the REST API through the online request builder.

Please see the Further Information section for links to key guides and resources that will help you build out your full integration.