how to create wallet in mangopay?

Creating a Wallet in MangoPay: A PHP Guide

Learn how to programmatically create and manage user wallets within the MangoPay payment gateway using PHP, covering essential steps and best practices.

MangoPay is a powerful payment solution that allows platforms to manage funds for multiple users. A core component of this system is the 'wallet', which acts as a virtual account where funds are held for a user. Before any transactions can occur, each user on your platform needs an associated MangoPay wallet. This article will guide you through the process of creating a user wallet using the MangoPay PHP SDK.

Understanding MangoPay Wallets

A MangoPay wallet is essentially an electronic money account linked to a user. It holds funds in a specific currency and is crucial for facilitating various payment operations such as payouts, transfers, and refunds. Each wallet is associated with a unique user ID, ensuring that funds are correctly attributed. It's important to understand that a user can have multiple wallets, typically one per currency they operate with, or for different purposes (e.g., a main wallet and a bonus wallet).

flowchart TD
    A[Platform User Registration] --> B{Create MangoPay User?}
    B -- Yes --> C[Create MangoPay User (Natural/Legal)]
    C --> D[Create MangoPay Wallet]
    D --> E[Wallet Created & Linked to User]
    B -- No --> E
    E --> F[Ready for Transactions]

Workflow for creating a MangoPay wallet for a new user.

Prerequisites for Wallet Creation

Before you can create a wallet, you must have a MangoPay user account set up. This user can be either a 'Natural User' (an individual) or a 'Legal User' (a company or organization). The wallet creation process requires the OwnerId (the ID of the MangoPay user) and the Currency for the wallet. Ensure your MangoPay SDK is properly initialized with your client ID and API key.

<?php

require_once 'vendor/autoload.php';

use MangoPay\MangoPayApi;
use MangoPay\Wallet;

// Initialize MangoPay API
$mangoPayApi = new MangoPayApi();
$mangoPayApi->Config->ClientId = 'YOUR_CLIENT_ID';
$mangoPayApi->Config->ClientPassword = 'YOUR_API_KEY';
$mangoPayApi->Config->BaseUrl = 'https://api.mangopay.com'; // Or 'https://api.sandbox.mangopay.com' for sandbox

// --- Replace with your actual user ID ---
$ownerId = 'mgp_user_12345'; // Example: ID of an existing MangoPay user

// Create a new Wallet object
$wallet = new Wallet();
$wallet->Owners = [$ownerId];
$wallet->Currency = 'EUR'; // Or 'GBP', 'USD', etc.
$wallet->Description = 'Main wallet for user ' . $ownerId;

try {
    // Create the wallet via the API
    $createdWallet = $mangoPayApi->Wallets->Create($wallet);

    echo 'Wallet created successfully!\n';
    echo 'Wallet ID: ' . $createdWallet->Id . '\n';
    echo 'Balance: ' . $createdWallet->Balance->Amount . ' ' . $createdWallet->Balance->Currency . '\n';
    echo 'Description: ' . $createdWallet->Description . '\n';

} catch (MangoPay\Libraries\ResponseException $e) {
    echo 'Error creating wallet: ' . $e->getMessage() . '\n';
    // Log the error details for debugging
    error_log('MangoPay Error: ' . $e->getMessage() . ' - ' . json_encode($e->Get  ResponseObject()));
} catch (Exception $e) {
    echo 'An unexpected error occurred: ' . $e->getMessage() . '\n';
}

?>

PHP code to create a new MangoPay wallet.

Handling Multiple Currencies and Wallets

If your platform supports multiple currencies, you will likely need to create a separate wallet for each currency for a given user. MangoPay handles currency conversions during transfers between wallets of different currencies, but funds are always held in the wallet's native currency. You might also create multiple wallets for a single user in the same currency if you need to segregate funds for different purposes (e.g., a primary wallet and a loyalty points wallet).

<?php
// ... (MangoPay API initialization as above) ...

$ownerId = 'mgp_user_12345'; // Existing user ID
$currencies = ['EUR', 'GBP', 'USD'];

foreach ($currencies as $currency) {
    $wallet = new Wallet();
    $wallet->Owners = [$ownerId];
    $wallet->Currency = $currency;
    $wallet->Description = 'Main wallet for user ' . $ownerId . ' in ' . $currency;

    try {
        $createdWallet = $mangoPayApi->Wallets->Create($wallet);
        echo 'Wallet created successfully for ' . $currency . ': ' . $createdWallet->Id . '\n';
    } catch (MangoPay\Libraries\ResponseException $e) {
        echo 'Error creating ' . $currency . ' wallet: ' . $e->getMessage() . '\n';
    } catch (Exception $e) {
        echo 'An unexpected error occurred for ' . $currency . ' wallet: ' . $e->getMessage() . '\n';
    }
}

?>

Creating multiple wallets for a user, each with a different currency.

Error Handling and Best Practices

Robust error handling is crucial when interacting with any external API. MangoPay's PHP SDK throws MangoPay\Libraries\ResponseException for API-specific errors, which contain detailed information about what went wrong. Always catch these exceptions and log the details to aid in debugging. Additionally, consider implementing idempotency keys for critical operations like wallet creation to prevent duplicate requests if a network issue occurs.

1. Step 1: Install the MangoPay PHP SDK

Ensure you have the MangoPay PHP SDK installed via Composer: composer require mangopay/php-sdk.

2. Step 2: Initialize the API Client

Set up your MangoPayApi instance with your ClientId and ClientPassword (API Key) obtained from your MangoPay dashboard. Remember to use the correct BaseUrl for sandbox or production.

3. Step 3: Prepare Wallet Data

Create a new Wallet object and populate its Owners array with the ID(s) of the MangoPay user(s) who will own this wallet. Specify the Currency (e.g., 'EUR', 'GBP') and an optional Description.

4. Step 4: Create the Wallet

Call the Wallets->Create() method with your prepared Wallet object. This will send the request to MangoPay and return the newly created wallet object.

5. Step 5: Store Wallet ID and Handle Response

Extract the Id from the returned wallet object and store it in your application's database. Implement try-catch blocks to gracefully handle any ResponseException or other general exceptions that may occur during the API call.