@ravenpay/bankbox-me-sdk

Bankbox Me SDK Documentation

Table of Contents

• Introduction
• Installation
• Quick Start
• Core Concepts
  • BankboxManager
  • Event System
• API Reference
  • BankboxManager Configuration
  • Methods
  • Events
• Troubleshooting

Introduction

Bankbox Me SDK is a flexible payment integration solution that allows you to seamlessly embed payment functionality into your web applications. It provides a simple API for initializing payment widgets, handling payment flows, and managing the payment experience for your users.

Installation

# Using npm
npm install @ravenpay/bankbox-me-sdk

# Using yarn
yarn add @ravenpay/bankbox-me-sdk

Quick Start

Here's a basic implementation to get started with Bankbox SDK:

import React from 'react'
import BankboxManager from '@ravenpay/bankbox-me-sdk'

const PaymentComponent = () => {
  // Initialize the Bankbox manager
  const bankbox = new BankboxManager({
    appName: 'your-app-name',
    environment: 'production', // or 'development'
    widgetOptions: {
      isPersistent: true,
    },
    onSuccess: (data) => {
      console.log('Payment succeeded:', data)
    },
    onLoad: () => {
      console.log('Bankbox is ready')
    },
    onError: (error) => {
      console.error('An error occurred:', error)
    },
  })

  // Function to initiate payment
  const handlePayment = () => {
    bankbox.open({
      amount: 1000, // Amount in smallest currency unit
    })
  }

  return (
    <div>
      <button onClick={handlePayment}>Pay Now</button>

      <button
        onClick={() =>
          alert(
            `Bankbox is ${
              bankbox.isBluethoothConnected ? 'connected' : 'disconnected'
            }`
          )
        }
      >
        Check Connection Status
      </button>
    </div>
  )
}

export default PaymentComponent

Legacy CRA

If you encounter issues running the SDK with create-react-app (CRA), which has become obsolete, you can use the following approach. This method accesses the bundle file directly, bypassing React auto-import.

Here's a basic implementation to get started with Bankbox SDK:

import React from 'react'
import BankboxManager from '@ravenpay/bankbox-me-sdk/bundles/index.esm.js'

// The rest of the implementation follows...

Core Concepts

BankboxManager

The BankboxManager is the main entry point for the SDK. It handles initialization, configuration, and provides methods to control the payment flow.

Event System

Bankbox uses an event system to handle communication between your application and the payment widget. This enables you to receive updates and send data to the payment flow.

API Reference

BankboxManager Configuration

When initializing the BankboxManager, you can provide the following configuration options:

Option	Type	Description	Required	Default
appName	string	Your application's identifier	Yes	-
environment	string	'development' or 'production'	Yes	-
containerId	string	ID of the container element	No	-
widgetOptions	object	Configuration for the payment widget	No	{}
onSuccess	function	Callback when payment succeeds	No	-
onLoad	function	Callback when widget loads	No	-
onFail	function	Callback when payment fails	No	-
onError	function	Callback when an error occurs	No	-

Widget Options

Option	Type	Description	Default
isPersistent	boolean	Keep widget instance after closure	false
theme	string	'light' or 'dark'	'light'
paymentMethod	string	Default payment method	-

Methods

open(options)

Opens the payment widget with the specified options.

Parameters:

• options (object):
  • amount (number): The payment amount in the smallest currency unit

Returns: Boolean - true if the widget was opened successfully, false otherwise

const opened = bankbox.open({ amount: 1000 })
if (opened) {
  console.log('Payment widget opened successfully')
}

close()

Closes the payment widget.

bankbox.close()

isBluethoothConnected

Checks if the SDK is properly connected and ready to use, this value returns a boolean.

Returns: Boolean - true if connected, false otherwise

if (bankbox.isBluethoothConnected) {
  console.log('Bankbox is connected and ready')
} else {
  console.log('Bankbox is not connected yet')
}

Events

The SDK allows you to handle various payment events:

Available Events

The SDK provides constants for common events that you can listen for in your callbacks:

• onSuccess: Called when payment completes successfully
• onFail: Called when payment fails
• onError: Called when an error occurs
• onLoad: Called when the Bankbox widget is fully loaded

Updating Payment Data

You can update the payment details using events. For example, you can update the payment amount dynamically based on user input.

TIP: You can hook this to your input element's onChange event.

// Updating payment amount
bankbox.$event.emit(bankbox.constants.sdkPaymentData, { amount: 1500 })

Here's an example of how to use the onChange event to update the payment amount:

import React, { useState } from 'react'
import BankboxManager from '@ravenpay/bankbox-me-sdk'

const PaymentComponent = () => {
  const [amount, setAmount] = useState(1000)
  const bankbox = new BankboxManager({
    appName: 'your-app-name',
    environment: 'production',
    widgetOptions: {
      isPersistent: true,
    },
    onSuccess: (data) => {
      console.log('Payment succeeded:', data)
    },
    onLoad: () => {
      console.log('Bankbox is ready')
    },
    onError: (error) => {
      console.error('An error occurred:', error)
    },
  })

  const handleAmountChange = (event) => {
    const newAmount = parseInt(event.target.value, 10)
    setAmount(newAmount)
    bankbox.$event.emit(bankbox.constants.sdkPaymentData, { amount: newAmount })
  }

  const handlePayment = () => {
    bankbox.open({ amount })
  }

  return (
    <div>
      <input
        type="number"
        value={amount}
        onChange={handleAmountChange}
        placeholder="Enter amount"
      />
      <button onClick={handlePayment}>Pay Now</button>
    </div>
  )
}

export default PaymentComponent

Troubleshooting

Widget Not Appearing

Ensure that:

• You've provided a valid appName and environment
• The container element exists (if containerId is specified)

Payment Processing Issues

If payments aren't processing correctly:

• Verify the amount is in the correct format (smallest currency unit)
• Ensure all required payment fields are provided
• Check your callbacks are properly handling success and error cases
• Check that isBluethootConnected returns true before attempting to process payment

Best Practices

• Always check connection status before initiating payment flows
• Implement proper error handling in your callbacks
• Test thoroughly in development before moving to production
• Provide clear feedback to users during or after the payment process
• Hooking into the onSuccess & onFailure would allow take custom actions in your application based on transaction status