Overview

This document provides a comprehensive overview of the wallet top-up process in the Presto Financial Institutions API. The wallet top-up functionality allows financial institutions to credit funds to their customers' Presto wallets.

Process Flow Diagram

The following sequence diagram illustrates the interactions between systems during the wallet top-up process:

Integration Steps

1. Customer Information Collection

Collect the customer's identifier (phone number, email, or UID) and the desired top-up amount through your interface.

2. Wallet Initialization

Call the initialization endpoint to validate the customer and obtain the transaction reference.

3. User Confirmation

Present the returned customer information to your user and request confirmation.

4. Transaction Completion

After confirmation, call the confirmation endpoint to finalize the transaction.

5. Transaction Verification

If needed, verify the transaction status using the transaction information endpoint.

6. Handling Cancellations

If the user cancels or the transaction expires, no further action is needed. The transaction will be automatically voided.

Implementation Best Practices

Security Considerations

• Store API tokens securely in your environment variables or secrets manager
• Implement proper TLS certificate validation
• Log all API calls for audit purposes
• Never expose your API tokens in client-side code

Key Implementation Guidelines

Guideline	Description
Always Validate Customer Info	Use the wallet initialization endpoint to validate customer information before presenting confirmation options
Handle Timeouts Gracefully	Implement appropriate timeout handling for all API calls, with clear user feedback
Provide Clear User Interface	Display confirmation details clearly to reduce user errors and increase confidence
Implement Proper Retries	Use exponential backoff for retry logic on transient errors

Error Handling

Common Integration Challenges

Challenge	Resolution
Customer Not Found	Verify identifier format and type match exactly what's registered in Presto
Timeouts	Implement proper retry mechanisms with exponential backoff
Expired Transactions	Reinitialize transaction if confirmation is delayed beyond 15 minutes

When handling errors from the API:

1. Display user-friendly error messages that guide the customer
2. Log detailed error information including request IDs for troubleshooting
3. Implement appropriate retry logic for transient errors only

Support and Troubleshooting

If you encounter issues implementing the wallet top-up flow, contact Presto support with:

Support Request Checklist

• Detailed error messages and codes
• Transaction references (if available)
• Request and response payloads (with sensitive data redacted)
• Timestamps of the requests
• Steps to reproduce the issue