Migration - Peere

This guide covers how to migrate your existing customers (for banks) and merchants (for providers) to the Peere Network efficiently and securely.

Bank Customer Migration

For Banks

Banks can migrate their existing customer base to Peere Network using batch endpoints, enabling customers to make identity-based payments immediately.

Migration Process Overview

Prepare Customer Data

Gather and format existing customer information according to Peere requirements

Batch Upload

Use the batch customer creation endpoint to migrate customers in groups

Monitor Progress

Track migration status and handle any failures

Link Devices

Connect customer devices to their unique phrases for seamless merchant interaction

Notify Customers

Inform customers about their new Peere payment capabilities

Customer Data Requirements

Required Fields
Optional Fields
Data Validation

{
  "clientRef": "string",        // Your internal customer ID
  "firstname": "string",        // Customer's first name
  "lastname": "string",         // Customer's last name
  "accountName": "string",      // Full account name
  "email": "string",           // Customer's email address
  "country": "string",         // ISO country code (e.g., "NG")
  "accountNumber": "string",   // Bank account number
  "reference": "string"        // Unique reference for this customer
}

{
  "middlename": "string",      // Middle name (optional)
  "address": "string",         // Customer address
  "gender": "string",          // "male", "female", or "other"
  "phone": "string"            // Phone number with country code
}

Batch Migration Implementation

curl -X POST "https://api.peere.network/v1/bank/customers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customers": [
      {
        "clientRef": "CUST001",
        "firstname": "John",
        "lastname": "Doe",
        "accountName": "John Doe",
        "email": "john.doe@example.com",
        "country": "NG",
        "accountNumber": "1234567890",
        "reference": "ACC001",
        "phone": "+2348012345678"
      },
      {
        "clientRef": "CUST002", 
        "firstname": "Jane",
        "lastname": "Smith",
        "accountName": "Jane Smith",
        "email": "jane.smith@example.com",
        "country": "NG",
        "accountNumber": "0987654321",
        "reference": "ACC002",
        "phone": "+2348087654321"
      }
    ]
  }'

Migration Response Handling

Success Response
Partial Failure Response
Large Batch Response

{
  "success": true,
  "statusCode": 201,
  "message": "Batch processed, customers will reflect shortly",
  "data": {
    "batchId": "bch_20240114_session_abc123xyz",
    "status": "PROCESSING",
    "summary": {
      "total": 100,
      "successful": 95,
      "failed": 5,
      "duplicates": 2,
      "invalidData": 3
    },
    "data": {
      "createdCount": 95,
      "customerIds": ["cust_1", "cust_2", "..."]
    }
  }
}

{
  "success": true,
  "statusCode": 201,
  "data": {
    "batchId": "bch_20240114_session_def456uvw",
    "status": "PROCESSING",
    "summary": {
      "total": 25,
      "successful": 18,
      "failed": 7,
      "duplicates": 3,
      "invalidData": 4
    },
    "failures": [
      {
        "clientRef": "REF-001",
        "index": 2,
        "errorCode": "DUPLICATE_IN_BATCH",
        "errorMessage": "Duplicate customer found within the same batch"
      },
      {
        "clientRef": "REF-005",
        "index": 5,
        "errorCode": "INVALID_DATA",
        "errorMessage": "Missing required fields"
      }
    ],
    "failuresInline": true
  }
}

{
  "success": true,
  "statusCode": 201,
  "data": {
    "batchId": "bch_20240114_session_ghi789rst",
    "status": "PROCESSING",
    "summary": {
      "total": 1000,
      "successful": 850,
      "failed": 150
    },
    "failuresInline": false,
    "failureReport": {
      "format": "CSV",
      "rows": 150,
      "downloadUrl": "https://storage.com/failures.csv",
      "expiresAt": "2024-01-15T12:00:00.000Z"
    }
  }
}

Device Linking After Migration

After successful customer migration, link their devices:

curl -X POST "https://api.peere.network/v1/bank/customer/device/link" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_123",
    "phrase": "customer-unique-phrase",
    "deviceId": "device_789"
  }'

Provider Merchant Migration

For Providers

Payment providers can migrate their existing merchant portfolio to Peere Network, enabling them to accept identity-based payments from customers.

Merchant Migration Process

Gather Merchant Data

Collect merchant business information and contact details

Batch Merchant Creation

Use the provider merchant endpoint to create merchants in batches

Set Trust Levels

Configure appropriate trust levels for each merchant

Configure Webhooks

Set up webhook endpoints for merchant notifications

Test Integration

Verify merchant integration works correctly

Merchant Data Requirements

Required Fields
Optional Fields

{
  "name": "string",           // Business name
  "email": "string",          // Business email
  "phone": "string",          // Business phone number
  "address": "string",        // Business address
  "website": "string"         // Business website URL
}

{
  "description": "string",    // Business description
  "icon": "string",          // Logo/icon URL
  "registrationNumber": "string", // Business registration number
  "industry": "string",      // Industry category
  "country": "string",       // Operating country
  "state": "string"          // Operating state/region
}

Batch Merchant Migration

curl -X POST "https://api.peere.network/v1/provider/merchants" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchants": [
      {
        "name": "Coffee Shop Lagos",
        "email": "contact@coffeeshoplagos.com",
        "phone": "+2348012345678",
        "address": "123 Victoria Island, Lagos",
        "website": "https://coffeeshoplagos.com",
        "industry": "food_beverage"
      },
      {
        "name": "Tech Store Abuja",
        "email": "info@techstoreabuja.com", 
        "phone": "+2348087654321",
        "address": "456 Wuse 2, Abuja",
        "website": "https://techstoreabuja.com",
        "industry": "electronics"
      }
    ]
  }'

Trust Level Configuration

After merchant creation, configure appropriate trust levels:

Basic Trust

Features: Standard billing operations Suitable for: New merchants, low-volume businesses

Enhanced Trust

Features: Device lookup, advanced billing Suitable for: Established merchants, medium-volume

Premium Trust

Features: Full feature access, priority support Suitable for: Large merchants, high-volume businesses

curl -X PATCH "https://api.peere.network/v1/provider/merchant/trust" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "merchant_456",
    "trusted": true,
    "trustLevel": "enhanced",
    "deviceLookupEnabled": true
  }'

Migration Best Practices

1. Data Preparation

Data Validation

Validate all data before migration to avoid batch failures

Duplicate Detection

Check for duplicates using email addresses and account numbers

Data Cleansing

Standardize formats for phone numbers, addresses, and names

Backup Creation

Create backups of original data before migration

2. Migration Strategy

Phased Migration
Batch Sizing

Phase 1: Migrate 10% of customers/merchants for testing Phase 2: Migrate 50% after successful validation Phase 3: Complete migration of remaining records Phase 4: Verify all records and handle any failures

3. Error Handling

async function handleMigrationFailures(failures) {
  const retryableErrors = ['NETWORK_ERROR', 'TIMEOUT', 'RATE_LIMIT'];
  const fixableErrors = ['INVALID_PHONE', 'INVALID_EMAIL'];
  
  for (const failure of failures) {
    if (retryableErrors.includes(failure.errorCode)) {
      // Retry after delay
      await retryMigration(failure.data);
    } else if (fixableErrors.includes(failure.errorCode)) {
      // Fix data and retry
      const fixedData = await fixDataIssue(failure.data, failure.errorCode);
      await retryMigration(fixedData);
    } else {
      // Log for manual review
      console.error('Manual review required:', failure);
    }
  }
}

Post-Migration Tasks

1. Verification

Data Integrity Check

Verify all migrated records are accessible via API

Functionality Testing

Test key operations (billing, device linking, etc.)

Performance Monitoring

Monitor API response times and error rates

User Acceptance Testing

Have key users test the new functionality

2. Customer/Merchant Communication

Customer Notification
Merchant Notification

Email Template:

Subject: New Payment Option Available - Peere Network

Dear [Customer Name],

We're excited to announce that you can now make payments using Peere Network's identity-based payment system.

What's New:

Pay using your identity (no cards or cash needed), Faster, more secure transactions, Seamless payment experience

Your account has been automatically set up. No action is required from you.

Questions? Contact us at [support email]

Best regards,
[Bank Name]

Email Template:

Subject: Accept Identity-Based Payments with Peere Network

Dear [Merchant Name],

Your business can now accept payments through Peere Network's revolutionary identity-based payment system.

Benefits:

- Accept payments without card readers
- Faster transaction processing
- Reduced payment friction for customers
- Enhanced security

Next Steps:

1. Log into your dashboard: [dashboard URL]
2. Review your integration guide
3. Test the payment flow
4. Go live with identity-based payments

Need help? Our integration team is ready to assist.

Best regards,
[Provider Name]

Migration Monitoring

Key Metrics to Track

Success Rate

Target: >95% successful migrations Monitor: Batch success rates, error patterns

Processing Time

Target: < 5 minutes per batch Monitor: API response times, queue lengths

Data Quality

Target: < 1% data validation errors Monitor: Field validation failures, duplicates

System Performance

Target: < 2% error rate post-migration Monitor: API errors, webhook delivery rates

Next Steps

Webhooks Setup

Configure webhook endpoints for real-time notifications

Testing Guide

Test your integration thoroughly before going live

API Reference

Explore detailed API documentation

Support

Get help with your migration

Getting started

Documentation Index

​Bank Customer Migration

For Banks

​Migration Process Overview

​Customer Data Requirements

​Batch Migration Implementation

​Migration Response Handling

​Device Linking After Migration

​Provider Merchant Migration