The Mandate object

A Direct Debit Mandate is an instruction between a user and a bank account which allows you to process payments directly from his bank to a wallet for a dedicated user.

  • After using this method, you can then use it to do a direct debit payin (in a similar way to registering a card and then doing a direct card payin for that card.
  • Mandates and direct debit payin are only available for certain business types, and is not activated by default – please contact your sales manager for more info
  • Mandates cover only payments in Europe, and this is split between two schemes (see Scheme in the mandate object) – BACS (for the UK) and SEPA (the rest of the EU). MANGOPAY handles the complexities and strict compliance regulations in each case, but you should be aware of a couple of particularities:
    1. Only GBP payments can be made with mandates in the BACS Scheme
    2. The confirmation page and emails for mandates in the BACS Scheme are only available in English
    3. Only bank account types GB and IBAN can be used to create a Mandate
  • When a mandate in the BACS Scheme is confirmed by the user, we will send them an email on your behalf (the design of this email, and the confirmation webpage they see, can be lightly customised with your logo and colours – see the client object for more info on that)
  • Once confirmed, mandates have the Status "SUBMITTED which means it has been submitted to the user’s bank and will become "ACTIVE" after a few days. However, you can immediately make payments against the mandate (ie you do not need to wait for the Status to become "ACTIVE") and we will manage the submission process for you – read more about the timings on the payments page
  • For testing mandates, you should use a specific value for the FirstName for the user owning the mandate
    1. "Invalid" will result in a failed mandate due to incorrect bank account information – note that this only works for mandates with the Scheme "BACS"
    2. "Successful" will result in an active mandate, however you must do a payment with this mandate for the status to be updated
  • Note that for all the mandate list methods, the usual pagination and filter parameters are available, such as BeforeDate, AfterDate and Status and you can order by CreationDate

Note that the language for the mandate confirmation pages and mandate PDFs is only English and French for now

Parameters

Id
string

string:

Maximum length is 255 characters

The item's ID

CreationDate
timestamp

timestamp

When the item was created

Tag
string

string:

Maximum length is 255 characters

Custom data that you can add to this item

BankAccountId
string

string:

Maximum length is 255 characters

An ID of a Bank Account

UserId
string

string:

Maximum length is 255 characters

The object owner's UserId

ReturnURL
string

string:

Maximum length is 255 characters

The URL to redirect to after payment (whether successful or not)

RedirectURL
string

string:

Maximum length is 255 characters

The URL to redirect to user to for them to proceed with the payment

DocumentURL
string

string:

Maximum length is 255 characters

The URL to download the mandate

Culture
MandateCultureCode

MandateCultureCode:

EN, FR, NL, DE, ES, IT, PL

The language to use for the mandate confirmation webpage

The language to use for the mandate confirmation page - needs to be the ISO code of the language

Scheme
MandateScheme

MandateScheme:

SEPA, BACS

The mandate scheme

The type of mandate, but will only be completed once the mandate has been submitted

Status
MandateStatus

MandateStatus:

CREATED, SUBMITTED, ACTIVE, FAILED

The status of a mandate

The status of the mandate:

  • "CREATED" - the mandate has been created
  • "SUBMITTED" - the mandate has been submitted to the banks and you can now do payments with this mandate
  • "ACTIVE" - the mandate is active and has been accepted by the banks and/or successfully used in a payment
  • "FAILED" - the mandate has failed for a variety of reasons and is no longer available for payments
ResultCode
string

string:

Maximum length is 255 characters

The result code

ResultMessage
string

string:

Maximum length is 255 characters

A verbal explanation of the ResultCode

ExecutionType
MandateExecutionType

MandateExecutionType:

WEB

The execution type of the mandate

The execution type for creating the mandate

MandateType
MandateType

MandateType:

DIRECT_DEBIT

The type of mandate

The type of Mandate

{
"Id": "8494514",
"CreationDate": 12926321,
"Tag": "custom meta",
"BankAccountId": "14213351",
"UserId": "8494514",
"ReturnURL": "http://www.my-site.com/returnURL/",
"RedirectURL": "http://www.a-url.com/redirect",
"DocumentURL": "http://www.a-url.com/documentURL/",
"Culture": "EN",
"Scheme": "BACS",
"Status": "SUBMITTED ",
"ResultCode": "000000",
"ResultMessage": "The transaction was successful",
"ExecutionType": "WEB",
"MandateType": "DIRECT_DEBIT"
}

Create a Mandate

Note that you need to confirm the mandate within one hour of the CreationDate, otherwise it will expire with the ResultCode "001807"

POST .../v2.01/ClientId

The ID of your client account

/mandates/directdebit/web/

Parameters

Tag
string

string:

Maximum length is 255 characters

optional

Custom data that you can add to this item

BankAccountId
string

string:

Maximum length is 255 characters

required

An ID of a Bank Account

Culture
MandateCultureCode

MandateCultureCode:

EN, FR, NL, DE, ES, IT, PL

The language to use for the mandate confirmation webpage

required

The language to use for the mandate confirmation page - needs to be the ISO code of the language

ReturnURL
string

string:

Maximum length is 255 characters

required

The URL to redirect to after payment (whether successful or not)

  • View
  • Code
  • Run
  • View
  • Code
  • Run
POST .../mandates/directdebit/web/ HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"BankAccountId": "14213351",
"Culture": "EN",
"ReturnURL": "http://www.my-site.com/returnURL/"
}
require_once("mangopay.php");

try {


$Mandate = new \MangoPay\Mandate();
$Mandate->Tag = "custom meta";
$Mandate->BankAccountId = "14213351";
$Mandate->Culture = "EN";
$Mandate->ReturnURL = "http://www.my-site.com/returnURL/";

$Result = $Api->Mandates->Create($Mandate);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
POST .../mandates/directdebit/web/ HTTP/1.1
Body Parameters :
{
"Tag": "",
"BankAccountId": "",
"Culture": "",
"ReturnURL": ""
}

View a Mandate

GET .../v2.01/ClientId

The ID of your client account

/mandates/MandateId

The ID of a Mandate

/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
GET .../mandates/:MandateId/ HTTP/1.1
require_once("mangopay.php");

try {

$MandateId = "blabla";

$Mandate = $Api->Mandates->Get($MandateId);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
GET .../mandates// HTTP/1.1

Cancel a Mandate

Note that the mandate must have the Status of "SUBMITTED"or "ACTIVE" for this to be acceptable

PUT .../v2.01/ClientId

The ID of your client account

/mandates/MandateId

The ID of a Mandate

/cancel/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
PUT .../mandates/:MandateId/cancel/ HTTP/1.1
require_once("mangopay.php");

try {

$Mandate = new \MangoPay\Mandate();
$Mandate->Id = "blabla";

$Result = $Api->Mandates->Cancel($Mandate);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
PUT .../mandates//cancel/ HTTP/1.1

List all Mandates

GET .../v2.01/ClientId

The ID of your client account

/mandates/

Get parameters

Page
int

int

optional

The page number of results you wish to return

Per_Page
int

int

optional

The number of results to return per page

Sort
ColumnAndDirection

ColumnAndDirection:

The column to sort against and direction, separated by a :

optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

BeforeDate
timestamp

timestamp

optional

To return only resources that have CreationDate BEFORE this date

AfterDate
timestamp

timestamp

optional

To return only resources that have CreationDate AFTER this date

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../mandates/ HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC",
"BeforeDate": 1463440221,
"AfterDate": 1431817821
}
GET .../mandates/ HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": "",
"BeforeDate": ,
"AfterDate":
}

List a User's Mandates

GET .../v2.01/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/mandates/

Get parameters

Page
int

int

optional

The page number of results you wish to return

Per_Page
int

int

optional

The number of results to return per page

Sort
ColumnAndDirection

ColumnAndDirection:

The column to sort against and direction, separated by a :

optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

BeforeDate
timestamp

timestamp

optional

To return only resources that have CreationDate BEFORE this date

AfterDate
timestamp

timestamp

optional

To return only resources that have CreationDate AFTER this date

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../users/:UserId/mandates/ HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC",
"BeforeDate": 1463440221,
"AfterDate": 1431817821
}
GET .../users//mandates/ HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": "",
"BeforeDate": ,
"AfterDate":
}

List a Bank Account's Mandates

GET .../v2.01/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/bankaccounts/BankAccountId

The bank account ID of a user

/mandates/

Get parameters

Page
int

int

optional

The page number of results you wish to return

Per_Page
int

int

optional

The number of results to return per page

Sort
ColumnAndDirection

ColumnAndDirection:

The column to sort against and direction, separated by a :

optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

BeforeDate
timestamp

timestamp

optional

To return only resources that have CreationDate BEFORE this date

AfterDate
timestamp

timestamp

optional

To return only resources that have CreationDate AFTER this date

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../users/:UserId/bankaccounts/:BankAccountId/mandates/ HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC",
"BeforeDate": 1463440221,
"AfterDate": 1431817821
}
GET .../users//bankaccounts//mandates/ HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": "",
"BeforeDate": ,
"AfterDate":
}