Integration Best Practices

This guide outlines best practices for developers integrating with the Reveel PayID API. Following these principles will help ensure a reliable, secure, and scalable integration.

1. Authentication

• Always include your API key in the Authorization header:

  Authorization: Bearer your-api-key

• Store API keys securely in environment variables, never in frontend code or public repositories

• Implement key rotation mechanisms if your backend supports it

• Use proper error handling for 401 responses to trigger re-authentication flows

2. Token and Network Compatibility

• Only use the supported tokens: USDT, USDC, ETH, BNB, POL - along with native tokens of respective chains.

• Only use the supported networks: ETH, POL, OP, BNB, BASE

• Be aware of unsupported combinations:

  • POL token on OP network

  • BNB token on OP network

  • USDT token on BASE network

  • BNB token on BASE network

  • POL token on BASE network

3. Transaction Handling

• For ERC20 tokens (USDT, USDC), always check for approveTx in the response

• If approveTx is present, execute this transaction first before the main transaction

• Implement proper error handling for transaction states (pending, completed, failed)

• Add client-side idempotency keys to prevent accidental duplicate transactions

• When sending to a PayID, be prepared to handle route-based swaps and associated fees

4. Error Handling

• All API responses follow a consistent format with success flag

• Error responses include detailed information in the error object:

  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid input data",
      "details": {
        "errors": [
          {
            "path": ["userId"],
            "message": "userId is required"
          }
        ]
      }
    }
  }

• Implement specific handling for common errors:

  • 400: Client-side validation errors

  • 401: Authentication failures

  • 404: Resource not found

  • 409: Conflicts (e.g., route conflicts, PayID already taken)

  • 500: Server errors (may be retried with backoff)

5. Pagination

• When fetching transaction activities, always use pagination parameters:

  • page (default: 1): Page number

  • pageSize (default: 10): Number of items per page

• Implement UI for pagination controls or auto-load mechanisms

• Use the pagination metadata returned in the response for accurate UI:

  "pagination": {
    "totalCount": 25,
    "totalPages": 3,
    "currentPage": 1,
    "pageSize": 10
  }

6. Network Resilience

• Implement retry logic with exponential backoff for 5xx errors and timeouts

• Do not retry on 4xx errors (except possibly 429 Too Many Requests)

• Recommended backoff strategy:

  • Initial delay: 1 second

  • Maximum retries: 3

  • Exponential factor: 2 (1s, 2s, 4s)

• Add circuit breakers to prevent cascading failures during API outages

7. Monitoring and Logging

• Log all API requests with relevant details:

  • Endpoint path

  • HTTP method

  • Response status code

  • Error messages (without sensitive data)

  • Response times

• Track transaction success rates for user analytics

• Implement health checks to detect API availability issues

8. Security Considerations

• Validate wallet addresses on the client side before submission

• Never log full transaction data that might contain sensitive information

• Implement rate limiting in your client applications to prevent abuse

• For PayID integrations, validate PayID format before submission to reduce errors

9. Performance Optimization

• Cache frequently accessed data (user lists, routes)

• Implement conditional fetching based on UI state

• Use local storage or state management to reduce redundant API calls

• Prefetch anticipated data when appropriate (e.g., user routes before transaction)

10. API Evolution

• The Reveel API uses versioned endpoints (/v1/transactions)

• Monitor for deprecation notices and new versions

• Design your integration to easily accommodate API changes by using abstraction layers

• Subscribe to developer notifications if available to stay current with changes

11. Content Headers

• Always include proper headers for all requests:

  Accept: application/json
  Content-Type: application/json  // For requests with bodies

• Validate response content types to ensure you're receiving JSON data

• Handle unexpected content types gracefully (e.g., HTML error pages)