Mandates

Create and manage direct debit mandates for recurring payments

Overview

Mandates enable direct debit payments from bank accounts. They allow you to collect recurring payments after obtaining user authorization. The Mangopay PHP SDK provides a complete set of tools to create, retrieve, and manage mandates.

Creating a Mandate

Create a new mandate linked to a user’s bank account:

use MangoPay\Mandate;

// First, ensure the user has a bank account
$userId = 'user_123456';
$bankAccountId = 'bankacc_123456';

$mandate = new Mandate();
$mandate->Tag = "Monthly subscription";
$mandate->BankAccountId = $bankAccountId;
$mandate->ReturnURL = "https://www.mysite.com/returnURL/";
$mandate->Culture = "EN";

$createdMandate = $api->Mandates->Create($mandate);

echo "Mandate ID: " . $createdMandate->Id . "\n";
echo "Redirect URL: " . $createdMandate->RedirectURL . "\n";

After creating a mandate, redirect the user to the RedirectURL to complete the authorization process.

Getting a Mandate

Retrieve details of an existing mandate:

$mandateId = 'mandate_123456';
$mandate = $api->Mandates->Get($mandateId);

echo "Status: " . $mandate->Status . "\n";
echo "Scheme: " . $mandate->Scheme . "\n";
echo "Bank Reference: " . $mandate->BankReference . "\n";

Listing All Mandates

Get all mandates with pagination, filtering, and sorting:

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

$pagination = new Pagination(1, 20);
$filter = new FilterTransactions();
$sorting = new Sorting();
$sorting->AddField("CreationDate", SortDirection::DESC);

$mandates = $api->Mandates->GetAll($pagination, $filter, $sorting);

foreach ($mandates as $mandate) {
    echo "Mandate: " . $mandate->Id . " - Status: " . $mandate->Status . "\n";
}

Canceling a Mandate

Cancel an active mandate:

$mandateId = 'mandate_123456';

try {
    $canceledMandate = $api->Mandates->Cancel($mandateId);
    echo "Mandate canceled successfully";
} catch (\MangoPay\Libraries\ResponseException $e) {
    echo "Error: " . $e->getMessage();
}

You can only cancel mandates with status SUBMITTED or ACTIVE. Mandates with status CREATED will return an error.

Getting Mandate Transactions

Retrieve all transactions associated with a mandate:

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

$transactions = $api->Mandates->GetTransactions(
    $mandateId,
    $pagination,
    $filter,
    $sorting
);

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

Using Mandates for Direct Debit Pay-Ins

Once a mandate is active, use it to create direct debit pay-ins:

use MangoPay\PayIn;
use MangoPay\PayInPaymentDetailsDirectDebit;
use MangoPay\PayInExecutionDetailsDirect;
use MangoPay\Money;

$mandate = $api->Mandates->Get('mandate_123456');
$walletId = 'wallet_123456';
$userId = 'user_123456';

// Create pay-in using the mandate
$payIn = new PayIn();
$payIn->CreditedWalletId = $walletId;
$payIn->AuthorId = $userId;

$payIn->DebitedFunds = new Money();
$payIn->DebitedFunds->Amount = 10000; // 100.00 EUR
$payIn->DebitedFunds->Currency = 'EUR';

$payIn->Fees = new Money();
$payIn->Fees->Amount = 0;
$payIn->Fees->Currency = 'EUR';

// Payment details with mandate
$payIn->PaymentDetails = new PayInPaymentDetailsDirectDebit();
$payIn->PaymentDetails->MandateId = $mandate->Id;

// Execution details
$payIn->ExecutionDetails = new PayInExecutionDetailsDirect();

$createdPayIn = $api->PayIns->Create($payIn);
echo "Direct debit pay-in created: " . $createdPayIn->Id;

Mandate Statuses

Mandates progress through different statuses:

• CREATED - Mandate created but not yet confirmed by user
• SUBMITTED - User has confirmed the mandate
• ACTIVE - Mandate is active and can be used for payments
• FAILED - Mandate confirmation failed
• EXPIRED - Mandate has expired

Mandate Schemes

The SDK supports different direct debit schemes:

• SEPA - Single Euro Payments Area direct debit
• BACS - UK direct debit scheme

Complete Example

Here’s a complete workflow for setting up and using a mandate:

use MangoPay\MangoPayApi;
use MangoPay\Mandate;
use MangoPay\MandateStatus;

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

// Step 1: Create mandate
$mandate = new Mandate();
$mandate->BankAccountId = 'bankacc_123456';
$mandate->ReturnURL = "https://www.mysite.com/mandate-return";
$mandate->Culture = "EN";
$mandate->Tag = "Subscription-User-123";

$createdMandate = $api->Mandates->Create($mandate);

// Step 2: Redirect user to authorize
header('Location: ' . $createdMandate->RedirectURL);
exit();

// Step 3: After user returns, check status
$mandate = $api->Mandates->Get($createdMandate->Id);

if ($mandate->Status === MandateStatus::Submitted || 
    $mandate->Status === MandateStatus::Active) {
    echo "Mandate is ready for use";
    
    // Step 4: Use mandate for direct debit payments
    // (see pay-in example above)
} else {
    echo "Mandate not yet active: " . $mandate->Status;
}

Error Handling

Handle common mandate errors:

use MangoPay\Libraries\ResponseException;

try {
    $mandate = $api->Mandates->Create($mandate);
} catch (ResponseException $e) {
    // Handle API errors
    echo "Error Code: " . $e->getCode() . "\n";
    echo "Error Message: " . $e->getMessage() . "\n";
    
    // Get detailed error information
    $errors = $e->GetErrorDetails();
    foreach ($errors as $error) {
        echo "Detail: " . $error->Message . "\n";
    }
} catch (\MangoPay\Libraries\Exception $e) {
    // Handle SDK errors
    echo "SDK Error: " . $e->getMessage();
}

Best Practices

Store Mandate IDs

Save mandate IDs in your database to reuse them for recurring payments.

Check Status

Always verify mandate status before attempting a direct debit payment.

Handle Webhooks

Set up webhooks to receive notifications about mandate status changes.

User Communication

Clearly communicate to users when they’re authorizing a mandate for recurring payments.

Related Resources

Bank Accounts

Learn how to create and manage bank accounts

Pay-Ins

Understand different pay-in methods