How we work

Start building for the invisible economy! Peere Network revolutionizes how money moves by using your identity instead of cards or cash.

What is Peere Network?

Identity-Based Payments

Peere is a payment network where payments are made based on identity (palm scanning, biometric recognition, and invisible systems) rather than traditional EDC (Everyday Carry) items like credit cards, cash, or phones. Built for the invisible economy, We represent an innovative alternative to established physical payment networks like Visa and Mastercard.

The Players

Banks

Financial institutions that manage customer accounts and authorize payments

Merchants

Businesses that want to receive payments from customers

Providers

Payment processors (like Paystack, Flutterwave, or Stripe) who onboard merchants to use Peere

This creates three distinct use cases: Bank APIs, Merchant APIs, and Provider APIs.

Three Fundamental Questions We Answer

1. As a Merchant: How can I receive money from my customers?

Learn how to establish billing agreements and process payments seamlessly

2. As a Bank: How can my customers pay using Peere?

Discover how to enable identity-based payments for your customers

3. As a Provider: How can my merchants receive money from their customers?

Understand how to onboard merchants and manage payments on their behalf

1. As a Merchant, How can I receive money from my customers?

Receiving money from your customers is now significantly easier and more secure than traditional methods.

The Peere Payment Process

Establish Agreement

For one-time payments, you can initiate payment with a customer’s lookupPhrase, which requires the customer’s approval through their bank. To receive payments recurringly or on-demand, you need to establish a digital agreement (represented by an encrypted string called an agreementPhrase) with your customer through their bank. This agreement specifies how you want to bill them; whether one-time, recurring, or on-demand when they use your service.

Customer Responds

The customer responds within minutes via webhook (sample response), either accepting or denying your proposal. Approval can be either of the following:

approve_once

Requires approval for each transaction

approve_recurring

Grants permission for future billing (trusted merchants only)

Step-by-Step Implementation

Step 1: One-Time Payment
Step 2: Create Agreement
Step 3: Bill Customer

Payment Initiated with Lookup Phrase

Use this flow for a one-time payment that requires the customer’s approval through their bank. This flow is independent of the agreement-based flow below.

Option A: Merchant Initiated with Lookup Phrase

Prompt customers through their bank app using their lookupPhrase. lookupPhrase can be gotten from any of the following methods:

Method 1: Device Lookup

Use device ID obtained when customers visit your website/app http POST /v1/customer/device/lookup

Method 2: Email Lookup

Use customer’s email to find associated banks and lookupPhrase http GET /v1/customer/banks

Banks link customer devices to their lookup phrases for seamless merchant interaction.

For customers whose banks haven’t onboarded to Peere yet, use alternative payment methods while we work to onboard all banks in our regions of operation.

Initiate the one-time payment:

{
  "lookupPhrases": ["customer-lookup-phrase"],
  "amount": 1500,
  "currency": "NGN",
  "description": "One-time payment requiring customer approval"
}

This one-time payment is completed only after the customer approves it through their bank.

Create Customer Decision (Establish Agreement)

Use this flow if you want recurring or on-demand payments. First establish the agreementPhrase, then bill the customer with it.

Choose the right approach based on your customer interaction flow

Option A: Customer Initiated with Agreement Phrase

Present a form during onboarding or checkout (alongside your Merchant ID, which customers can give to their bank) where customers input their agreementPhrase.

What is a Agreement Phrase?

A signed contract between you, the customer, and their bank, granting you permission to bill them based on their specified settings.

Check permissions: You can check the permissions of any agreementPhrase using this:

GET /v1/merchant/customer-decisions

Option B: Merchant Initiated with Lookup Phrase

Prompt customers through their bank app using their lookupPhrase. lookupPhrase can be gotten from any of the following methods:

Method 1: Device Lookup

Use device ID obtained when customers visit your website/app http POST /v1/customer/device/lookup

Method 2: Email Lookup

Use customer’s email to find associated banks and lookupPhrase http GET /v1/customer/banks

Banks link customer devices to their lookup phrases for seamless merchant interaction.

For customers whose banks haven’t onboarded to Peere yet, use alternative payment methods while we work to onboard all banks in our regions of operation.

Initiate the agreement:

{
  "lookupPhrases": ["customer-lookup-phrase"],
  "currency": "NGN",
  "description": "Netflix subscription - monthly billing authorization"
}

You’ll receive the customer’s decision via webhook (sample response), along with a agreementPhrase for future billing.

Next step Bill Customer

Bill Customer

After establishing an agreement, bill your customer using the agreementPhrase for recurring or on-demand payments:

{
  "agreementPhrases": ["customer-agreement-phrase"],
  "amount": 1500,
  "currency": "NGN",
  "description": "Netflix Premium - January 2024"
}

approve_once

Requires approval for each transaction

approve_recurring

Grants permission for future billing (trusted merchants only)

For Subscription Billing: Use POST /v1/billing/recurring/create to set up automated recurring payments.

Updating Billing Agreements

You can request new billing agreements from customers if you need to change billing terms by calling POST /v1/billing/intent with your updated settings.

2. As a Bank, how can my customers pay using Peere?

Your Role in the Peere Network

Banks act as the trusted intermediary between customers and merchants, managing customer identities, payment authorizations, and transaction processing. You control your customers’ payment decisions and ensure secure, compliant transactions.

Setting up your customers

Customer Onboarding
Device Linking

Customer Onboarding

First, you need to onboard your existing customers to the Peere network using /v1/bank/customers. This batch endpoint allows you to migrate customers efficiently:

{
  "customers": [
    {
      "clientRef": "string",
      "firstname": "string",
      "lastname": "string",
      "accountName": "string",
      "email": "string",
      "country": "string",
      "accountNumber": "string",
      "reference": "string"
    }
  ]
}

Device Linking

Link your customers’ devices to their unique phrases for seamless merchant interaction:

{
  "customerId": "customer_123",
  "phrase": "unique-phrase",
  "deviceId": "device_789"
}

Handling Merchant Requests

Billing Intent Notifications

When merchants want to establish billing agreements, you’ll receive Billing Intent Webhook notifications. These notifications informs you that a merchant wants your customer to decide on billing permissions. You are advised to send the customer an FCM/email notification, notifying him of the the merchant intent.

Billing Request Notifications

When merchants attempt to bill customers, you’ll receive Billing Request Webhook notifications. These notifications imforms you that a merchant wants to bill your customer. You are advised to send the customer an FCM/email notification to the customer, to either accept (in cases where permission is needed) or to notify him of such debit

Responding to Billing Intents

After receiving a Billing Intent Notification from a merchant, notify the respective customer via FCM or email based on the webhook intent. If billing requires approval, provide a UI where the customer can accept/decline billing (customer has limited time to respond, else billing will decline automatically). Else confirm that the customer has enough balance and bill accordingly. Respond using /v1/billing/intent-response:

{
  "customerId": "customer_123",
  "entityId": "merchant_456",
  "lookupPhrase": "lookup-phrase",
  "customerDecision": "approve_once | approve_recurring | deny | suspended",
  "spendingLimits": {
    "daily": 1000,
    "monthly": 5000
  },
  "blockMerchant": false
}

Responding to Billing Requests

After receiving a Billing Request Notification from a merchant, notify the customer via FCM or email that a merchant intends to bill them. The customer sets their preference through your banking interface, and you respond using /v1/billing/bank-response:

{
  "billingRequestId": "billing_123",
  "action": "approve_once | approve_recurring | deny | suspended",
  "bankTransactionId": "bank_txn_789"
}

Managing Customer Decisions

View Decisions

Monitor all customer decisions http GET /v1/bank/customer-decisions

Update Decisions

Modify existing decisions http PUT /v1/bank/customer-decisions/:id

Track Subscriptions

Monitor customer subscriptions http GET /v1/bank/customer/subscriptions

Transaction Management

Track all transactions involving your customers and get detailed transaction information for compliance and reporting.

Transaction History

http GET /v1/transaction-history

Transaction Details

http GET /v1/transaction-details

3. As a Payment Provider, how can my merchants receive money from their customers?

Your Role in the Peere Network

Providers act as intermediaries for merchants, managing their Peere integration, handling billing operations on their behalf, and maintaining merchant trust levels for enhanced capabilities.

Onboarding Your Merchants

Merchant Registration
Trust Management

Merchant Registration

Onboard your existing merchants using /v1/provider/merchants:

{
  "merchants": [
    {
      "name": "Merchant 1",
      "email": "merchant1@example.com",
      "phone": "+1234567890",
      "address": "123 Merchant St",
      "website": "https://merchant1.com"
    }
  ]
}

Trust Management

Establish and manage merchant trust levels using /v1/provider/merchant/trust. Higher trust levels unlock advanced features:

Basic

Standard features

Enhanced

Additional capabilities

Premium

Full feature access

{
  "entityId": "merchant_456",
  "trusted": true,
  "trustLevel": "basic | enhanced | premium",
  "deviceLookupEnabled": true
}

Billing Operations on Behalf of Merchants

Customer Discovery

Help merchants find customers using device lookup or email search

One-Time Payments

Initiate one-time payments with lookupPhrase and customer approval

Billing Intent

Establish agreementPhrase for recurring or on-demand billing

Process Payments

Handle recurring or on-demand billing with agreementPhrase

Customer Discovery
One-Time Payments
Billing Intent
Bill Customers

Customer Discovery

Help merchants find customers using:

Find by Email

http GET /v1/customer/banks Find banks by customer email address

Find by Device

http POST /v1/customer/device/lookup Lookup customer by device ID

One-Time Payments for Merchants

Use this flow when a merchant wants to initiate a one-time payment that requires the customer’s approval through their bank.

{
  "entityId": "merchant_456",
  "lookupPhrases": ["lookup-phrase-1"],
  "amount": 50.00,
  "currency": "NGN",
  "description": "One-time payment requiring customer approval"
}

This path is independent of the agreement-based flow. For recurring or on-demand billing, first create an agreementPhrase through Billing Intent.

Billing Intent for Merchants

Use this flow when a merchant wants recurring or on-demand payments. Send billing intents on behalf of your merchants using /v1/merchant/billing/intent:

{
  "entityId": "merchant_456",
  "lookupPhrases": ["lookup-phrase-1"],
  "currency": "NGN",
  "description": "Uber needs your permission to bill you automatically after each ride."
}

Bill Customers for Merchants

After the merchant has an agreementPhrase, process recurring or on-demand billing requests on their behalf using /v1/merchant/customer/bill:

{
  "entityId": "merchant_456",
  "agreementPhrases": ["unique-phrase-1"],
  "amount": 50.00,
  "currency": "NGN",
  "description": "Payment for services"
}

Advanced Features

Recurring Billing

Create, pause, and resume subscription schedules

Refund Processing

Handle refunds and check refund status

Financial Management

Monitor transactions, balances, and customer decisions

Advanced Feature Details

Recurring Billing Management

Create schedules: POST /v1/billing/recurring/create - Pause schedules: POST /v1/recurring/:scheduleId/pause - Resume schedules: POST /v1/recurring/:scheduleId/resume

Refund Processing

Initiate refunds: POST /v1/refunds/initiate - Check refund status: GET /v1/refunds/:refundId/status

Transaction & Financial Management

Monitor transactions: GET /v1/transaction-history - Check balances: GET /v1/balance/details - View customer decisions: GET /v1/merchant/customer-decisions

Webhook Notifications: As a provider, you’ll receive the same merchant webhooks that direct merchants receive, allowing you to handle responses and manage the payment flow on behalf of your merchants.

Summary

The Peere Network Ecosystem

The Peere Network creates a seamless identity-based payment ecosystem where: Merchants establish billing agreements and process payments using customer phrases Banks manage customer identities, authorize payments, and control spending limits Providers enable existing merchants to access Peere capabilities while maintaining their current integrations. All three players work together through encrypted phrases and webhook notifications to create secure, efficient, and user friendly payment experiences without traditional payment cards or devices.

Getting started

​What is Peere Network?

Identity-Based Payments

​The Players

Banks

Merchants

Providers

​How We Work

​1. As a Merchant, How can I receive money from my customers?

​The Peere Payment Process

approve_once

approve_recurring

​Step-by-Step Implementation

​Payment Initiated with Lookup Phrase

Method 1: Device Lookup

Method 2: Email Lookup

​Create Customer Decision (Establish Agreement)

What is a Agreement Phrase?

Method 1: Device Lookup

Method 2: Email Lookup

​Bill Customer

approve_once

approve_recurring

Updating Billing Agreements

​2. As a Bank, how can my customers pay using Peere?

Your Role in the Peere Network

​Setting up your customers

​Customer Onboarding

​Device Linking

​Handling Merchant Requests

Billing Intent Notifications

Billing Request Notifications

​Responding to Billing Intents

​Responding to Billing Requests

​Managing Customer Decisions

View Decisions

Update Decisions

Track Subscriptions

​Transaction Management

Transaction History

Transaction Details

​3. As a Payment Provider, how can my merchants receive money from their customers?

Your Role in the Peere Network

​Onboarding Your Merchants

​Merchant Registration

​Trust Management

Basic

Enhanced

Premium

​Billing Operations on Behalf of Merchants

​Customer Discovery

Find by Email

Find by Device

​One-Time Payments for Merchants

​Billing Intent for Merchants

​Bill Customers for Merchants

​Advanced Features

Recurring Billing

Refund Processing

Financial Management

​Summary

The Peere Network Ecosystem

What is Peere Network?

The Players

How We Work

1. As a Merchant, How can I receive money from my customers?

The Peere Payment Process

Step-by-Step Implementation

Payment Initiated with Lookup Phrase

Create Customer Decision (Establish Agreement)

Bill Customer

2. As a Bank, how can my customers pay using Peere?

Setting up your customers

Customer Onboarding

Device Linking

Handling Merchant Requests

Responding to Billing Intents

Responding to Billing Requests

Managing Customer Decisions

Transaction Management

3. As a Payment Provider, how can my merchants receive money from their customers?

Onboarding Your Merchants

Merchant Registration

Trust Management

Billing Operations on Behalf of Merchants

Customer Discovery

One-Time Payments for Merchants

Billing Intent for Merchants

Bill Customers for Merchants

Advanced Features

Summary