The Mandate object

The activation of the mean of payment is made on request. We reserve the right to refuse its activation if certain conditions are not met by the client. Please contact us for more information.

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 information.
  • 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 few 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
    4. The minimum amount is £1/1€.
  • 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 information).
  • 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. For SEPA, you can immediately make a Direct Debit Payin against the mandate. This first payment will change the status from SUBMITTED to ACTIVE– 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
  • For UK clients: Note that mandates can't be created on accounts where multiple signatures are required (business accounts).

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

To activate the Direct Debit Mandate in production, you must mention on your mandate page that payment is made via our partner Gocardless and you must refer to its privacy policy.

Parameters

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 220 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, EXPIRED

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
  • "EXPIRED" - the mandate is expired and is not 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

BankReference
string

string:

Maximum length is 255 characters

The banking reference for this mandate

{
"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",
"BankReference": "4HAS7JA"
}

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

BankAccountId
string

string:

Maximum length is 255 characters

required

An ID of a BankAccount. Warning : BankAccount should belong to BACS or SEPA network.

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 220 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 :
{
"BankAccountId": "123456",
"Culture": "EN",
"ReturnURL": "http://www.my-site.com/returnURL/"
}
POST .../mandates/directdebit/web/ HTTP/1.1
Body Parameters :
{
"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
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
PUT .../mandates//cancel/ HTTP/1.1

List all Mandates

GET .../v2.01/ClientId

The ID of your client account

/mandates/
  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../mandates/ HTTP/1.1
GET .../mandates/ HTTP/1.1

List a User's Mandates

GET .../v2.01/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/mandates/
  • 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 .../users//mandates/ HTTP/1.1

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/
  • 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 .../users//bankaccounts//mandates/ HTTP/1.1
Share feedback