surfboard_ttp 1.1.1

Payments SDK for Surfboard Payments enabling payments for Flutter projects.

Surfboard TTP

​ ​

The SurfboardTTP package enables your flutter application to accept card present payments using Tap To Phone (TTP) technology. This package is currently available only on Android. ​

Before starting to use the Surfboard TTP SDK, we recommend you to have an account with Surfboard Payments to receive API credentials. We also recommend reading through our guides and SDK documentation.

​ The Surfboard TTP SDK works alongside the Surfboard Payments API. This SDK allows you to perform the following operations: ​

• Terminal - registration
• Order
  • creation
  • updatation
  • cancellation
• Payment
  • initiation
  • statusCheck
  • cancellation ​

To perform admin actions, an integration with the Surfboard Payments API is required. The SDK also requires an auth token for each merchant. More information on this is available in the developer docs. ​ The integration with the SDK can be more focussed on the backend or lighter on the backend. We recommend using the SDK only for payment initiation and payment status checks. However, the SDK can be used to create orders as well. The below steps are used to integrate the SDK with your application and show an implementation that is client heavy. ​

Getting Started

​ Add the surfboardTTP package as a dependency to your project. Please note that this package is dependent on other commonly used packages such as android_id, android_intent_plus, device_apps, device_info_plus, http and package_info_plus ​

flutter pub add surfboard_ttp

​

Permissions

​ The PIN app collects user permissions for the following: ​

• Camera
• Location
• GPS
• Storage ​

Your app needs to have the QUERY_ALL_PACKAGES enabled as we use the device_apps package to check if the PIN app is installed on the device. ​

<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" />
<uses-permission android:name="android.permission.INTERNET"/>

​

Initialise the package

​ Import the package in your app. Please note that if the terminal is registered earlier, you will need to pass in the terminalId to avoid triggering of the re-registration process. You will also need the merchantId and the storeId of the merchant as part of the initialisation. ​

import'package:surfboard_ttp/surfboard_tt.dart'
​
SurfboardTTP surfboardTTP = SurfboardTTP(
  apiUrl: 'apiUrl',
  terminalId: 'terminalId',
  cpocBundleId: "bundleId",
  partnerId: "partnerId",
  merchantId: "merchantId",
  storeId: "storeId",
  appId: "appId",
);

​ The terminalId is an optional field and is not required. ​

Authentication

​ Sets the authToken generated by the Auth Token API. This method can be called to set a new token. The SDK will use this token for all subsequent API calls. ​

surfboardTTP.setAuthToken(authToken: 'authToken');

​

Supported Operations on the SurfboardTTP

​

Terminal Registration

​ This is a one time process that needs to be performed in each new android device. We recommend that you register the terminal as part of the onboarding process of the merchant. The current terminal registration process involves 3 steps. ​

⚠️ NOTE: The terminal registration flow is being redesigned and will be updated in the upcoming release to make it simpler. The below calls will be replaced by a single call. ​ To register the terminal, start by creating an instance of the Terminal ​

final Terminal terminal = Terminal();

​

1. Register Terminal

​ Call the registerTerminal method to receive the entryCode that is required in the next step. You will also recieve the terminalId which needs to be saved and used for all further activations of the SDK. The terminalId is also used when creating an order against a terminal. ​

RegisterTerminalReturnType terminalReturn = await terminal.registerTerminal();

​

2. Activate PIN Add-On

​ Launch the PIN add-on for the activation. Pass in the entryCode returned from [registerTerminal]. Please note that the PIN add-on needs to be installed on the device for this to work. ​

terminal.callCpocForRegistration("entryCode");

​

3. Complete Activation of the PIN Add-On

​ You need to call the registerCpoc method with the registrationCodeId from the [registerTerminal] method to finalise the activation process. ​

await.terminal.registerCpoc("registrationCodeId");

​ Once the terminal is registered, you can start creating orders and performing payments. The SDK takes care of initialising the terminalId on the completion of terminal registration. ​

Performing Order operations

​ You can create an order in the SDK and perform operations on it. The order object is created by passing the OrderType to the constructor. We recommend that you create the order in the backend using the API for increased compatibility with other solutions. ​

Order order = Order(orderType: OrderType.purchase);

​

1. Create Order

​ You need to add LineItem to the order instance to be able initiate payments. ​

LineItem lineItem = LineItem(
  id: '1234',
  quantity: 1,
  name: 'item1',
  itemAmount: ItemAmount(
    regular: 1000,
    total: 1000,
    currency: Currency.sek,
    tax: [
      Tax(
        amount: 100,
        percentage: 10,
        type: TaxType.vat,
      ),
    ],
  ),
);

​ Once the lineItem is added, you can call createOrder method which creates the order and returns the orderId which is required for payment initiation. ​

order.addLineItem(lineItem).createOrder();

​

Performing Payments

​ Once an order is created, you can initiate a payment against the order by calling the initiatePayment method. You will receive a paymentObject which can be used to check the status of the payment and get the transaction details. ​

Payment payment = await order.initiatePayment();

​

2. Get Payment Status

​ To check the payment status of the current payment instance. Returns PaymentStatus . ​

PaymentStatus paymentStatus = await payment.getPaymentStatus();

​

3. Get Transaction Details

​ Once the payment status is completed, call this method to the Transaction Details ​

TransactionDetails transactionDetails = await payment.getTransactionDetails();

​ This will return the transactionId , truncatedPan and other transactionDetails. ​

Additional information

​ To know more visit https://developers.surfboardpayments.com/docs ​

COMING SOON

​

• ❌ Function to show pop-up for PIN-app installation
• ❌ Function to check if the PIN-app is installed
• ❌ Ability to pass in the terminalID after initialisation
• ❌ CHange in the terminal registration flow