ON THIS PAGE

Overview

Version 1.0

Release notes V1

The Smartpay Fuse REST API provides a complete set of tools to integrate with your payment system. It helps you start and manage transactions, and perform key administrative tasks.

This REST API is our main interface for integration, and the primary way to connect with the Smartpay Fuse platform.

You can use the REST API in two main ways:

 

  1. On its own to process payments when you collect card details on your site.
  2. Manage transactions started with other Smartpay Fuse platform tools, such as Secure Acceptance Hosted Checkout and Flex Microform.

Key Steps for Integration

 

  1. Review Key Features and Benefits and Integration Feature Comparison to learn more about the REST API and its capabilities. Consider this information before you start your integration. Make sure that a direct REST API integration is the best choice for your system. One of our other integration methods might work just as well, and require less effort to integrate in to your system.
  2. Choose how to authenticate:
    Shared secret
    Certificate-based
  3. Create your REST API requests:
    Send order and card data using the REST API to start a payment
    Add 3-D Secure (Payment Authentication) for e-commerce transactions
  4. Test your integration thoroughly.
Our REST API offers several advantages:
 
  • You have full control of the user experience.
  • You have full control of the payment process.
  • Works for both web and mobile journeys.
  • You can access all Smartpay Fuse platform features.
  • You can complete transactions started with E-commerce Plugins, Virtual Terminal, Hosted Payment Pages, and Flex Microform integration methods.

The REST API integration is one of several methods to accept payments on your site. Smartpay Fuse offers additional methods that provide different features. Before you start your integration, make sure you choose the right method for your needs. If the capability you need is not supported with the REST API, consider using one of the alternate integration methods.

For more information about these integration options, refer to these quick start guides:

  • E-commerce Plugins: provides an easy integration for supported e-commerce platforms.
  • Virtual Terminal: no integration is required because servicing agents take payments using our back-office portal, Smartpay Fuse Portal[ebc].
  • Hosted Fields: you can capture individual payment card details as PCI-safe fields.
  • Hosted Payment Page: requires minimal integration because you initiate the payment page, which handles the entire payment flow.

Contact us if you have questions about the REST API.

This table provides a comparison of the features that are available in the different integration methods.

Integration Methods
Features Virtual Terminal 1  E-Commerce Plugins Hosted Payment Page   Direct REST API  Hosted Fields
 PCI overhead SAQ C-VT Mixed2 SAQ A SAQ D SAQ A3
 Transaction Types

Authorization only

 Yes Yes (all) Yes Yes Yes7

Authorization and capture

 Yes Yes (all) Yes Yes Yes7

Tokenise card (COF) 

 Yes Yes Yes4 Yes Yes7

CIT (initial/subsequent)

 Yes Yes Yes4 Yes Yes7

MIT (continuous authority)

 No Some6 No Yes Yes7

Refund (standalone)

 Yes8 Some6 REST API & Smartpay Fuse Portal1 Yes Yes7

Refund (existing transaction)

 Yes Yes (all) REST API & Smartpay Fuse Portal1 Yes Yes7

Reversal

 Yes Yes (all) REST API & Smartpay Fuse Portal1 Yes Yes7

Capture of standalone authorization

 No Yes (all) REST API & Smartpay Fuse Portal1 Yes Yes7
 3-D Secure (v2)  N/A Yes (all) Yes Yes Yes7
 Account validation N/A Some6 Yes Yes Yes7
 Basic fraud rules5 Yes Yes (all) Yes Yes Yes7
 Low value exemptions N/A No Yes Yes Yes7
AVS/CSC Auto Reversal/Blocking Yes8 Yes6, 8 Yes8 Yes8 Yes7, 8
Digital Wallets

Apple Pay

 N/A Some6 No Yes No7

Google Pay

 N/A Some6 No Yes No7
Card Types

Visa

 Yes Yes Yes Yes Yes

Mastercard

 Yes Yes Yes Yes Yes

American Express

 Yes8 Yes8 Yes8 Yes8 Yes8
 Channels

E-Commerce

 No Yes Yes Yes Yes7

Moto

 Yes Some6 Yes8 Yes Yes7

Notes:

1: The Smartpay Fuse Portal is our back-office servicing portal.
2: Different plugins use different integration methods. Refer to the applicable quick start guide listed and linked above for details about the PCI implications of those integration methods. Contact support if you have concerns or questions about PCI implications.
3: SAQ A applies when Flex Microforms is used to tokenize from web applications.
4: Secure Acceptance Hosted Checkout creates tokens from initial CIT transactions that can be used for subsequent CIT transactions.
5: Basic velocity rules using Decision Manager are only available for SME clients. Advanced fraud check and TRA are handled on a case-by-case basis.
6: These features are only available on some of our plugins (refer to the individual plugin solution pages for more information).
7: Flex Microform allows card numbers to be safely tokenized in compliance with PC standards. The resulting transient token is used to process or manage the transaction using the direct integration REST API.
8: These features are not enabled out of the box and need further configuration by our support team.

Using the REST API to take payments lets you use all the features of the Smartpay Fuse platform. It gives you full control over how payments are handled and processed. You need to collect the cardholder's details in your front-end applications, and send these details through your back-end system to start the payment process with Smartpay Fuse.

If you decide to collect card details and send them to Smartpay Fuse, those card details go through your own back-end service. This process might require your service to follow a SAQ D-level PCI compliance (see PCI Implications), so consider this integration carefully.

The figure below shows the stages of the payment flow using the REST API:

  1. The customer processes their order on the merchant website.
  2. The payment form displays on the merchant website.
  3. The merchant REST API processes the payment.
  4. The Smartpay Fuse platform processes the payment.

Please see the Getting Started section below for step by step instructions on how to use the REST API.

file

The PCI compliance rules to which you need to adhere vary depending how you use the REST API:

  • If you capture card details on your website and pass them to the Smartpay Fuse platform using the REST API, the card details pass through your system and network. In this case, you incur the highest PCI level, SAQ D.
  • If you tokenize card details using Flex Microform Hosted Fields, cardholder data is already exchanged with Smartpay Fuse, and using the REST API does not require you to pass cardholder data through your service and network. In this case, you incur the lowest PCI level, SAQ A.

If you have any questions or concerns about the PCI implications of using the REST API integration, contact us.

Getting Started

Create a sandbox account

If you use the Flex Microform Hosted Fields to tokenize card details, you need to set-up, configure, and integrate to the Flex Microform solution first.

  1. Visit our sandbox creation page: https://developer.smartpayfuse.barclaycard/hello-world/sandbox.html.
  2. Complete the registration form, accept the terms and conditions, and click Create Account to create your sandbox account.

Important: Registration with our 3-D Secure (version 2) Payer Authentication provider takes approximately 24 to 36 hours to complete. During this time, you might see some transactions failing on 3-D Secure authentication. These failures are flagged as Decision Manager failures in the Smartpay Fuse Portal transaction search.

You receive an automated email from our partner, Smartpay Fuse. This email includes instructions for your first log in and password reset. If you do not receive the email within five minutes after you submit your form, check your email junk folder.

Continue with Step 2: Log In to the Smartpay Fuse Portal.

Log in to the Enterprise Business Centre

  1. Log in to the Smartpay Fuse Portal (https://admin.smartpayfuse.barclaycard/ebc2) using the username and password you created for your sandbox account.

  2. When prompted, set a new password for your Smartpay Fuse Portal account.

Continue with Step 3: Create Your REST API Key to configure your Flex Microform service and retrieve credentials for the implementation.

Create your REST API key

A REST API key is required to authenticate REST-based requests on the Smartpay Fuse platform.

  1. Choose Payment Configuration > Key Management from the left navigation menu. The Key Management page displays. The initial view displays keys that were previously created on the account. You can search for keys using the key type and the date range for which the key was created.
  2. To generate a new key, select the Generate Key icon on the top right-hand side of the Key Management page.

    3. A Create Key page displays, which provides a selection for different key types. For REST API integrations, select a key type from the REST APIs section on the page:

  3. Choose one of these key types from the REST APIs section of the Create Key page::
    • 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.
  4. Scroll to the bottom of the Create Key page and click Generate Key. Your new keys are generated and displayed. Two keys are required for Flex Microform authentication:
    • A key id that is used to identify your new REST key in API requests.
    • A shared secret that is used to digitally sign API requests.

    5.  

  5. Copy and download the REST API keys.

    Important: These REST keys must be stored securely in the Smartpay Fuse Portal. They allow API access to your service and must be treated as highly sensitive information. Adhere to API key management best practices to store and manage these keys.

    If you click Generate another key, the Create Key page displays and allows you to generate new keys. Your keys have already been generated if this window displays. In this case, it is safe to click Cancel or navigate to other pages.

    If you want to use certificates instead of keys to process API requests, select REST – Certificate on the Create Key page. This option generates a PKCS12 file that can be used to digitally sign your API request before transmitting the message to the Smartpay Fuse platform. No data is displayed on the gateway in this case, so you must download the key for future use.

    6.  

    Continue with Step 4: Test the REST API Using the API Reference to test transactions from the REST API using the API Reference tool.

Test the REST API Using the API Reference

Before you begin:

  • Create your test account (see Step 1: Create a Sandbox Account).
  • Generate your API keys (see Step 2: Log In to the Smartpay Fuse Portal and Step 3: Create Your REST API Key.

The API Reference tool, which includes a request builder, provides an easy-to-use graphical interface you can use to generate and send requests, and view the responses to the requests. You can also get detailed information about the fields included in the request by clicking the information (I) icon next to the field.

  1. Access the API Reference tool using this URL: https://developer.smartpayfuse.barclaycard/api-reference-assets/index.html#static-home-section.
  2. Expand the Payments section in the navigation pane and click the Payment link. The Process a Payment page displays.

  3. Configure the type of transaction you want to process:
    • Click the Configuration tab, which appears to the right of the Request Builder tab, in the Process a Payment page.
    • Select Barclays Merchant Services from the Payment Processor Type drop-down menu.
    • Select the request type that you want to process from the Sample Request drop-down menu. When you change the request type, the body content of the request message, which displays in the Request: Live Console pane changes based on the request type you select.

  4. Configure API credentials:
    • Scroll down to the Authentication Type section in the Configuration tab.
    • Enter the credentials for the REST API key you generated in Step 3: Create Your REST API Key. The Authentication Type drop-down menu provides these options:
      • HTTP Signature: uses a Merchant ID, Key, and Shared secret to authenticate requests.
      • JSON Web Token: uses a Merchant ID and P12 certificate to authenticate requests

  5. Click Update Credentials.
  6. Test the transaction:
    1. Click the Request Builder tab.
    2. Click the Send icon at the bottom of the Request: Live Console pane. The response to the request displays in the Response pane, which appears below the Request: Live Console pane.
    3. Review the response displayed in the console at the bottom of the page to ensure the transaction was processed correctly. See the Transaction response codes page to get information about response codes you receive in the response. 

You successfully processed a transaction from the REST API using the API Reference tool.

Continue using the API Reference tool to select and test different transactions. After testing different transactions, go to Step 5: Test the REST API Using Sample Application Code to test transactions using sample application code.

Test the REST API using sample application code

Before you begin:

  • If you use the PHP sample application code, use version 5.6 or greater.
  • Install the cURL, JSON, and APCU extensions.
  • Create your test account (see Step 1: Create a Sandbox Account).
  • Generate your API keys (see Step 2: Log In to the Smartpay Fuse Portal and Step 3: Create Your REST API Key)

Successfully processing a transaction using the API Reference tool confirms that your credentials are valid and your REST API implementation is correct. You can also use sample application code to test basic transactions. Sample application code is available in these languages:

Java      C#        PHP      NodeJS     Ruby    Python

These samples use the Smartpay Fuse brand because the Smartpay Fuse was created in partnership with Smartpay Fuse.

We will use the PHP example to demonstrate the necessary steps:

  1. Clone the sample application code from GitHub. This example shows how to clone the PHP sample application.
    > git clone https://github.com/cybersource/cybersource-rest-samples-php
    > cd cybersource-rest-samples-php

  2. Run composer to update dependencies.
    > composer update

  3. Execute a simple test scenario.
    The sample application has a wide range of example scenarios, each of which can be used as a template for your own code or executed standalone from the command line.
    The code samples work out of the box with test credentials, but you might want to amend the sample application configuration to use the credentials you created in Step 3: Create Your REST API Key. Using your own credentials processes transactions to your account and allows you to search for and manage those transactions in the Smartpay Fuse Portal.
      — Start by executing a simple authorization with capture (sale) transaction. This example shows how execute the transaction using the PHP sample application.
    > php ./Samples/Payments/Payments/AuthorizationWithCaptureSale.php

The request is processed and the response displays in the console. You can view the transaction details in the Smartpay Fuse Portal.

Congratulations, you should now have processed a transaction using the REST API.

Continue testing different sample requests using the API Reference tool to integrate additional capabilities in your code.

Key Resources


Code Samples

Testing Resources

Developer Guides

  • Payer Authentication Developer Guide: provides information for using the REST API to integrate payer authentication services into your payment system.
  • Apple Pay Developer Guide: provides information for using the REST API to integrate Apple Pay with your system and how to process and search for Apple Pay transactions.
  • Google Pay Developer Guide: provides information for using the REST API to integrate Google Pay with your system and how to process Google Pay transactions.

Support

If you have questions about the REST API or need guidance for your integration, contact us.