Start Here - Peere

Peere is a payment network where money moves strictly on identity (palm scanning, biometric recognition, and invisible systems) rather than traditional Everyday Carry items like credit cards, cash, and phones. Peere is built to drive us into an era of invisible payment and 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

This creates two distinct flow of payment: Bank(customer) to Bank(customer), and Merchant to Bank(customer)

Bank
Merchant

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

Banks act as the trusted intermediary between customers or customer and merchant. Managing customer identities and payment authorizations. You control your customers’ payment decisions and ensure secure, compliant transactions.

Steps to setting up your customers

Customer Onboarding

First, you need to onboard your existing customers to the Peere network using our batch migration endpoint /v1/bank/customers.

Device Linking (online payments only)

Link your customers’ devices to their lookup IDs that was created during onboarding, for seamless merchant interaction online. see /v1/bank/customer/device/link. check our demo page to see this in action.

Handling Payment Requests

We send two types of webhook notifications, to notify you whenever a customer wants to make payment either instore or online, and when merchants want to establish billing agreements with a customer.

Billing Intent Notifications

When merchants want to establish billing agreements, you’ll receive Billing Intent Webhook notifications. These notifications indicate that a merchant is requesting your customer’s approval for billing permissions. You should notify the customer through FCM or email about the merchant’s request and direct them to review it within your app. See example UI

Billing Request Notifications

You’ll receive Billing Request Webhook notifications when a customer attempts to make payment instore or online. 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
Responding to Billing Requests

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",
  "lookupID": "lookup-phrase",
  "customerDecision": "approve_once | approve_recurring | deny | suspended",
  "spendingLimits": {
    "daily": 1000,
    "monthly": 5000
  },
  "blockMerchant": false
}

curl -X POST "https://api.peere.network/v1/billing/intent-response" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{...}'

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"
}

curl -X POST "https://api.peere.network/v1/billing/bank-response" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{...}'

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

2. As a Merchant, How can I receive money from users/customers online?

Receiving money from your customers is now significantly easier than most traditional methods, you can now receive and automate billing directly from your customers’ bank whenever needed.

The Payment Process

Retrieve lookupID

To interact with a customer you need their lookupID, you can get this either by any one of the following:

Email lookup

Perform an email lookup with /v1/customer/banks to get list of banks associated with a customer email address, along side their respective lookupID

Device lookup

Perform a device lookup with /v1/customer/device/lookup to get list of banks associated with that customer’s device

Manual Submission

Provide a form for the user to manually fill in their lookupID copied from their bank apps

Establish Agreement

For one-time payments, you can initiate payment with a customer’s lookupID, 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 paymentID) 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

Option A: One-Time Payment
Option B: Recurring Payment
Step 3: Bill Customer

One-Time Payment

Prompt customers through their bank app using their lookupID, for one-time payment.Initiate the one-time payment:

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

curl -X POST "https://api.peere.network/v1/customer/bill" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lookupIDs": ["customer-lookup-phrase"],
    "amount": 1500,
    "currency": "NGN",
    "description": "One-time payment requiring customer approval"
  }'

Recurring Payment (Establish Agreement)

To receive on demand payments, you must first establish a billing agreement with the customer and create an paymentID. Once the agreement is in place, you can use the paymentID to bill the customer.Initiate the agreement:

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

curl -X POST "https://api.peere.network/v1/billing/intent" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lookupIDs": ["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 paymentID for future billing.

Next step Bill Customer

Bill Customer

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

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

curl -X POST "https://api.peere.network/v1/customer/bill" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentIDs": ["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.

​The Players

Banks

Merchants

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

​Steps to setting up your customers

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

​2. As a Merchant, How can I receive money from users/customers online?

​The Payment Process

Email lookup

Device lookup

Manual Submission

approve_once

approve_recurring

​Step-by-Step Implementation

​One-Time Payment

​Recurring Payment (Establish Agreement)

​Bill Customer

approve_once

approve_recurring

Updating Billing Agreements

The Players

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

Steps to setting up your customers

Responding to Billing Intents

Responding to Billing Requests

Managing Customer Decisions

Transaction Management

2. As a Merchant, How can I receive money from users/customers online?

The Payment Process

Step-by-Step Implementation

One-Time Payment

Recurring Payment (Establish Agreement)

Bill Customer