Surfboard TTP
The SurfboardTTP SDK enables your flutter application to accept card present payments using Tap To Phone (TTP) technology. This package currently functions 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 add-on 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 add-on 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_ttp.dart'
SurfboardTTP surfboardTTP = SurfboardTTP(
apiUrl: 'apiUrl',
terminalId: 'terminalId',
ttpBundleId: "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.
To register the terminal, start by creating an instance of the Terminal
final Terminal terminal = Terminal();
To perform payments Pin add-on plays the important of handling card transaction. so its important to check whether the pin add-on is installed or not.
Call the isPinAppInstalled method to know whether pin add-on is installed or not. Returns true if the pin add-on is installed in the device.
bool isPinInstalled = await terminal.isPinAppInstalled();
Call the registerTerminal method to 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. The SDK also requires a stream to be provided which should be populated according to the AppLifeCycle
StreamController<AppLifecycleState> appLifecycleState = StreamController<AppLifecycleState>();
String terminalId = await terminal.registerTerminal(appLifecycleState.stream);
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.
Initiating Payments For created Orders
Once you create an order via the API, you can initiate a card Payment for the order via the SDK.
Order order = Order(orderType: OrderType.purchase, orderId: <Your OrderID>);
Payment payment = await order.initiatePayment();
Once the payment is initiated, the app handles the intent switch to the PIN add-on. Once the card read and PIN entry are completed, the PIN add-on closes and redirects back to the app. You can check the status of the payment and fetch transaction details using the below methods.
Get Payment Status
To check the payment status of the current payment instance. Returns PaymentStatus .
PaymentStatus paymentStatus = await payment.getPaymentStatus();
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.
Other methods
If you have a setup where you would like to create the order on the client side, we also provide utility methods for order creation. 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);
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();
Additional information
To know more visit developers.surfboardpayments.com/docs
Libraries
- core/order
- core/payment
- core/surfboard_ttp
- core/terminal
- models/device_data
- models/errors
- models/initiate_payment_req
- models/models
- models/order_details
- models/order_model/amount/currency
- models/order_model/amount/item_amount
- models/order_model/amount/tax
- models/order_model/amount/tax_type
- models/order_model/company
- models/order_model/control_functions
- models/order_model/customer/billing
- models/order_model/customer/customer
- models/order_model/customer/name
- models/order_model/customer/person
- models/order_model/customer/phone
- models/order_model/order_lines
- models/order_model/order_models
- models/order_model/order_type
- models/payment_id
- models/payment_method
- models/payment_model/payment_models
- models/payment_model/src/payment_details
- models/payment_model/src/payment_status
- models/payment_model/src/tranaction_details
- models/payment_model/src/transaction_data
- models/response_models/response_models
- models/response_models/src/get_registration_id
- models/response_models/src/no_data_response
- models/response_models/src/order_created
- models/response_models/src/order_status_response
- models/response_models/src/payment_details_response
- models/response_models/src/payment_initiated
- models/response_models/src/payment_status_response
- models/response_models/src/terminal_registered
- models/terminal_model/src/create_terminal
- models/terminal_model/src/register_terminal_return
- models/terminal_model/src/register_ttp
- models/terminal_model/src/software_type
- models/terminal_model/terminal_model
- services/abstract/device_handler
- services/abstract/pin_intent
- services/constants
- services/http_service
- services/response_error
- services/routes
- surfboard_ttp