Deposits

Overview

Deposits allow you to pre-authorize funds on a user’s card without immediately capturing them. This is useful for scenarios like hotel bookings or rental services where you need to hold funds but may not charge the full amount.

Creating a Deposit

Create a new deposit with pre-authorization:

use MangoPay\CreateDeposit;
use MangoPay\Money;
use MangoPay\Address;
use MangoPay\Billing;
use MangoPay\BrowserInfo;

$userId = 'user_123456';
$cardId = 'card_123456';

$deposit = new CreateDeposit();
$deposit->AuthorId = $userId;
$deposit->CardId = $cardId;

// Set deposit amount
$debitedFunds = new Money();
$debitedFunds->Currency = 'EUR';
$debitedFunds->Amount = 100000; // 1000.00 EUR
$deposit->DebitedFunds = $debitedFunds;

// Required security fields
$deposit->SecureModeReturnURL = "https://www.mysite.com/deposit-return";
$deposit->StatementDescriptor = "Deposit for booking #12345";
$deposit->Culture = "EN";
$deposit->IpAddress = "2001:0620:0000:0000:0211:24FF:FE80:C12C";

// Browser info for 3DS authentication
$browserInfo = new BrowserInfo();
$browserInfo->AcceptHeader = "text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8";
$browserInfo->JavaEnabled = true;
$browserInfo->Language = "en-US";
$browserInfo->ColorDepth = 24;
$browserInfo->ScreenHeight = 1080;
$browserInfo->ScreenWidth = 1920;
$browserInfo->TimeZoneOffset = "-120";
$browserInfo->UserAgent = "Mozilla/5.0";
$browserInfo->JavascriptEnabled = true;
$deposit->BrowserInfo = $browserInfo;

// Billing information
$address = new Address();
$address->AddressLine1 = 'Main Street no 5';
$address->City = 'Paris';
$address->Country = 'FR';
$address->PostalCode = '68400';
$address->Region = 'Europe';

$billing = new Billing();
$billing->FirstName = 'John';
$billing->LastName = 'Doe';
$billing->Address = $address;
$deposit->Billing = $billing;
$deposit->Shipping = $billing; // Can use same or different address

$createdDeposit = $api->Deposits->Create($deposit);

echo "Deposit ID: " . $createdDeposit->Id . "\n";
echo "Status: " . $createdDeposit->PaymentStatus . "\n";

If 3DS authentication is required, redirect the user to $createdDeposit->SecureModeRedirectURL to complete verification.

Getting a Deposit

Retrieve deposit details:

$depositId = 'deposit_123456';
$deposit = $api->Deposits->Get($depositId);

echo "Author: " . $deposit->AuthorId . "\n";
echo "Amount: " . $deposit->DebitedFunds->Amount . " " . $deposit->DebitedFunds->Currency . "\n";
echo "Payment Status: " . $deposit->PaymentStatus . "\n";
echo "Expiration Date: " . date('Y-m-d H:i:s', $deposit->ExpirationDate) . "\n";

// Access card information
if ($deposit->CardInfo !== null) {
    echo "Card Type: " . $deposit->CardInfo->Type . "\n";
    echo "Card Brand: " . $deposit->CardInfo->Brand . "\n";
}

Getting Deposits for a User

Retrieve all deposits for a specific user:

use MangoPay\Pagination;
use MangoPay\FilterPreAuthorizations;
use MangoPay\Sorting;

$userId = 'user_123456';
$pagination = new Pagination(1, 20);
$filter = new FilterPreAuthorizations();
$sorting = new Sorting();

$deposits = $api->Deposits->GetAllForUser($userId, $pagination, $filter, $sorting);

foreach ($deposits as $deposit) {
    echo "Deposit: " . $deposit->Id . " - Status: " . $deposit->PaymentStatus . "\n";
}

Getting Deposits for a Card

Retrieve all deposits associated with a specific card:

$cardId = 'card_123456';
$pagination = new Pagination(1, 20);

$deposits = $api->Deposits->GetAllForCard($cardId, $pagination);

foreach ($deposits as $deposit) {
    echo "Deposit: " . $deposit->Id . " - Amount: " . $deposit->DebitedFunds->Amount . "\n";
}

Canceling a Deposit

Cancel a deposit before it’s captured:

use MangoPay\CancelDeposit;

$depositId = 'deposit_123456';

$cancelDto = new CancelDeposit();
$cancelDto->PaymentStatus = "CANCELED";

$api->Deposits->Cancel($depositId, $cancelDto);

// Verify cancellation
$deposit = $api->Deposits->Get($depositId);
if ($deposit->PaymentStatus === "CANCELED") {
    echo "Deposit canceled successfully";
}

Updating a Deposit

Update deposit details:

use MangoPay\UpdateDeposit;

$depositId = 'deposit_123456';

$updateDto = new UpdateDeposit();
// Update fields as needed
// (specific update fields depend on deposit status)

$updatedDeposit = $api->Deposits->Update($depositId, $updateDto);

Capturing a Deposit

Capture funds from a deposit by creating a pre-authorized deposit pay-in:

use MangoPay\CreateCardPreAuthorizedDepositPayIn;
use MangoPay\Money;

$depositId = 'deposit_123456';
$userId = 'user_123456';
$walletId = 'wallet_123456';

$payIn = new CreateCardPreAuthorizedDepositPayIn();
$payIn->DepositId = $depositId;
$payIn->AuthorId = $userId;
$payIn->CreditedWalletId = $walletId;

// Set amount to capture (can be less than or equal to deposit amount)
$debitedFunds = new Money();
$debitedFunds->Amount = 50000; // 500.00 EUR (capturing partial amount)
$debitedFunds->Currency = "EUR";
$payIn->DebitedFunds = $debitedFunds;

// Set fees
$fees = new Money();
$fees->Amount = 0;
$fees->Currency = "EUR";
$payIn->Fees = $fees;

$capturedPayIn = $api->PayIns->CreateDepositPreauthorizedPayInWithoutComplement($payIn);

echo "Captured: " . $capturedPayIn->DebitedFunds->Amount . " from deposit\n";

You can capture less than the pre-authorized amount, allowing partial captures for scenarios like damage deposits.

Getting Deposit Transactions

Retrieve all transactions associated with a deposit:

use MangoPay\Pagination;
use MangoPay\FilterTransactions;
use MangoPay\Sorting;

$depositId = 'deposit_123456';
$pagination = new Pagination(1, 50);
$filter = new FilterTransactions();
$sorting = new Sorting();

$transactions = $api->Deposits->GetTransactions($depositId, $pagination, $filter, $sorting);

foreach ($transactions as $transaction) {
    echo "Transaction: " . $transaction->Id . "\n";
    echo "Type: " . $transaction->Type . "\n";
    echo "Amount: " . $transaction->DebitedFunds->Amount . "\n";
}

Deposit Payment Statuses

Deposits progress through various payment statuses:

CREATED - Deposit created but not yet processed
WAITING - Awaiting 3DS authentication
TO_BE_COMPLETED - Ready for capture
SUCCEEDED - Deposit successfully captured
CANCELED - Deposit canceled
FAILED - Deposit failed
EXPIRED - Deposit expired before capture

Complete Deposit Workflow

Here’s a complete example of the deposit lifecycle:

use MangoPay\MangoPayApi;
use MangoPay\CreateDeposit;
use MangoPay\CancelDeposit;
use MangoPay\Money;

$api = new MangoPayApi();
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';
$api->Config->TemporaryFolder = '/tmp/';

try {
    // Step 1: Create deposit
    $deposit = new CreateDeposit();
    $deposit->AuthorId = 'user_123456';
    $deposit->CardId = 'card_123456';
    
    $debitedFunds = new Money();
    $debitedFunds->Currency = 'EUR';
    $debitedFunds->Amount = 100000;
    $deposit->DebitedFunds = $debitedFunds;
    
    $deposit->SecureModeReturnURL = "https://www.mysite.com/return";
    $deposit->StatementDescriptor = "Security deposit";
    $deposit->Culture = "EN";
    $deposit->IpAddress = "85.70.150.10";
    // ... add billing, browser info, etc.
    
    $createdDeposit = $api->Deposits->Create($deposit);
    
    // Step 2: Check if 3DS required
    if (!empty($createdDeposit->SecureModeRedirectURL)) {
        // Redirect user for authentication
        header('Location: ' . $createdDeposit->SecureModeRedirectURL);
        exit();
    }
    
    // Step 3: After user returns, check status
    $deposit = $api->Deposits->Get($createdDeposit->Id);
    
    if ($deposit->PaymentStatus === 'TO_BE_COMPLETED') {
        // Step 4a: Capture funds
        $payIn = new \MangoPay\CreateCardPreAuthorizedDepositPayIn();
        $payIn->DepositId = $deposit->Id;
        $payIn->AuthorId = $deposit->AuthorId;
        $payIn->CreditedWalletId = 'wallet_123456';
        
        $amount = new Money();
        $amount->Amount = 50000; // Capture partial amount
        $amount->Currency = 'EUR';
        $payIn->DebitedFunds = $amount;
        
        $fees = new Money();
        $fees->Amount = 0;
        $fees->Currency = 'EUR';
        $payIn->Fees = $fees;
        
        $captured = $api->PayIns->CreateDepositPreauthorizedPayInWithoutComplement($payIn);
        echo "Captured: " . $captured->DebitedFunds->Amount . "\n";
        
    } else {
        // Step 4b: Or cancel if not needed
        $cancelDto = new CancelDeposit();
        $cancelDto->PaymentStatus = "CANCELED";
        $api->Deposits->Cancel($deposit->Id, $cancelDto);
        echo "Deposit canceled\n";
    }
    
} catch (\MangoPay\Libraries\ResponseException $e) {
    echo "API Error: " . $e->getMessage();
} catch (\MangoPay\Libraries\Exception $e) {
    echo "SDK Error: " . $e->getMessage();
}

Authentication Result

Check 3DS authentication results:

$deposit = $api->Deposits->Get($depositId);

if ($deposit->AuthenticationResult !== null) {
    echo "3DS Version: " . $deposit->AuthenticationResult->ThreeDSVersion . "\n";
    echo "Result: " . $deposit->AuthenticationResult->Result . "\n";
    echo "Result Message: " . $deposit->AuthenticationResult->ResultMessage . "\n";
}

Best Practices

Set Appropriate Amounts

Pre-authorize reasonable amounts based on your use case - too high may cause customer concern.

Monitor Expiration

Deposits have expiration dates - capture funds before they expire.

Clear Communication

Inform users about pre-authorization amounts and when funds will be captured.

Handle 3DS Properly

Always implement 3DS authentication flow for security and compliance.

Error Handling

use MangoPay\Libraries\ResponseException;

try {
    $deposit = $api->Deposits->Create($depositData);
} catch (ResponseException $e) {
    switch ($e->getCode()) {
        case 400:
            echo "Invalid request: " . $e->getMessage();
            break;
        case 401:
            echo "Authentication failed";
            break;
        case 403:
            echo "Card blocked or insufficient funds";
            break;
        default:
            echo "Error: " . $e->getMessage();
    }
    
    // Get detailed errors
    $errors = $e->GetErrorDetails();
    foreach ($errors as $error) {
        echo "Error Detail: " . $error->Message . "\n";
    }
}

Card Pre-Authorizations

Learn about standard card pre-authorizations

Pay-Ins

Understand different pay-in methods

Cards

Manage user cards and registrations

3DS Authentication

Implement secure 3DS authentication

Get Started

Core Concepts

Guides

Advanced

Overview

Creating a Deposit

Getting a Deposit

Getting Deposits for a User

Getting Deposits for a Card

Canceling a Deposit

Updating a Deposit

Capturing a Deposit

Getting Deposit Transactions

Deposit Payment Statuses

Complete Deposit Workflow

Authentication Result

Best Practices

Set Appropriate Amounts

Monitor Expiration

Clear Communication

Handle 3DS Properly

Error Handling

Card Pre-Authorizations

Pay-Ins

Cards

3DS Authentication

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Overview

​Creating a Deposit

​Getting a Deposit

​Getting Deposits for a User

​Getting Deposits for a Card

​Canceling a Deposit

​Updating a Deposit

​Capturing a Deposit

​Getting Deposit Transactions

​Deposit Payment Statuses

​Complete Deposit Workflow

​Authentication Result

​Best Practices

Set Appropriate Amounts

Monitor Expiration

Clear Communication

Handle 3DS Properly

​Error Handling

​Related Resources

Card Pre-Authorizations

Pay-Ins

Cards

3DS Authentication

Build docs developers (and LLMs) love

Overview

Creating a Deposit

Getting a Deposit

Getting Deposits for a User

Getting Deposits for a Card

Canceling a Deposit

Updating a Deposit

Capturing a Deposit

Getting Deposit Transactions

Deposit Payment Statuses

Complete Deposit Workflow

Authentication Result

Best Practices

Error Handling

Related Resources