> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peere.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Start Here

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

<CardGroup cols={2}>
  <Card title="Banks" icon="building-columns">
    Financial institutions that manage customer accounts and authorize payments
  </Card>

  <Card title="Merchants" icon="store">
    Businesses that want to receive payments from customers
  </Card>
</CardGroup>

<Note>
  This creates two distinct flow of payment: **Bank**(customer) **to Bank**(customer), and **Merchant to Bank**(customer)
</Note>

***

<Tabs>
  <Tab title="Bank">
    ## 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

    <Steps>
      <Step title="Customer Onboarding">
        First, you need to onboard your existing customers to the Peere network using our batch migration endpoint [/v1/bank/customers](https://docs.peere.network/bank-apis/customer/create-customers).
      </Step>

      <Step title="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](https://docs.peere.network/bank-apis/customer-device-management/link-customer-device). check our [demo](https://peere.network/demo) page to see this in action.
      </Step>

      <Step title="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.

        <CardGroup cols={2}>
          <Card title="Billing Intent Notifications">
            When merchants want to establish billing agreements, you'll receive [Billing Intent Webhook](https://docs.peere.network/guides/getting-started/webhooks/bank/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](https://res.cloudinary.com/dwlat0fnt/image/upload/v1780670871/merchant-agreement.png)
          </Card>

          <Card title="Billing Request Notifications">
            You'll receive [Billing Request Webhook](https://docs.peere.network/guides/getting-started/webhooks/bank/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
          </Card>
        </CardGroup>

        <Tabs>
          <Tab title="Responding to Billing Intents">
            #### 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](https://api.peere.network/v1/billing/intent-response):

            <CodeGroup>
              ```json Request theme={null}
              {
                "customerId": "customer_123",
                "entityId": "merchant_456",
                "lookupID": "lookup-phrase",
                "customerDecision": "approve_once | approve_recurring | deny | suspended",
                "spendingLimits": {
                  "daily": 1000,
                  "monthly": 5000
                },
                "blockMerchant": false
              }
              ```

              ```bash cURL theme={null}
              curl -X POST "https://api.peere.network/v1/billing/intent-response" \
                -H "Authorization: Bearer YOUR_TOKEN" \
                -H "Content-Type: application/json" \
                -d '{...}'
              ```
            </CodeGroup>
          </Tab>

          <Tab title="Responding to Billing Requests">
            #### 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](https://api.peere.network/v1/billing/bank-response):

            <CodeGroup>
              ```json Request theme={null}
              {
                "billingRequestId": "billing_123",
                "action": "approve_once | approve_recurring | deny | suspended",
                "bankTransactionId": "bank_txn_789"
              }
              ```

              ```bash cURL theme={null}
              curl -X POST "https://api.peere.network/v1/billing/bank-response" \
                -H "Authorization: Bearer YOUR_TOKEN" \
                -H "Content-Type: application/json" \
                -d '{...}'
              ```
            </CodeGroup>
          </Tab>
        </Tabs>
      </Step>

      <Step title="Managing Customer Decisions">
        ### Managing Customer Decisions

        <CardGroup cols={3}>
          <Card title="View Decisions">
            Monitor all customer decisions `http GET /v1/bank/customer-decisions `
          </Card>

          <Card title="Update Decisions">
            Modify existing decisions `http PUT /v1/bank/customer-decisions/:id `
          </Card>

          <Card title="Track Subscriptions">
            Monitor customer subscriptions `http GET /v1/bank/customer/subscriptions `
          </Card>
        </CardGroup>
      </Step>

      <Step title="Transaction Management">
        ### Transaction Management

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

        <CardGroup cols={2}>
          <Card title="Transaction History" icon="chart-line">
            `http GET /v1/transaction-history `
          </Card>

          <Card title="Transaction Details" icon="magnifying-glass">
            `http GET /v1/transaction-details `
          </Card>
        </CardGroup>
      </Step>
    </Steps>

    ***
  </Tab>

  <Tab title="Merchant">
    ## 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

    <Steps>
      <Step title="Retrieve lookupID">
        To interact with a customer you need their `lookupID`, you can get this either by any one of the following:

        <CardGroup cols={3}>
          <Card title="Email lookup">
            Perform an email lookup with [/v1/customer/banks](https://docs.peere.network/merchant-apis/find-customer/get-customer-banks) to get list of banks associated with a customer email address, along side their respective `lookupID`
          </Card>

          <Card title="Device lookup">
            Perform a device lookup with [/v1/customer/device/lookup](https://docs.peere.network/merchant-apis/find-customer/lookup-customer-device-phrase) to get list of banks associated with that customer's device
          </Card>

          <Card title="Manual Submission">
            Provide a form for the user to manually fill in their lookupID copied from their bank apps
          </Card>
        </CardGroup>
      </Step>

      <Step title="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.
      </Step>

      <Step title="Customer Responds">
        The customer responds within minutes via webhook ([sample response](https://docs.peere.network/guides/getting-started/webhooks/merchant/bank-intent-response-webhook)), either accepting or denying your proposal. Approval can be either of the following:

        <CardGroup cols={2}>
          <Card title="approve_once">
            Requires approval for each transaction
          </Card>

          <Card title="approve_recurring">
            Grants permission for future billing (trusted merchants only)
          </Card>
        </CardGroup>
      </Step>
    </Steps>

    ### Step-by-Step Implementation

    <Tabs>
      <Tab title="Option A: One-Time Payment">
        #### One-Time Payment

        Prompt customers through their bank app using their `lookupID`, for one-time payment.

        **Initiate the one-time payment:**

        <CodeGroup>
          ```json Request theme={null}
          {
            "lookupIDs": ["customer-lookup-phrase"],
            "amount": 1500,
            "currency": "NGN",
            "description": "One-time payment requiring customer approval"
          }
          ```

          ```bash cURL theme={null}
          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"
            }'
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Option B: Recurring Payment">
        #### 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:**

        <CodeGroup>
          ```json Request theme={null}
          {
            "lookupIDs": ["customer-lookup-phrase"],
            "currency": "NGN",
            "description": "Netflix subscription - monthly billing authorization"
          }
          ```

          ```bash cURL theme={null}
          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"
            }'
          ```
        </CodeGroup>

        <Tip>
          You'll receive the customer's decision via webhook ([sample response](https://docs.peere.network/guides/getting-started/webhooks/merchant/bank-intent-response-webhook)), along with a `paymentID` for future billing.
        </Tip>

        Next step [Bill Customer](#bill-customer)
      </Tab>

      <Tab title="Step 3: Bill Customer">
        #### Bill Customer

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

        <CodeGroup>
          ```json Request theme={null}
          {
            "paymentIDs": ["customer-agreement-phrase"],
            "amount": 1500,
            "currency": "NGN",
            "description": "Netflix Premium - January 2024"
          }
          ```

          ```bash cURL theme={null}
          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"
            }'
          ```
        </CodeGroup>

        <CardGroup cols={2}>
          <Card title="approve_once">
            Requires approval for each transaction
          </Card>

          <Card title="approve_recurring">
            Grants permission for future billing (trusted merchants only)
          </Card>
        </CardGroup>

        <Note>
          **For Subscription Billing:** Use `POST /v1/billing/recurring/create` to set up automated recurring payments.
        </Note>
      </Tab>
    </Tabs>

    <Card title="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.
    </Card>

    ***
  </Tab>
</Tabs>