The ApiMandates class provides methods to create and manage direct debit mandates, which authorize recurring payments from a bank account.
Methods
Create
Create a new mandate.
public function Create($mandate, $idempotencyKey = null)
mandate
\MangoPay\Mandate
required
The Mandate object to create
Optional idempotency key for safe retries
\MangoPay\Mandate - The created Mandate object
Example:
$mandate = new \MangoPay\Mandate();
$mandate->BankAccountId = 'bankaccount_123456';
$mandate->Culture = 'EN';
$mandate->ReturnURL = 'https://example.com/mandate-return';
$result = $api->Mandates->Create($mandate);
// Redirect user to confirm the mandate
header('Location: ' . $result->RedirectURL);
Get
Get a mandate by its ID.
public function Get($mandateId)
The unique identifier of the mandate
\MangoPay\Mandate - The Mandate object
Example:
$mandate = $api->Mandates->Get('mandate_123456');
Cancel
Cancel an active mandate.
public function Cancel($mandateId)
The ID of the mandate to cancel
\MangoPay\Mandate - The updated Mandate object
Example:
$result = $api->Mandates->Cancel('mandate_123456');
if ($result->Status === 'FAILED') {
echo "Mandate canceled successfully";
}
GetAll
Retrieve all mandates.
public function GetAll(& $pagination = null, $filter = null, $sorting = null)
Pagination object (passed by reference)
filter
\MangoPay\FilterTransactions
Filtering options
\MangoPay\Mandate[] - Array of Mandate objects
Example:
$pagination = new \MangoPay\Pagination();
$mandates = $api->Mandates->GetAll($pagination);
foreach ($mandates as $mandate) {
echo "Mandate: " . $mandate->Id . " - " . $mandate->Status . "\n";
}
GetTransactions
Retrieve all transactions for a specific mandate.
public function GetTransactions($mandateId, & $pagination = null, $filter = null, $sorting = null)
Pagination object (passed by reference)
filter
\MangoPay\FilterTransactions
Filtering options
\MangoPay\Transaction[] - Array of Transaction objects
Example:
$pagination = new \MangoPay\Pagination();
$transactions = $api->Mandates->GetTransactions('mandate_123456', $pagination);
foreach ($transactions as $transaction) {
echo "Transaction: " . $transaction->Id . " - " . $transaction->Status . "\n";
}
To get mandates for a specific user, use $api->Users->GetMandates($userId, $pagination, $sorting)
Mandate Entity
The Mandate entity represents a direct debit mandate authorization.
Properties
The unique identifier of the mandate
Unix timestamp of when the mandate was created
The ID of the bank account to associate with this mandate
The ID of the user who owns the mandate
The mandate scheme type: SEPA or BACS (completed once mandate is submitted)
The language for the mandate confirmation page: EN, FR, NL, DE, ES, IT, PL, PT
The URL to view/download the mandate document
The URL to redirect the user to for mandate confirmation
The URL where the user is redirected after mandate confirmation
The status of the mandate: CREATED, SUBMITTED, ACTIVE, FAILED, EXPIRED
The result code of the mandate
The result message explaining the result code
The type of mandate: DIRECT_DEBIT
How the mandate is created: WEB
The unique bank reference for the mandate
Mandate Flow
Step 1: Create the Mandate
// Create a mandate for a bank account
$mandate = new \MangoPay\Mandate();
$mandate->BankAccountId = 'bankaccount_123456';
$mandate->Culture = 'EN';
$mandate->ReturnURL = 'https://example.com/mandate-return';
$result = $api->Mandates->Create($mandate);
echo "Mandate ID: " . $result->Id . "\n";
echo "Status: " . $result->Status . "\n";
echo "Redirect URL: " . $result->RedirectURL . "\n";
Step 2: User Confirmation
// Redirect user to confirm the mandate
header('Location: ' . $result->RedirectURL);
exit;
Step 3: Check Mandate Status
// After user returns to your ReturnURL
$mandate = $api->Mandates->Get($mandateId);
if ($mandate->Status === 'ACTIVE') {
echo "Mandate is active and ready to use";
} elseif ($mandate->Status === 'SUBMITTED') {
echo "Mandate submitted, waiting for activation";
} else {
echo "Mandate status: " . $mandate->Status;
echo "Error: " . $mandate->ResultMessage;
}
Step 4: Use the Mandate for Direct Debit Pay-ins
// Create a direct debit pay-in using the mandate
$payIn = new \MangoPay\PayIn();
$payIn->AuthorId = $userId;
$payIn->CreditedWalletId = $walletId;
$payIn->DebitedFunds = new \MangoPay\Money();
$payIn->DebitedFunds->Currency = 'EUR';
$payIn->DebitedFunds->Amount = 1000;
$payIn->Fees = new \MangoPay\Money();
$payIn->Fees->Currency = 'EUR';
$payIn->Fees->Amount = 10;
$payIn->PaymentType = 'DIRECT_DEBIT';
$payIn->ExecutionType = 'DIRECT';
$paymentDetails = new \MangoPay\PayInPaymentDetailsDirectDebitDirect();
$paymentDetails->MandateId = $mandate->Id;
$payIn->PaymentDetails = $paymentDetails;
$executionDetails = new \MangoPay\PayInExecutionDetailsDirect();
$payIn->ExecutionDetails = $executionDetails;
$result = $api->PayIns->Create($payIn);
SEPA vs BACS Mandates
SEPA (Single Euro Payments Area)
- Used for bank accounts in the European Economic Area
- Supports EUR currency
- Scheme is determined automatically based on bank account country
BACS (Bankers’ Automated Clearing Services)
- Used for bank accounts in the United Kingdom
- Supports GBP currency
- Scheme is determined automatically based on bank account country
Mandates must be confirmed by the user before they can be used for direct debit transactions. Always redirect users to the RedirectURL for confirmation.
Once a mandate is ACTIVE, it can be used for multiple direct debit pay-ins until it expires or is canceled.
