Skip to main content

​
Your First Integration

This guide walks you through creating your first Mangopay integration: creating a natural user and retrieving their information. You’ll learn the basic patterns used throughout the SDK.
Before starting, ensure you’ve installed the SDK and have your API credentials ready.

​
Complete Example: Creating a User

Here’s a complete working example that demonstrates the core SDK usage pattern: 
<?php

require_once 'vendor/autoload.php';

use MangoPay\MangoPayApi;
use MangoPay\UserNatural;
use MangoPay\Address;
use MangoPay\Libraries\ResponseException;
use MangoPay\Libraries\Exception;

// Initialize the API
$api = new MangoPayApi();

// Configure with your credentials
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';
$api->Config->TemporaryFolder = '/tmp/mangopay/';

// Create a new natural user
$user = new UserNatural();
$user->FirstName = 'John';
$user->LastName = 'Doe';
$user->Email = '[email protected]';
$user->Birthday = mktime(0, 0, 0, 12, 21, 1985);
$user->Nationality = 'FR';
$user->CountryOfResidence = 'FR';
$user->TermsAndConditionsAccepted = true;

// Set user address
$user->Address = new Address();
$user->Address->AddressLine1 = '1 Mangopay Street';
$user->Address->AddressLine2 = 'The Oasis';
$user->Address->City = 'Paris';
$user->Address->Region = 'Ile-de-France';
$user->Address->PostalCode = '75001';
$user->Address->Country = 'FR';

try {
    // Create the user via API
    $createdUser = $api->Users->Create($user);
    
    echo "User created successfully!\n";
    echo "User ID: " . $createdUser->Id . "\n";
    echo "Name: " . $createdUser->FirstName . " " . $createdUser->LastName . "\n";
    echo "Email: " . $createdUser->Email . "\n";
    
    // Retrieve the user by ID
    $retrievedUser = $api->Users->Get($createdUser->Id);
    echo "\nUser retrieved successfully!\n";
    echo "Person Type: " . $retrievedUser->PersonType . "\n";
    
} catch (ResponseException $e) {
    // Handle API errors
    echo "API Error: " . $e->GetMessage() . "\n";
    echo "Error Code: " . $e->GetCode() . "\n";
    echo "Details: " . print_r($e->GetErrorDetails(), true);
} catch (Exception $e) {
    // Handle general SDK errors
    echo "SDK Error: " . $e->GetMessage() . "\n";
}

​
Breaking Down the Example

Let’s examine each part of the code:

​
Step 1: Initialize the API

use MangoPay\MangoPayApi;

$api = new MangoPayApi();
The MangoPayApi class is your main entry point. It provides access to all SDK functionality through manager properties like Users, Wallets, PayIns, etc.

​
Step 2: Configure Credentials

$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';
$api->Config->TemporaryFolder = '/tmp/mangopay/';
The TemporaryFolder must be writable and outside your web root for security. Use different folders for sandbox and production environments.
For production, also set: 
$api->Config->BaseUrl = 'https://api.mangopay.com';

​
Step 3: Create User Object

use MangoPay\UserNatural;
use MangoPay\Address;

$user = new UserNatural();
$user->FirstName = 'John';
$user->LastName = 'Doe';
$user->Email = '[email protected]';
$user->Birthday = mktime(0, 0, 0, 12, 21, 1985);
$user->Nationality = 'FR';
$user->CountryOfResidence = 'FR';
$user->TermsAndConditionsAccepted = true;
Birthday must be a Unix timestamp. Use mktime() to create timestamps from dates.
The SDK provides entity classes for all API resources:
  • UserNatural - Individual persons
  • UserLegal - Organizations
  • Wallet - User wallets
  • PayIn, PayOut, Transfer - Transactions

​
Step 4: Set Nested Objects

$user->Address = new Address();
$user->Address->AddressLine1 = '1 Mangopay Street';
$user->Address->City = 'Paris';
$user->Address->Country = 'FR';
Many entities have nested objects like Address, Money, or BankAccountDetails. Create these using their respective classes.

​
Step 5: Make API Calls

$createdUser = $api->Users->Create($user);
API calls are made through manager properties:
  • $api->Users - User management
  • $api->Wallets - Wallet operations
  • $api->PayIns - Payment processing
  • $api->Transfers - Transfer operations
Each manager provides standard CRUD methods where applicable:
  • Create($object) - Create a new resource
  • Get($id) - Retrieve by ID
  • Update($object) - Update existing resource
  • GetAll($pagination) - List resources

​
Step 6: Handle Errors

try {
    $user = $api->Users->Create($user);
} catch (ResponseException $e) {
    // API returned an error
    echo $e->GetMessage();
    echo $e->GetCode();
    print_r($e->GetErrorDetails());
} catch (Exception $e) {
    // SDK or network error
    echo $e->GetMessage();
}
Always catch both ResponseException (API errors) and Exception (SDK/network errors) for robust error handling.

​
Working with Pagination

When retrieving lists of resources, use the Pagination class: 
use MangoPay\Pagination;

// Get page 1 with 10 items per page
$pagination = new Pagination(1, 10);

try {
    $users = $api->Users->GetAll($pagination);
    
    echo "Total users: " . $pagination->TotalItems . "\n";
    echo "Total pages: " . $pagination->TotalPages . "\n";
    
    foreach ($users as $user) {
        echo "User: " . $user->FirstName . " " . $user->LastName . "\n";
    }
    
} catch (ResponseException $e) {
    echo "Error: " . $e->GetMessage();
}

​
Updating Resources

To update a resource, retrieve it, modify properties, and call the update method: 
try {
    // Get the user
    $user = $api->Users->Get($userId);
    
    // Modify properties
    $user->LastName = 'Smith';
    $user->Email = '[email protected]';
    
    // Update via API
    $updatedUser = $api->Users->Update($user);
    
    echo "User updated successfully!\n";
    
} catch (ResponseException $e) {
    echo "Error: " . $e->GetMessage();
}

​
Creating a Simple Payer User

For users who only make payments (payers), you can create a simplified user: 
use MangoPay\UserCategory;

$payer = new UserNatural();
$payer->FirstName = 'Jane';
$payer->LastName = 'Smith';
$payer->Email = '[email protected]';
$payer->TermsAndConditionsAccepted = true;
$payer->UserCategory = UserCategory::Payer;

try {
    $createdPayer = $api->Users->Create($payer);
    echo "Payer created with ID: " . $createdPayer->Id . "\n";
} catch (ResponseException $e) {
    echo "Error: " . $e->GetMessage();
}
Payer users have simplified requirements compared to owner users, making onboarding faster for customers who only need to make payments.

​
Common SDK Patterns

Here are patterns you’ll use throughout the SDK:

​
1. Using Constants

The SDK provides constants for enumerated values: 
use MangoPay\PersonType;
use MangoPay\LegalPersonType;
use MangoPay\CurrencyIso;

// Check user type
if ($user->PersonType === PersonType::Natural) {
    echo "Individual user";
}

// Use currency constants
$money = new Money();
$money->Currency = CurrencyIso::EUR;
$money->Amount = 1000; // Amount in cents

​
2. Working with Timestamps

API timestamps are Unix timestamps: 
// Create timestamp from date
$user->Birthday = mktime(0, 0, 0, 12, 21, 1985);

// Format timestamp for display
echo date('Y-m-d', $user->Birthday);

​
3. Money Amounts

All monetary amounts are in the smallest currency unit (cents for EUR/USD): 
use MangoPay\Money;

$amount = new Money();
$amount->Currency = 'EUR';
$amount->Amount = 1000; // €10.00 (1000 cents)

​
Next Steps

Now that you’ve created your first user, explore more features:

Configuration

Learn about all configuration options and environment settings

Users

Dive deeper into user management and KYC

Wallets

Create and manage user wallets

Payments

Process payments and handle transactions

​
Getting Help

If you encounter issues:
  • Check the API documentation for endpoint details
  • Review error messages in ResponseException for specific issues
  • Report bugs on GitHub
  • Ensure your temporary folder has write permissions

Build docs developers (and LLMs) love

Get started for freeTalk to us