Sending Payments Through Your Peer-to-Peer App

Payments are a key enabler for efficient transactions on BSV. In this guide, you’ll learn how to set up PeerPay to send live payments and handle incoming payments using both WebSocket and HTTP fallback methods. You will also see how to accept or reject payments as needed.

1. Prerequisites

• BSV-Compatible Wallet:
  You’ll use this for key management, signing, and authentication.

• Node.js & npm (or Yarn):
  Required for developing your app and managing dependencies.

• PeerPay Client Library:
  Install the messaging client library with:

  1npm install @bsv/message-box-client

  Copied!

• Basic JavaScript/TypeScript Knowledge: Familiarity with Node.js development is assumed.

2. Set Up Your Project

1. Initialize a New Project:

1mkdir my-payment-app && cd my-payment-app
2npm init -y

2. Install Dependencies:

1npm install @bsv/message-box-client @bsv/sdk

3. Folder Structure (example): my-payment-app/ ├─ package.json ├─ index.js └─ …

3. Building the Payment Functionality

a. Initialize PeerPay Client Below is an example of how to instantiate the PeerPayClient using a WalletClient. Adjust the wallet client initialization as needed:

1import { PeerPayClient } from '@bsv/message-box-client'
2import { WalletClient } from '@bsv/sdk'
3
4// Example walletClient initialization
5const walletClient = new WalletClient('auto')
6
7// Instantiate the PeerPayClient with the public MessageBox Server endpoint.
8const peerPayClient = new PeerPayClient({
9  messageBoxHost: 'https://your-messagebox.example',
10  walletClient,
11  enableLogging: true  // Enable logging for debugging (disabled by default)
12})
13
14// Initialize the connection
15await peerPayClient.initializeConnection()

b. Sending a Payment Use the sendLivePayment() method to send a payment via WebSocket. If the live channel fails, the request falls back to HTTP automatically:

1await peerPayClient.sendLivePayment({
2  recipient: 'recipient_identity_key',  // Replace with the actual recipient's identity key
3  amount: 1000  // Payment amount in satoshis
4})

c. Handling Live Incoming Payments Set up a listener to process incoming payments in real time using WebSocket:

1await peerPayClient.listenForLivePayments({
2  onPayment: (payment) => {
3    console.log('Incoming Payment:', payment)
4    // Process the incoming payment (update UI, trigger business logic, etc.)
5  }
6})

d. Managing Payments via HTTP (Listing, Accepting, and Rejecting) In addition to live updates, you can retrieve pending payments over HTTP. Use listIncomingPayments() to fetch them and then process individual payments with acceptPayment() or rejectPayment(). Listing Incoming Payments

1const payments = await peerPayClient.listIncomingPayments()
2console.log('HTTP Incoming Payments:', payments)

Accepting a Payment

1// Assume payments is an array and we take the first payment for demonstration.
2const paymentToAccept = payments[0]
3if (paymentToAccept) {
4  const acceptResult = await peerPayClient.acceptPayment(paymentToAccept)
5  console.log('Payment accepted:', acceptResult)
6}

Rejecting a Payment

1// Assume payments is an array and we take the first payment for demonstration.
2const paymentToReject = payments[0]
3if (paymentToReject) {
4  await peerPayClient.rejectPayment(paymentToReject)
5  console.log('Payment rejected and refunded (if applicable).')
6}

4. Testing Your Payment App

1. Run Your Application:

1node index.js

2. Verify Functionality:
   • Confirm that live payments are sent and received.
   • Check that HTTP fallback correctly lists pending payments.
   • Validate that accepting or rejecting payments behaves as expected.

5. Next Steps & Resources

• Enhance Your Payment Flow: Expand your app with improved error handling, UI integration, and support for payment confirmations.
• Advanced Integration: Explore further configuration and advanced features by reviewing the full PeerPay and MessageBox documentation.
• Developer Support: Visit Project Babbage for community support and feedback.

Conclusion

By following this guide, you’ve built a basic payment system using PeerPay on BSV. This Quick Start provides a solid foundation for sending live payments via WebSocket and managing transactions over HTTP. Use this foundation to further integrate payment capabilities into your broader peer-to-peer application. Happy building and enjoy the seamless world of payments on BSV!