Getting started

This API documentation is specifically designed for businesses looking to use PAYFI as an underline BNPL provider enabling businesses to extend BNPL payments to other merchants' websites, mobile apps, or in your stores.

You need to request access to use this API endpoint. Please reach out to [email protected].

Overview

Payfi offers a white label integration for merchants that want to take full control of the user experience in accordance with their corporate identity, and this section walks you through the end-to-end user journey.
You probably have your test credentials already, otherwise, you can get them on the test environment page.

Payfi offers a broad selection of integration options and features to bring a seamless, customized and unique experience to customers on online platforms as well as offline solutions. This will help you to extend these options to other businesses as well.

Authentication

All endpoints require an API key which will be shared with you by the sales team upon request.

Onboarding Channels

API Onboarding
Distributed Channel Onboarding (Onboarding via bank account number)

API Onboarding

This process is divided into the following sections:

Onboarding
Checkout
Settlement
Repayment

1. Onboarding

There are two categories of Payfi onboarding, which are the merchant onboarding and the customer onboarding. The customer onboarding is further divided into two: Payfi Step Process (this involves calling Payfi in steps) and Payfi Bigbang (this involves putting all Payfi steps into one API call).

a. Merchant onboarding

This is for onboarding the business on Payfi. This can be done using the merchant onboarding endpoint. After this has been completed, the merchant can request for his API credentials.

Authentication: This call uses the general Payfi auth flow
API and make a HTTP POST endpoint + /v1/unternehmen/merchant/onboarding with the header content-type: application/json

{
   "name": "My business name"
}

b. Customer onboarding

I. Payfi step process

Account creation - Here we collect customers’ basic information for registration. This endpoint also allows you to collect the entire onboarding when going through the big bang route, but for the step process, you can control how much information you wish to pass at this stage.

Authentication: This call uses the general Payfi auth flow

HTTP POST endpoint + /v1/unternehmen/onboarding
header
content-type: application/json
payfi-sec-key: your-sec-key

{
   "firstName": "larry",
    "lastName": "next",
    "otherName": "Okoro",
    "bvn": "59490289323",
    "email": "[email protected]",
    "phone": "09050401212",
    "eligibility": "100000",
    "salaryDay": "20", 
    "gender": "male",
    "password":"admin",
    "pin":"1234",
    "dob": "2000-06-14",
    "stateOfOrigin": "Delta",
    "maritalStatus": "Married",
    "educationalLevel": "graduate",
    "numberOfChildren":1,
    "fullOnboarding": false
}

Send email verification token - This endpoint allows us to send verification email to the email address provided by the user for verification.

Authentication: This call uses the general Payfi auth flow

HTTP POST endpoint + /v1/unternehmen/send-email-otp
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
 "userId": string
}

Verify email token - This API is basically for verifying the token sent to the customer.

HTTP POST endpoint + /v1/unternehmen/verify-email-otp
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVC"
}

Add employment details - This endpoint is used to submit the user's employment information.

HTTP POST endpoint + /v1/unternehmen/employement-details
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
    "employerName": string,
    "monthlyIncome": number,
    "employerPhonenumber": string,
    "employerAddress": string,
    "employerPayDay": number,
    "state": string,
    "lga": string,
    "sector": string,
    "industry": string,
    "startDate": dtring,
    "employmentStatus": string,
    "employmentEmail": string
    "userId": string
}

Create Address - This endpoint is used to submit the user's contact address information.

HTTP POST endpoint + /v1/unternehmen/address
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
    "addressType": string,
    "city": string,
    "street": string,
    "houseNo": string,
    "state": string,
    "country": string,
    "residentialStatus": string,
    "lga": string,
    "dateAtResidentialAddress": string,
    "image": string,
    "userId": string
}

Verify BVN - This endpoint is used to verify the BVN details of the user. This is to ensure that the user is the owner of the account.
Submit a request to add BVN with the correct date of birth attached to the BVN.
An OTP will be sent to the phone number associated with the BVN.
Send a request to validate the OTP.

HTTP POST endpoint + /v1/unternehmen/verify-bvn
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
    "userId": string,
    "bvn": string,
    "otp": ""
}

{
    "userId":string,
    "bvn": string,
    "otp": string
}

Connect bank - We require customers to connect their salary account, and we enable this connection via Mono (a third party service).
For us to seamlessly extend this functionality, the integrations team ([email protected]) would be providing a unique public key which you would have to use to enable customer bank connection.

NOTE: it is important that the customer knows that this account to be connected should be his active salary account (Naira Accounts Only)

Connection Steps:

Display connection widget
Follow the steps on MONO with the key provided to you.
On successful connection call Payfi Connect endpoint with the reference

HTTP POST endpoint + /v1/unternehmen/verify-mono-code
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
    "userId": string,
    "code":string
}

Add payment card with paystack - Here white-labeled partner sends a request to tokenize and we return to them a paystack checkout link.

STEPS:
I. Initialize card: An endpoint where the user adds his card details to initiate a payment. The response from this will determine the next step of the card process

HTTP POST endpoint + /v1/unternehmen/init-card
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
    "userId": string,
     "amount": number,
    "cardNumber": string,
    "cvv": string,
    "expireMonth": string,
    "expireYear": string,
    "pin": string
}

II. Input card OTP: If the initialized card endpoint request for the user’s OTP, then this endpoint will be called.

HTTP POST endpoint + /v1/unternehmen/add-card-otp
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
  "otp":string,
  "reference": string
}

III. Add card phone: If the initialized card endpoint requests for the user phone number, then this endpoint will be called.

HTTP POST endpoint + /v1/unternehmen/add-card-phone
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
  "phone":string,
  "reference": string
}

IV. Verify card: This verifies that the card can be debited which is the final stage of tokenizing a card.

HTTP POST endpoint + /v1/unternehmen/verify-card*
header
content-type: application/json**
payfi-sec-key: your-sec-key
userId: onboarded userId

{
  "reference": string
}

Add ID Card - This endpoint is used to upload the user’s valid means of identification.
Document must be any of the following: National ID card, Driver’s License, Voters Card, NIN Slip, or an International Passport.
This is actually a form data which accepts key-value pairs.

HTTP POST endpoint + /v1/unternehmen/upload-ID
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
 "file":binary,
 "userId":string,
 "documentNumber":string,
 "issueDate":string,
 "expireDate": string,
 "documentType": string
}

Next of kin - This endpoint is used to submit user’s for next of kin information.

HTTP POST endpoint + /v1/unternehmen/add-nok
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
     "userId": string,
      "title": string,
      "relationship": string,
      "firstName": string,
      "otherName": string,
      "lastName": string,
      "phoneNumber": string,
      "email":string,
      "address": string,
      "country": string,
      "state": string,
      "town": string
}

Check compliance - This endpoint confirms if a user has complete information to get his/her eligibility.
N.b: This endpoint can be called at any point during/after the onboarding information has been provided by the user.

HTTP POST endpoint + /v1/unternehmen/check-eligibility
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
    "userId": string
}

Get eligibility - This endpoint returns an array of offers for the customer.

HTTP POST endpoint + /v1/unternehmen/get-eligibility
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
    "userId": string,
    "amount":number
}

II. Payfi Bigbang
If you prefer skipping steps and just call everything in one API call, this is the flow for you.

We have made an effort to squatch all the steps and processes into one API call, this means you will handle the entire onboarding process and verification on your end, and when all documents are ready you just have to call one endpoint (the onboarding endpoint).

NOTE: This call will fail if any of the processes fails however the basic account details of the customer will be registered

HTTP POST endpoint + /v1/unternehmen/onboarding
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
    "firstName": string,
    "lastName": string,
    "otherName": string,
    "bvn": string,
    "email": string,
    "phone": string,
    "eligibility": string,
    "salaryDay": number,
    "gender": string,
    "password": string,
    "pin": string,
    "dob": string,
    "stateOfOrigin": string,
    "maritalStatus": string,
    "educationalLevel": string,
    "fullOnboarding": boolean,
    "address": {
        "addressType": string,
        "city": string,
        "street": string,
        "houseNo": string,
        "state": string,
        "country": string,
        "residentialStatus": string,
        "lga": string,
        "dateAtResidentialAddress": string,
        "image": string
    },
    "employmentDetails": {
        "employerName": string,
        "monthlyIncome": string,
        "employerPhonenumber": string,
        "employerAddress": string,
        "employerPayDay": number,
        "state": string,
        "lga": string,
        "sector": string,
        "industry": string,
        "startDate": string,
        "employmentStatus": string,
        "employmentEmail": string
    },
    "monoReference": string,
    "ID": {
        "url": string,
        "documentNumber": string,
        "issueDate": string,
        "expireDate": string,
        "documentType": string
    },
    "nextOfKin": {
        "title": string,
        "relationship": string,
        "firstName": string,
        "otherName": string,
        "lastName": string,
        "phoneNumber": string,
        "email": string,
        "address": string,
        "country": string,
        "state": string,
        "town": string
    },
    "merchantId": string

}

2. Checkout/Creating a loan

The APIs below shows the steps to take when a whitelabel wants to make use of the BNPL payment for a customer. Please note that this APIs must be consumed in the order they are listed in this document.

Initialize loan process: This API is used to start the loan process. A meta field which is optional can be used to pass the customer order items.

HTTP POST endpoint + /v1/unternehmen/initialize/pk_bbaaef25-f590-4331-b382-1dd83e2a820e
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
    "reference": "47376317381912121129051915",
    "amount":30000,
    "tenor":3,
    "meta": {
        "order":[
            {
                "name":"addidas shoe",
                "id":"sku23322",
                "category":"men shoes"
            }
        ]
    }
   
}

Get Eligibility - This API returns an offer or an array of offers with the repayment schedule for a customer if the customer is eligible.

HTTP POST endpoint + /v1/unternehmen/check-eligibility*
header
content-type: application/json**
payfi-sec-key: your-sec-key
userId: onboarded userId

{
    "userId": "88020175-d57c-4f4c-a624-508aba7d464c",
    "code":""
}

After calling the get eligibility endpoint, use the add card endpoints to make payment for the first instalment. The payment reference you get here will be useful in the next API.
Create Loan - This API creates a loan for a customer if the above APIs were successful.

{
    "code": 5,
    "userId": "47e7c2de-72ec-47f1-a2da-9db27aab4296",
    "pin": "1234",
    "paymentReference": "PAYSTACK_TX_REF-1656885469000"
}

3. Settlement

Where a Whitelabel client is a Payment Gateway, we settle them and they settle their merchants, as we will not be onboarding their merchants.

Where a Whitelabel client is a merchant aggregator, the merchant aggregator will have a single merchant account with Payfi where Payfi will settle. This will ensure that merchant management is done by the Merchant aggregator and not Payfi.

Bulk settlement is done at settlement intervals.

3. Repayment

Payfi is responsible for collecting all repayments. However, repayment notification is done via an API/Webhook for both successful and unsuccessful repayments.

Get Repayment - This endpoint is called to fetch the repayment tenor of the user.

HTTP POST endpoint + /v1/unternehmen/get-repayment
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
    "tenor":number,
    "totalAmount": number
}

Get Loan status - This endpoint is to get the loan status of the user.

HTTP POST endpoint + /v1/unternehmen/loan-status
header
content-type: application/json
payfi-sec-key: your-sec-key
userId: onboarded userId

{
  "loanId":string
}