Migrate to V2 - Request Network Docs

The Request Network API V2 introduces significant improvements while maintaining backward compatibility. This guide provides a comprehensive overview of the breaking changes between V1 and V2, along with a step-by-step migration guide.

V1 API Deprecation NoticeV1 of the Request Network API is deprecated and in security-fixes-only mode. This means:

Deprecated: We strongly recommend upgrading to V2
Security-fixes-only: V1 will only receive critical security patches, no new features, enhancements, or non-security bug fixes

Please migrate to V2 as soon as possible to ensure continued support and access to the latest features.

Important: V2 is designed to coexist with V1. You can migrate incrementally and don’t need to migrate all endpoints at once. See the Full API Reference for documentation of the V1 endpoints.

Breaking Changes from V1 to V2

Core Architectural Changes

Path Parameter Changes

V1: Uses paymentReference as the path parameter
V2: Uses requestId as the path parameter

Response Schema Standardization

V1: Returns requestID (uppercase D) in create responses
V2: Returns requestId (lowercase d) in create responses

Enhanced Validation

V2: Stricter type checking and validation schemas
V1: More permissive validation

API Interface Differences

Endpoint Structure Changes

Request Endpoints

Feature	V1 Endpoint	V2 Endpoint
Create Request	`POST /v1/request`	`POST /v2/request`
Get Request	`GET /v1/request/{paymentReference}`	`GET /v2/request/{requestId}`
Get Request Status	`GET /v1/request/{paymentReference}/status`	`GET /v2/request/{requestId}/status`

Payment Endpoints

Feature	V1 Endpoint	V2 Endpoint
Get Payment Calldata	`GET /v1/request/{paymentReference}/pay`	`GET /v2/request/{requestId}/pay`
Get Payment Routes	`GET /v1/request/{paymentReference}/routes`	`GET /v2/request/{requestId}/routes`

Request Schema Differences

Create Request Schema

V1 Schema:

{
  "amount": "string",
  "payee": "string",
  "invoiceCurrency": "string",
  "paymentCurrency": "string"
}

V2 Schema:

{
  "amount": "string",
  "payee": "string",
  "invoiceCurrency": "string",
  "paymentCurrency": "string"
  // V2 accepts additional optional fields for extended functionality
}

Create Response Schema

V1 Response:

{
  "requestID": "string",  // Note: uppercase D
  "paymentReference": "string"
}

V2 Response:

{
  "requestId": "string",  // Note: lowercase d
  "paymentReference": "string"
}

Payment Query Parameter Differences

Pay Request Query Parameters

V1 Query Parameters:

interface PayRequestQueryV1 {
  payerAddress?: string;
  routeId?: string;
}

V2 Query Parameters:

interface PayRequestQueryV2 {
  payerAddress?: string;
  routeId?: string;
  // Enhanced validation with stricter type checking
}

Step-by-Step Migration Guide

Phase 1: Assessment and Planning

Audit Your Current Integration
- List all V1 endpoints you’re currently using
- Identify which features you need (basic payments vs advanced features)
Choose Migration Strategy
- Incremental: Migrate endpoints one by one (recommended)
- Full Migration: Switch all endpoints at once
- Parallel: Run V1 and V2 side by side

Phase 2: Update Path Parameters

Before (V1):

// Get request status
const response = await fetch(`/v1/request/${paymentReference}/status`);

// Get payment calldata
const payData = await fetch(`/v1/request/${paymentReference}/pay?payerAddress=${address}`);

After (V2):

// Get request status
const response = await fetch(`/v2/request/${requestId}/status`);

// Get payment calldata
const payData = await fetch(`/v2/request/${requestId}/pay?payerAddress=${address}`);

Phase 3: Update Response Handling

Before (V1):

const createResponse = await fetch('/v1/request', {
  method: 'POST',
  body: JSON.stringify(requestData)
});

const { requestID, paymentReference } = await createResponse.json();
// Note: requestID with uppercase D

After (V2):

const createResponse = await fetch('/v2/request', {
  method: 'POST',
  body: JSON.stringify(requestData)
});

const { requestId, paymentReference } = await createResponse.json();
// Note: requestId with lowercase d

Phase 4: Update Error Handling

V2 has enhanced error responses with more specific error codes:

try {
  const response = await fetch('/v2/request', {
    method: 'POST',
    body: JSON.stringify(requestData)
  });

  if (!response.ok) {
    const error = await response.json();

    // V2 provides more detailed error information
    console.error('Error:', error.message);
    console.error('Status Code:', error.statusCode);
    console.error('Error Code:', error.error);
  }
} catch (error) {
  console.error('Request failed:', error);
}

Phase 5: Testing and Validation

Test Core Functionality
- Create requests using V2 endpoints
- Verify payment flows work correctly
- Check response formats match expectations
Enhanced Validation Testing
- Test stricter type checking
- Verify improved error responses
Performance Testing
- Compare response times between V1 and V2
- Test with realistic data volumes

Support and Resources

Migration Support: Book a call with our team for migration assistance
GitHub Examples: Check the easy-invoice repository for V2 implementation examples

Backward Compatibility

V1 endpoints will continue to work during the migration period. However, we recommend migrating to V2 to access improvements and future features:

Enhanced security and validation
Better error handling and debugging
Improved webhook events
Access to new features as they are released

V2 is the foundation for all future Request Network API features and improvements.

​Breaking Changes from V1 to V2

​Core Architectural Changes

​API Interface Differences

​Endpoint Structure Changes

​Request Endpoints

​Payment Endpoints

​Request Schema Differences

​Create Request Schema

​Create Response Schema

​Payment Query Parameter Differences

​Pay Request Query Parameters

​Step-by-Step Migration Guide

​Phase 1: Assessment and Planning

​Phase 2: Update Path Parameters

​Before (V1):

​After (V2):

​Phase 3: Update Response Handling

​Before (V1):

​After (V2):

​Phase 4: Update Error Handling

​Phase 5: Testing and Validation

​Support and Resources

​Backward Compatibility

Breaking Changes from V1 to V2

Core Architectural Changes

API Interface Differences

Endpoint Structure Changes

Request Endpoints

Payment Endpoints

Request Schema Differences

Create Request Schema

Create Response Schema

Payment Query Parameter Differences

Pay Request Query Parameters

Step-by-Step Migration Guide

Phase 1: Assessment and Planning

Phase 2: Update Path Parameters

Before (V1):

After (V2):

Phase 3: Update Response Handling

Before (V1):

After (V2):

Phase 4: Update Error Handling

Phase 5: Testing and Validation

Support and Resources

Backward Compatibility