Skip to main content

​
Overview

The Mangopay PHP SDK uses OAuth 2.0 authentication to secure API requests. The SDK automatically manages authentication tokens, including creation, storage, and renewal.

​
Authentication Flow

The SDK handles authentication through two main components:
  1. AuthorizationTokenManager - Manages token lifecycle
  2. AuthenticationManager - Creates OAuth tokens

​
Token Management

Tokens are automatically managed by the SDK. When you make an API request:
  1. The SDK checks if a valid token exists
  2. If the token is expired or missing, a new one is created
  3. The token is stored using the configured storage strategy
  4. All subsequent requests use the stored token
Tokens are cached and automatically renewed when they expire, so you don’t need to manage them manually.

​
Configuration

Set up authentication when initializing the SDK: 
use MangoPay\MangoPayApi;

$api = new MangoPayApi();

// Set your API credentials
$api->Config->ClientId = 'your_client_id';
$api->Config->ClientPassword = 'your_client_password';

// Set the environment
$api->Config->BaseUrl = 'https://api.sandbox.mangopay.com'; // Sandbox
// $api->Config->BaseUrl = 'https://api.mangopay.com'; // Production

​
Environment URLs

Sandbox

https://api.sandbox.mangopay.comUse for testing and development

Production

https://api.mangopay.comUse for live transactions

​
Custom Token Storage

By default, tokens are stored in temporary files. You can implement custom storage by creating a class that implements IStorageStrategy: 
use MangoPay\Libraries\IStorageStrategy;
use MangoPay\Libraries\OAuthToken;

class CustomStorageStrategy implements IStorageStrategy
{
    public function Get()
    {
        // Retrieve token from your storage (database, cache, etc.)
        // Return OAuthToken or null
    }

    public function Store($token)
    {
        // Save token to your storage
    }
}
Register your custom storage strategy: 
$api = new MangoPayApi();
$api->OAuthTokenManager->RegisterCustomStorageStrategy(new CustomStorageStrategy());

​
Token Information

The OAuth token contains:
  • access_token - The authentication token
  • token_type - Always “Bearer”
  • expires_in - Token lifetime in seconds
Reference: ~/workspace/source/MangoPay/Libraries/AuthorizationTokenManager.php:29

​
Connection Timeouts

You can configure connection and response timeouts: 
$api->Config->CurlConnectionTimeout = 30; // Connection timeout in seconds
$api->Config->CurlResponseTimeout = 30;   // Response timeout in seconds
Reference: ~/workspace/source/MangoPay/Libraries/Configuration.php:56

​
Proxy Configuration

If you need to use a proxy: 
$api->Config->HostProxy = 'proxy.example.com:8080';
$api->Config->UserPasswordProxy = 'username:password';
Never commit your ClientPassword to version control. Use environment variables or secure configuration management.

​
SSL Certificate Verification

For production environments, you can specify a custom CA certificate bundle: 
$api->Config->CertificatesFilePath = '/path/to/cacert.pem';
Leave empty to skip certificate verification (not recommended for production). Reference: ~/workspace/source/MangoPay/Libraries/Configuration.php:39

​
Best Practices

Never hardcode credentials in your source code. Use environment variables or secure configuration files that are not committed to version control.
Maintain separate API credentials for sandbox and production environments.
The default file-based token storage is suitable for development, but consider using a database or cache system for production.
Implement logging to track authentication failures and token renewal issues.

​
Next Steps

Users

Learn about user management

Wallets

Understand wallet operations

Build docs developers (and LLMs) love

Get started for freeTalk to us