Troubleshooting - Mangopay PHP SDK

This guide covers common issues you might encounter when using the Mangopay PHP SDK and how to resolve them.

Authentication Issues

OAuth Token File Problems

After updating the SDK, you may experience authentication failures due to outdated temporary token files.

Symptom

401 Unauthorized errors
“Invalid token” messages
Authentication failures after SDK update

Solution

Delete your temporary token file to force regeneration:

rm -rf /path/to/temporary/folder/*

The SDK will automatically regenerate the token on the next API call.Important: Use different temporary folders for sandbox and production environments:

// Sandbox
$api->Config->TemporaryFolder = '/tmp/mangopay/sandbox/';

// Production
$api->Config->TemporaryFolder = '/tmp/mangopay/production/';

Invalid Credentials

Symptom

401 Unauthorized on all requests
“Authentication credentials not recognized” error

Solution

Verify your credentials are correct:

$api->Config->ClientId = 'your-client-id'; // Check this
$api->Config->ClientPassword = 'your-api-key'; // Check this

Common mistakes:

Using production credentials in sandbox (or vice versa)
Trailing/leading whitespace in credentials
Using Client Secret instead of API Key
Expired API keys

How to verify:

Log into your Mangopay Dashboard
Navigate to API & Reports > API Keys
Compare with your code

Wrong Environment

Symptom

Resources not found
Different data than expected
Authentication works but operations fail

Solution

Ensure you’re using the correct base URL:

// Sandbox (for testing)
$api->Config->BaseUrl = 'https://api.sandbox.mangopay.com';

// Production (for live transactions)
$api->Config->BaseUrl = 'https://api.mangopay.com';

Never use production credentials in sandbox or sandbox credentials in production!

SSL/TLS Issues

Certificate Verification Failures

Symptom

cURL error 60: SSL certificate problem
“unable to get local issuer certificate”

Solution

Update your CA certificate bundle:

Download the latest CA bundle from curl.se
Save it to a secure location
Configure the SDK:

$api->Config->CertificatesFilePath = '/path/to/cacert.pem';

For development only (not recommended for production):If you need to disable SSL verification temporarily:

// WARNING: Do not use in production!
$api->Config->CertificatesFilePath = '';

TLS Version Issues

Symptom

Connection errors
“unsupported protocol” errors

Solution

Mangopay requires TLS 1.2 or higher. Ensure your PHP installation supports it:

// Check OpenSSL version
echo OPENSSL_VERSION_TEXT;
// Should be OpenSSL 1.0.1 or higher

// Check cURL SSL version
$version = curl_version();
echo $version['ssl_version'];

If using an older version, upgrade OpenSSL and recompile PHP with the latest version.

Timeout Issues

Request Timeouts

Symptom

cURL error 28: Operation timed out
Requests fail after 30 seconds

Solution

Increase timeout values:

// Response timeout (default: 30 seconds)
$api->Config->CurlResponseTimeout = 60;

// Connection timeout (default: 80 seconds)
$api->Config->CurlConnectionTimeout = 120;

Some operations like KYC document uploads may require longer timeouts.

Script Execution Timeout

Symptom

PHP Fatal error: Maximum execution time exceeded

Solution

Increase PHP’s max execution time:

set_time_limit(300); // 5 minutes

Or in php.ini:

max_execution_time = 300

Type Errors and Object Issues

Money Object Errors

Symptom

“Expected Money object, got integer”
Type mismatch errors with amounts

Solution

Always use Money objects for amounts:

// Wrong
$payIn->DebitedFunds = 1000;

// Correct
use MangoPay\Money;

$payIn->DebitedFunds = new Money();
$payIn->DebitedFunds->Currency = 'EUR';
$payIn->DebitedFunds->Amount = 1000;

Address Object Errors

Symptom

“Address required” validation errors
Missing address fields

Solution

Ensure all required Address fields are set:

use MangoPay\Address;

$address = new Address();
$address->AddressLine1 = '1 London Road'; // Required
$address->City = 'London';                // Required
$address->PostalCode = 'SW1A 1AA';        // Required
$address->Country = 'GB';                 // Required (ISO 3166-1 alpha-2)
$address->Region = 'Greater London';      // Optional
$address->AddressLine2 = 'Apt 4';         // Optional

Null Reference Errors

Symptom

“Trying to get property of non-object”
Null pointer exceptions

Solution

Always check for null before accessing nested properties:

// Wrong
$redirectUrl = $user->PendingUserAction->RedirectUrl;

// Correct
if ($user->PendingUserAction !== null) {
    $redirectUrl = $user->PendingUserAction->RedirectUrl;
    // Redirect user for SCA
}

// Even safer
$redirectUrl = $user->PendingUserAction->RedirectUrl ?? null;
if ($redirectUrl !== null) {
    // Handle redirect
}

API Response Errors

Invalid Field Errors

Symptom

“One or several required parameters are missing or incorrect”
Field-specific validation errors

Solution

Check the error details for specific field issues:

use MangoPay\Libraries\ResponseException;

try {
    $user = $api->Users->Create($newUser);
} catch (ResponseException $e) {
    $errorDetails = $e->GetErrorDetails();
    
    if ($errorDetails && isset($errorDetails->Errors)) {
        foreach ($errorDetails->Errors as $field => $message) {
            echo "Field '{$field}': {$message}\n";
        }
    }
}

Common field issues:

Invalid country codes (must be ISO 3166-1 alpha-2)
Invalid currency codes (must be ISO 4217)
Email format validation
Birthday must be Unix timestamp
Phone numbers must include country code

Resource Not Found

Symptom

404 Not Found errors
“Resource does not exist” messages

Solution

Common causes:

Wrong environment: Resource exists in sandbox but not in production (or vice versa)
Incorrect ID: Double-check the resource ID
Deleted resource: The resource may have been deleted

try {
    $user = $api->Users->Get($userId);
} catch (ResponseException $e) {
    if ($e->getCode() === 404) {
        echo "User not found. Check ID and environment.\n";
    }
}

Rate Limiting Errors

Symptom

429 Too Many Requests
“Rate limit exceeded” errors

Solution

Implement exponential backoff and rate limit monitoring:

use MangoPay\Libraries\ResponseException;

function makeApiCallWithRetry($callable, $maxRetries = 3) {
    $retries = 0;
    
    while ($retries < $maxRetries) {
        try {
            return $callable();
        } catch (ResponseException $e) {
            if ($e->getCode() === 429) {
                $retries++;
                $waitTime = pow(2, $retries); // Exponential backoff
                sleep($waitTime);
            } else {
                throw $e;
            }
        }
    }
    
    throw new Exception("Max retries exceeded");
}

// Usage
$user = makeApiCallWithRetry(function() use ($api, $userId) {
    return $api->Users->Get($userId);
});

// Check rate limits
$rateLimits = $api->RateLimits;
if ($rateLimits[0]->CallsRemaining < 10) {
    // Slow down requests
}

SCA (Strong Customer Authentication) Issues

Missing SCA Redirect

Symptom

User not redirected for authentication
SCA required but no redirect URL

Solution

Check for SCA requirement and handle redirect:

try {
    $payIn = $api->PayIns->CreateCardDirect($payIn);
    
    if ($payIn->Status === 'CREATED') {
        // Check for 3DS redirect
        if (isset($payIn->ExecutionDetails->SecureModeRedirectURL)) {
            $redirectUrl = $payIn->ExecutionDetails->SecureModeRedirectURL;
            header("Location: {$redirectUrl}");
            exit;
        }
    }
} catch (\MangoPay\Libraries\ResponseException $e) {
    if ($e->getCode() === 401) {
        $errorDetails = $e->GetErrorDetails();
        if (isset($errorDetails->Data['RedirectUrl'])) {
            $redirectUrl = $errorDetails->Data['RedirectUrl'];
            header("Location: {$redirectUrl}");
            exit;
        }
    }
}

Missing Browser Info or IP Address

Symptom

“IpAddress is required” error
“BrowserInfo is required” error

Solution

For 3DS2, you must provide browser information:

use MangoPay\BrowserInfo;

$payIn->ExecutionDetails->IpAddress = $_SERVER['REMOTE_ADDR'];

$payIn->ExecutionDetails->BrowserInfo = new BrowserInfo();
$payIn->ExecutionDetails->BrowserInfo->AcceptHeader = $_SERVER['HTTP_ACCEPT'];
$payIn->ExecutionDetails->BrowserInfo->JavaEnabled = false;
$payIn->ExecutionDetails->BrowserInfo->Language = substr($_SERVER['HTTP_ACCEPT_LANGUAGE'], 0, 2);
$payIn->ExecutionDetails->BrowserInfo->ColorDepth = 24;
$payIn->ExecutionDetails->BrowserInfo->ScreenHeight = 1080;
$payIn->ExecutionDetails->BrowserInfo->ScreenWidth = 1920;
$payIn->ExecutionDetails->BrowserInfo->TimeZoneOffset = 0;
$payIn->ExecutionDetails->BrowserInfo->UserAgent = $_SERVER['HTTP_USER_AGENT'];
$payIn->ExecutionDetails->BrowserInfo->JavascriptEnabled = true;

In a real application, you should collect this information from the client-side using JavaScript.

KYC Document Upload Issues

File Upload Failures

Symptom

Upload timeout
File size errors
Invalid file format

Solution

Ensure file meets requirements:

// Check file before upload
$filePath = '/path/to/document.pdf';
$fileSize = filesize($filePath);
$maxSize = 7 * 1024 * 1024; // 7 MB

if ($fileSize > $maxSize) {
    throw new Exception("File too large. Maximum size: 7MB");
}

$allowedTypes = ['image/jpeg', 'image/png', 'application/pdf'];
$mimeType = mime_content_type($filePath);

if (!in_array($mimeType, $allowedTypes)) {
    throw new Exception("Invalid file type. Allowed: JPEG, PNG, PDF");
}

// Increase timeout for uploads
$api->Config->CurlResponseTimeout = 120;

// Create KYC page
$page = $api->KycDocuments->CreateKycPage($userId, $kycDocumentId, $filePath);

File requirements:

Maximum size: 7 MB per file
Formats: JPEG, PNG, PDF
Total pages: Maximum 10 per document

Document Validation Failures

Symptom

Document refused
Status changed to VALIDATION_ASKED then REFUSED

Solution

Check the Flags field for specific refusal reasons:

$document = $api->KycDocuments->Get($userId, $kycDocumentId);

if ($document->Status === 'REFUSED' && $document->Flags) {
    foreach ($document->Flags as $flag => $value) {
        echo "Refusal reason: {$flag}\n";
    }
    
    // Common flags:
    // DOCUMENT_UNREADABLE - Poor quality, improve scan
    // DOCUMENT_NOT_ACCEPTED - Wrong document type
    // DOCUMENT_EXPIRED - Document has expired
    // DOCUMENT_INCOMPLETE - Missing pages
    // DOCUMENT_DO_NOT_MATCH_USER_DATA - Name/DOB mismatch
    // DOCUMENT_FALSIFIED - Document appears fake
    // SPECIFIC_CASE - Contact support
}

Payment Issues

Card Registration Failures

Symptom

Invalid card data
Registration fails

Solution

Follow the complete registration flow:

// Step 1: Create card registration
$cardReg = new \MangoPay\CardRegistration();
$cardReg->UserId = $userId;
$cardReg->Currency = 'EUR';
$cardReg->CardType = 'CB_VISA_MASTERCARD';

$createdReg = $api->CardRegistrations->Create($cardReg);

// Step 2: Client-side tokenization (use JavaScript)
// Send card data to $createdReg->CardRegistrationURL
// Receive RegistrationData

// Step 3: Complete registration
$cardReg->Id = $createdReg->Id;
$cardReg->RegistrationData = $registrationDataFromClient;

try {
    $updatedReg = $api->CardRegistrations->Update($cardReg);
    $cardId = $updatedReg->CardId;
} catch (ResponseException $e) {
    if (strpos($e->GetMessage(), 'errorCode=105202') !== false) {
        echo "Card number is invalid";
    } elseif (strpos($e->GetMessage(), 'errorCode=105203') !== false) {
        echo "Expiry date is invalid";
    } elseif (strpos($e->GetMessage(), 'errorCode=105204') !== false) {
        echo "CVV is invalid";
    }
}

Never send card details directly to your server. Always use client-side tokenization.

PayIn Failures

Symptom

PayIn status is FAILED
Various result codes

Solution

Check the ResultCode for specific failure reasons:

$payIn = $api->PayIns->Get($payInId);

if ($payIn->Status === 'FAILED') {
    echo "Result Code: " . $payIn->ResultCode . "\n";
    echo "Result Message: " . $payIn->ResultMessage . "\n";
    
    // Common result codes:
    // 101001 - Generic transaction cancelled
    // 101002 - Transaction refused by bank
    // 101101 - Insufficient funds
    // 101102 - Card limit exceeded
    // 101103 - Authorization limit exceeded
    // 101104 - Card inactive
    // 101105 - Card expired
    // 101106 - Card invalid
    // 101399 - 3DS authentication failed
    // 105202 - Invalid card number
    // 105203 - Invalid expiry date
    // 105204 - Invalid CVV
}

Full list of result codes

Composer and Dependency Issues

Version Conflicts

Symptom

Composer cannot resolve dependencies
PSR/Log version conflicts

Solution

The SDK supports psr/log versions 1.x through 3.x:

# Update composer
composer update mangopay4/php-sdk

# If conflicts persist, try:
composer update mangopay4/php-sdk --with-all-dependencies

# Or specify version explicitly
composer require mangopay4/php-sdk:^3.50

Autoloader Issues

Symptom

Class not found errors
Autoload errors

Solution

Regenerate autoloader:

composer dump-autoload

Ensure you’re including the autoloader:

require_once __DIR__ . '/vendor/autoload.php';

PHP Version Issues

Deprecated Features

Symptom

Deprecated warnings in PHP 7.4+
Dynamic property warnings in PHP 8.2+

Solution

Ensure you’re using SDK version 3.45.1+ for PHP 8.2 compatibility.

composer require mangopay4/php-sdk:^3.45

If you see deprecation warnings, they’re usually safe to ignore or can be suppressed:

error_reporting(E_ALL & ~E_DEPRECATED);

Getting Additional Help

GitHub Issues

Report bugs or request features

API Documentation

Complete API reference

Result Codes

Error code reference

Support Portal

Contact Mangopay support

Debugging Tips

Enable Debug Mode

// Enable detailed error reporting
error_reporting(E_ALL);
ini_set('display_errors', 1);

// Enable SDK logging
$logger = new \Monolog\Logger('mangopay-debug');
$logger->pushHandler(new \Monolog\Handler\StreamHandler('php://stdout', \Monolog\Logger::DEBUG));
$api->setLogger($logger);

Inspect Raw API Responses

When debugging, you can inspect the raw response:

try {
    $user = $api->Users->Create($newUser);
} catch (\MangoPay\Libraries\ResponseException $e) {
    echo "HTTP Status: " . $e->getCode() . "\n";
    echo "Error Message: " . $e->GetMessage() . "\n";
    echo "Error Details:\n";
    var_dump($e->GetErrorDetails());
}

If you’re still experiencing issues after trying these solutions, please open an issue on GitHub with:

SDK version
PHP version
Complete error message
Code snippet (remove sensitive data)

Additional Resources

​Authentication Issues

​OAuth Token File Problems

​Invalid Credentials

​Wrong Environment

​SSL/TLS Issues

​Certificate Verification Failures

​TLS Version Issues

​Timeout Issues

​Request Timeouts

​Script Execution Timeout

​Type Errors and Object Issues

​Money Object Errors

​Address Object Errors

​Null Reference Errors

​API Response Errors

​Invalid Field Errors

​Resource Not Found

​Rate Limiting Errors

​SCA (Strong Customer Authentication) Issues

​Missing SCA Redirect

​Missing Browser Info or IP Address

​KYC Document Upload Issues

​File Upload Failures

​Document Validation Failures

​Payment Issues

​Card Registration Failures

​PayIn Failures

​Composer and Dependency Issues

​Version Conflicts

​Autoloader Issues

​PHP Version Issues

​Deprecated Features

​Getting Additional Help

GitHub Issues

API Documentation

Result Codes

Support Portal

​Debugging Tips

​Enable Debug Mode

​Inspect Raw API Responses

Build docs developers (and LLMs) love

Authentication Issues

OAuth Token File Problems

Invalid Credentials

Wrong Environment

SSL/TLS Issues

Certificate Verification Failures

TLS Version Issues

Timeout Issues

Request Timeouts

Script Execution Timeout

Type Errors and Object Issues

Money Object Errors

Address Object Errors

Null Reference Errors

API Response Errors

Invalid Field Errors

Resource Not Found

Rate Limiting Errors

SCA (Strong Customer Authentication) Issues

Missing SCA Redirect

Missing Browser Info or IP Address

KYC Document Upload Issues

File Upload Failures

Document Validation Failures

Payment Issues

Card Registration Failures

PayIn Failures

Composer and Dependency Issues

Version Conflicts

Autoloader Issues

PHP Version Issues

Deprecated Features

Getting Additional Help

Debugging Tips

Enable Debug Mode

Inspect Raw API Responses