Book Payment

The book payment component allows you to transfer funds between two customers on your platform, or between two accounts belonging to the same customer. Book payments are free and instant.

Customer experience:

• Specify the amount
• Write a description (that will show up on the activity screens and/or statements)
• Confirm payment

Book Payment Component TEST MODE

Mobile

Desktop

Implementation

Web Components

Add the book payment element to your app where you'd like it to be presented.

<unit-elements-book-payment
    account-id="1105561"
    counterparty-name="Peter Parker"
    counterparty-account-id="1105562"
    is-same-customer="true"
    theme=""
    customer-token=""
    initial-stage-back-button="true"
    final-stage-done-button="true"
></unit-elements-book-payment>

Inputs:

Name	Type	Required	Description
account-id	string	Yes	Unit account id. The account from which money is being sent.
counterparty-account-id	string	No	Unit account id. The account which will receive money.
counterparty-name	string	No	Name of the counterparty. This is the name that will be displayed in the Book Payment UI during the transfer.
is-same-customer	boolean string ("true" / "false")	No	Stating whether both accounts belong to the same customer. Allows fetching additional information about the counterparty account. Default "false"
is-auto-focus	boolean string ("true" / "false")	No	Auto-focus the money input field once the component is mounted. Default "false"
customer-token	string	Yes	A Unit Customer token. Required Scopes: payments payments-write accounts
theme	string	No	A URL that specifies the UI configuration.
language	string	No	A URL that specifies the language configuration.
initial-stage-back-button	boolean string ("true" / "false")	No	An action button at the first stage of the payment flow. Default "false"
final-stage-done-button	boolean string ("true" / "false")	No	An action button at the final stage of the payment flow. Default "false"

Events:

Event Name	Description	Detail
unitPaymentCreated	Occurs when a book payment is created	Book Payment
unitPaymentInitialStageBackButtonClicked	Occurs when the initial stage back button is clicked
unitPaymentFinalStageDoneButtonClicked	Occurs when the final stage done button is clicked

React Native SDK

UNBookPaymentComponent props:

Name	Type	Required	Description
customerToken	string	YES	A Unit Customer token.
accountId	string	NO	Unit account id. The account from which money is being sent.
counterPartyAccountId	string	NO	Unit account id. The account which will receive money.
counterPartyName	string	NO	Name of the counterparty. This is the name that will be displayed in the Book Payment UI during the transfer.
isSameCustomer	boolean	NO	Stating whether both accounts belong to the same customer. Allows fetching additional information about the counterparty account. Default "false"
isAutoFocus	boolean	NO	Auto-focus the money input field once the component is mounted. Default false
initialStageBackButton	boolean	NO	An action button at the first stage of the payment flow. Default false
finalStageDoneButton	boolean	NO	An action button at the final stage of the payment flow. Default false
theme	string	NO	A URL that specifies the UI configuration.
language	string	NO	A URL that specifies the language configuration.
onPaymentCreated	(bookPayment: UNBookPaymentData) => void	NO	Callback for the created bookPayment.
onInitialStageBackButtonClicked	() => void	NO	Occurs when the initial stage back button is clicked.
onFinalStageDoneButtonClicked	() => void	NO	Occurs when the final stage done button is clicked.
onLoad	(response: UNOnLoadResponse<[UNAccountData]>) => void	NO	Callback for handling onload event, also usable for error handling.

Example:

import React from 'react';
import { UNBookPaymentComponent, UNBookPaymentData, UNAccountData} from 'react-native-unit-components';

export default function YourComponent() {
  return (
    <UNBookPaymentComponent
      customerToken={/*Customer token here*/}
      accountId={'1105561'}
      counterPartyAccountId={'1105562'}
      counterPartyName={'Peter Parker"'}
      isSameCustomer={true}
      onPaymentCreated={(bookPayment: UNBookPaymentData) => { console.log(bookPayment) }}
      onLoad={(response: UNOnLoadResponse<[UNAccountData]>) => { console.log(response) }}
    />
  );
}

Android SDK

Component name: UNBookPaymentComponent

getBookPaymentComponent parameters:

Name	Type	Required	Description
accountId	String	NO	Unit account id.
counterpartyAccountId	String	NO	Unit account id. The account which will receive money.
counterpartyName	String	NO	Name of the counterparty. This is the name that will be displayed in the Book Payment UI during the transfer.
additionalSettings	UNBookPaymentViewSettingsInterface	NO	Additional settings unique for this component
theme	String	NO	A URL that specifies the UI configuration.
language	String	NO	A URL that specifies the language configuration.
callbacks	UNBookPaymentComponentCallbacks	NO	Component's Callbacks sealed class

UNBookPaymentComponentCallbacks

The callbacks parameter for UNBookPaymentComponent is of the following type:

typealias UNBookPaymentComponentCallbacks = (callback: UNBookPaymentComponentCallback) -> Unit

The UNBookPaymentComponentCallback is sealed class that has the following callbacks that you can receive from a BookPayment component:

sealed class UNBookPaymentComponentCallback {
    data object OnInitialStageBackButtonClicked : UNBookPaymentComponentCallback()
    data object OnFinalStageDoneButtonClicked : UNBookPaymentComponentCallback()
    data class OnPaymentCreated(val data: UNBookPaymentData): UNBookPaymentComponentCallback()
    data class OnLoad(val onLoadResponse: Result<List<UNAccountData>>): UNBookPaymentComponentCallback()
}

To get the BookPayment Component fragment, call the getBookPaymentComponent method of UnitComponentsSdk.manager.ui.views.

Example:

import android.os.Bundle
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import android.widget.LinearLayout
import androidx.fragment.app.Fragment
import co.unit.un_components.api.UnitComponentsSdk
import co.unit.un_components.common.builders.UNBookPaymentViewSettingsBuilder
import co.unit.un_components.common.enums.UNBookPaymentComponentCallback
import co.unit.un_components.components.UNBookPaymentView

class BookPaymentFragment : Fragment(){
    override fun onCreateView( inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View? {

        private var unBookPaymentComponent: UNBookPaymentComponent? = null

        unBookPaymentComponent = UnitComponentsSdk.manager.ui.views.getBookPaymentComponent(
            accountId = YOUR_ACCOUNT_ID,
            counterPartyAccountId = YOUR_COUNTER_PARTY_ACCOUNT_ID,
            counterPartyName = YOUR_COUNTER_PARTY_NAME,
            theme = YOUR_THEME_URL,
            language = YOUR_LANGUAGE_URL
        ) { callback ->
            when(callback) {
                is UNBookPaymentComponentCallback.OnInitialStageBackButtonClicked -> handleInitialStageBackButtonClicked()
                is UNBookPaymentComponentCallback.OnFinalStageDoneButtonClicked -> handleFinalStageDoneButtonClicked()
                is UNBookPaymentComponentCallback.OnPaymentCreated -> handlePaymentCreated(callback.data)
                is UNBookPaymentComponentCallback.OnLoad -> handleOnLoad(callback.onLoadResponse)
            }
        }

        val fragmentLayout = inflater.inflate(R.layout.FILE_NAME, container, false)
        childFragmentManager.beginTransaction()
            .replace(R.id.CONTAINER_NAME, unBookPaymentComponent as Fragment)
            .commitNow()
        return fragmentLayout
    }
    ...
    // Events handlers
    ...

The additionalSettings parameter for UNBookPaymentComponent has this attribute:

UNBookPaymentViewSettingsInterface

Name	Type	Default Value	Description
isSameCustomer	Boolean	false	Stating whether both accounts belong to the same customer. Allows fetching additional information about the counterparty account. Default false.
isAutoFocus	Boolean	false	Auto-focus the money input field once the component is mounted.
initialStageBackButton	Boolean	false	An action button at the first stage of the payment flow.
finalStageDoneButton	Boolean	false	An action button at the final stage of the payment flow.

You can use UNBookPaymentViewSettingsBuilder() to create an instance of the interface and define your additional settings.

val additionalSettings = UNBookPaymentViewSettingsBuilder()
    .isSameCustomer(...)
    .isAutoFocus(...)
    .initialStageBackButton(...)
    .finalStageDoneButton(...)

unBookPaymentComponent = UnitComponentsSdk.manager.ui.views.getBookPaymentComponent(
    accountId = YOUR_ACCOUNT_ID,
    counterPartyAccountId = YOUR_COUNTER_PARTY_ACCOUNT_ID,
    counterPartyName = YOUR_COUNTER_PARTY_NAME,
    additionalSettings = additionalSettings,
    theme = YOUR_THEME_URL,
    language = YOUR_LANGUAGE_URL
)

IOS SDK

Component name: UNBookPaymentComponent

Configuration parameters:

Name	Type	Required	Description
accountId	String	NO	Unit account id. The account from which money is being sent.
counterpartyAccountId	String	NO	Unit account id. The account which will receive money.
counterpartyName	String	NO	Name of the counterparty. This is the name that will be displayed in the Book Payment UI during the transfer.
isSameCustomer	Bool	No	Stating whether both accounts belong to the same customer. Allows fetching additional information about the counterparty account. Default false.
additionalSettings	UNBookPaymentViewSettingsProtocol	NO	Advanced optional settings.
callbacks	UNBookPaymentComponentCallbacks	NO	Callbacks to interact with the Book Payment component.
theme	String	NO	A URL that specifies the UI configuration.
language	String	NO	A URL that specifies the language configuration.

The callbacks parameter for UNBookPaymentComponent is of the following type:

public typealias UNBookPaymentComponentCallbacks = (_ callback: UNBookPaymentComponentCallback) -> Void

The UNBookPaymentComponentCallback is an enum that has the following callbacks that you can receive from a Book Payment component:

public enum UNBookPaymentComponentCallback {
    case onPaymentCreated(data: UNBookPaymentData)
    case unitOnLoad(result: Result<[UNAccountData], UNError>)
    case onInitialStageBackButtonClicked
    case onFinalStageDoneButtonClicked
}

To get the Book Payment Component view, call the getBookPaymentComponent method of UnitSDK.manager.ui.views.

Example:

import UIKit
import UNComponents
import SnapKit

class BookPaymentScreen: UIViewController {

    fileprivate lazy var bookPaymentComponent: UNBookPaymentView = {
        let unViews = UnitSDK.manager.ui.views
        let bookPaymentComponent = unViews.getBookPaymentComponent(accountId: "1105561", counterpartyAccountId: "1105562", counterpartyName: "Peter Parker") { callback in
            switch callback {
            case .onInitialStageBackButtonClicked:
                print("Back button clicked on the initial stage")
            case .onFinalStageDoneButtonClicked:
                print("Done button clicked on the final stage")
            case .onPaymentCreated(let data):
                print("[Book Payment Screen] onPaymentCreated: \(data)")
            case .unitOnLoad(let result):
                switch result {
                case .success(let account):
                    print("Success Loading Book Payment. account: \(account)")
                case .failure(let error):
                    switch error {
                    case .onLoad(let onLoadErrors):
                        print("Fail to load Book Payment component. Errors:")
                        for loadError in onLoadErrors {
                            print("Status: \(loadError.status); Title:\(loadError.title)")
                        }
                    default:
                        print("Error: \(error.description)")
                    }
                }
            }
        }
        return bookPaymentComponent
    }()

    override func viewDidLoad() {
        super.viewDidLoad()
        view.backgroundColor = .white

        // add the book payment component as a subview - using SnapKit for example
        view.addSubview(bookPaymentComponent)
        bookPaymentComponent.snp.makeConstraints { make in
            make.top.equalTo(view.safeAreaLayoutGuide.snp.top)
            make.bottom.equalTo(view.safeAreaLayoutGuide.snp.bottom)
            make.leading.trailing.equalToSuperview()
        }
    }
}

The additionalSettings parameter for UNBookPaymentComponent is of the following type:

UNBookPaymentViewSettingsProtocol:

Name	Type	Default Value	Description
isAutoFocus	Bool	false	Auto-focus the money input field once the component is mounted.
initialStageBackButton	Bool	false	An action button at the first stage of the payment flow.
finalStageDoneButton	Bool	false	An action button at the final stage of the payment flow.

You can use UNBookPaymentViewSettingsBuilder to create an instance of the protocol and define your additional settings.

Example:

let additionalSettings = UNBookPaymentViewSettingsBuilder()
    .isAutoFocus(true)
    .initialStageBackButton(true)
    .finalStageDoneButton(true)

let unViews = UnitSDK.manager.ui.views
let bookPaymentComponent = unViews.getBookPaymentComponent(accountId: "1105561", counterpartyAccountId: "1105562", counterpartyName: "Peter Parker", additionalSettings: additionalSettings)