@payhippo/embedded-credit-sdk

Embedded Credit Widget

Power your platforms Buy Now Pay Later credit flow

✨ Features

• 🌈 Easy to use widget for web applications.
• 📦 Minimum integration needed.
• 🛡 Customer Data is securely transmitted.
• ⚙️ Connects to dashboard for further ease of management.

🖥 Environment Support

• Modern browsers and Internet Explorer 11
• Integrates easily with WebView for React Native
• Direct SSR, React Native and Flutter support TBD

⌨️ Installation

$ npm install @payhippo/embedded-credit-sdk

Or if you prefer using Yarn:

$ yarn add @payhippo/embedded-credit-sdk

🔨 Usage

1. Import the widget

import PayHippo from '@payhippo/embedded-credit-sdk';
import '@payhippo/embedded-credit-sdk/dist/styles.css';

2. Initialization

The init method is asynchronous and handles the client authentication process.

import React, { useEffect } from 'react';
import PayHippo from '@payhippo/embedded-credit-sdk';
import '@payhippo/embedded-credit-sdk/dist/styles.css';

const CustomHook = () => {
    ...

    const INIT_PAYLOAD = {
        partnerId: 'VALID_PARTNER_ID',
        secretKey: 'VALID_SECRET_KEY',
    }

    useEffect(() => {
        const initializePayHippoClient = async () => {
            await PayHippo.init(INIT_PAYLOAD);
        };

        initializePayHippoClient();
    }, [])

    ...
}

3. Trigger the Widget to Open with the customer's data

Opening the widget with the customer data will verify their data and generate a credit offer.

...
import React from 'react';
import PayHippo from '@payhippo/embedded-credit-sdk';
import '@payhippo/embedded-credit-sdk/dist/styles.css';

const MyComponent: React.FC = () => {
    ...
    const CUSTOMER_DATA = {
        businessLocation: {
            address: '123 test street',
            city: 'lagos',
            country: 'nigeria',
            state: 'lagos',
            zipCode: '123-123',
        },
        businessOwner: {
            birthDate: 1234567891,
            firstName: 'Test',
            gender: 'FEMALE',
            lastName: 'X',
        },
        businessName: 'Test Business',
        businessType: 'COMPUTER_SALES',
        bvn: '20021221121',
        cartAmount: 200000,
        customerActivationDate: 1597590921,
        customerCreatedDate: 1597590921,
        email: '[e-mail]',
        phoneNumber: '2346505553495', // Use this number while Testing | Token = 123456
        transactionHistory: {
            totalAmount: 1000000,
            totalCount: 5,
        },
    };

    PayHippo.openWidget(CUSTOMER_DATA);

    ...
}

...

Advanced Configurations

There are optional values that can be passed during the initilization step.

import React, { useEffect } from 'react';
import PayHippo from '@payhippo/embedded-credit-sdk';
import '@payhippo/embedded-credit-sdk/dist/styles.css';

const CustomHook = () => {
    ...

    const INIT_PAYLOAD = {
        partnerId: 'VALID_PARTNER_ID',
        secretKey: 'VALID_SECRET_KEY',
        env: 'PRODUCTION', // default is 'TEST'
        logoUrl: '',
        onCreditAccept: payload => {},
        onCreditRequest: payload => {},
        onClose: () => {},
        onError: payload => {},
        onInitComplete: () => {},
        onOTPSent: () => {},
        onOpen: () => {},
        onOTPSent: () => {},
    }

    useEffect(() => {
        const initializePayHippoClient = async () => {
            await PayHippo.init(INIT_PAYLOAD);
        };

        initializePayHippoClient();
    }, [])

    ...
}

Optional Customer Data

There are optional customer values that can be provided.

import React from 'react';
import PayHippo from '@payhippo/embedded-credit-sdk';
import '@payhippo/embedded-credit-sdk/dist/styles.css';

...

const MyComponent: React.FC = () => {
    ...

    const CUSTOMER_DATA = {
        ...,
        cac: 'B12312312',
        referenceId: 'XXXXXXXX',
    };

    Payhippo.openWidget(CUSTOMER_DATA);

    ...
}
...

Schemas

Initialization Payload

Click to View

{
    env: {
        enum: ['PRODUCTION', 'TEST'],
        required: false,
        type: String,
    },
    logoUrl: { required: false, type: String },
    onClose: { required: false, type: Function },
    onCreditAccept: { required: false, type: Function },
    onCreditRequest: { required: false, type: Function },
    onError: { required: false, type: Function },
    onInitComplete: { required: false, type: Function },
    onOTPSent: { required: false, type: Function },
    onOpen: { required: false, type: Function },
    partnerId: { required: true, type: String },
    secretKey: { required: true, type: String },
}

Customer Data

Click to View

{
    businessLocation: {
        address: { required: true, type: String },
        city: { required: true, type: String },
        country: { required: true, type: String },
        state: { required: true, type: String },
        zipCode: { required: false, type: String },
    },
    businessName: { required: true, type: String },
    businessOwner: {
        birthDate: {
            // Unix Timestamp
            length: { max: 10, min: 10 },
            required: true,
            type: Number,
        },
        firstName: { required: true, type: String },
        gender: {
            enum: ['FEMALE', 'MALE'],
            required: true,
            type: String,
        },
        lastName: { required: true, type: String },
    },
    businessType: {
        enum: [
            'BAKERY',
            'COMPUTER_SALES',
            'PETROL_DIESEL_SUPPLY',
            'E_COMMERCE',
            'ELECTRIC_APPLICANCE_SALES',
            'FARM_AGRICULTURE',
            'FAST_MOVING_CONSUMER_GOODS',
            'GROCERY_SUPPLY',
            'LUXURY_GOODS',
            'MOBILE_MONEY',
            'OIL_GAS',
            'ONLINE_BILLING_PLATFORM',
            'PHARMACY',
            'PHONE_SALES_SMS',
            'SUPER_MARKET',
            'TELECOMMUNICATIONS',
            'TEXTILE_DESIGNS',
            'TRAVEL_AGENCY',
            'OTHER',
        ],
        required: true,
        type: String,
    },
    bvn: {
        length: { max: 11, min: 11 },
        required: true,
        type: String,
    },
    cac: { required: false, type: String },
    cartAmount: { 
        required: true, 
        type: Number, 
        size: { min: 1000 }
    },
    customerActivationDate: {
        // Unix Timestamp
        length: { max: 10, min: 10 },
        required: true,
        type: Number,
    },
    customerCreatedDate: {
        // Unix Timestamp
        length: { max: 10, min: 10 },
        required: true,
        type: Number,
    },
    email: { required: true, type: String },
    phoneNumber: {
        length: { max: 13, min: 13 },
        required: true,
        type: String,
    },
    referenceId: { required: false, type: String },
    transactionHistory: {
        totalAmount: { required: true, type: Number },
        totalCount: { required: true, type: Number },
    },
}

Callback Payload Types

onCreditAccept

Click to View

enum OnCreditAcceptStatus {
    CREDIT_ACCEPT_SUCCESS = 'CREDIT_ACCEPT_SUCCESS'
}

type OnCreditAccept = {
    data: {
        creditAmount: string,
        creditRequestId: string;
    };
    message: string;
    status: OnCreditAcceptStatus;
}

...

onCreditAccept(payload: OnCreditAccept) => {...}

...

onCreditRequest

Click to View

enum OnCreditRequestStatus {
    CREDIT_REQUEST_SUCCESS = 'CREDIT_REQUEST_SUCCESS'
}

type OnCreditRequest = {
    data: {
        businessName: string,
        creditAmount: string,
        creditRequestId: string,
        createdAt: number,
        isCreditApproved: boolean,
        originalFeeAmount: string,
        phoneNumber: string,
        repaymentAmount: string,
        repaymentDate: number,
    };
    message: string;
    status: OnCreditRequestStatus;
}

...

onCreditRequest(payload: OnCreditRequest) => {...}

...

onError

Click to View

enum ErrorStatus {
    CREDIT_ACCEPT_ERROR = 'CREDIT_ACCEPT_ERROR',
    CREDIT_REQUEST_ERROR = 'CREDIT_REQUEST_ERROR',
    MISSING_INIT_DATA = 'MISSING_INIT_DATA',
    MISSING_CUSTOMER_DATA = 'MISSING_CUSTOMER_DATA'
}

type OnError = {
    data: {
        creditRequestId?: string;
        missingKeys?: string[];
    };
    message: string;
    status: ErrorStatus;
}

...

onError(payload: OnError) => {...}

...

Using OTP on Test Environment

While testing the widget integration use the following test phone number and OTP token:

Customer Test Phone Number

2346505553495

Test OTP Token

123456

This number will only work when env is set to TEST. Otherwise, an OTP request will be made to the provided customer phone number.

Authors

• Uche Nnadi - Initial work -