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:
- Only GBP payments can be made with mandates in the BACS Scheme
- The confirmation page and emails for mandates in the BACS Scheme are only available in English
- 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
- "Invalid" will result in a failed mandate due to incorrect bank account information – note that this only works for mandates with the
Scheme
"BACS" - "Successful" will result in an active mandate, however you must do a payment with this mandate for the status to be updated
- "Invalid" will result in a failed mandate due to incorrect bank account information – note that this only works for mandates with the
- Note that for all the mandate list methods, the usual pagination and filter parameters are available, such as
BeforeDate
,AfterDate
andStatus
and you can order byCreationDate
Note that the language for the mandate confirmation pages and mandate PDFs is only English and French for now
Parameters
Id
string:
Maximum length is 255 characters
The item's ID
CreationDate
timestamp
When the item was created
Tag
string:
Maximum length is 255 characters
Custom data that you can add to this item
BankAccountId
string:
Maximum length is 255 characters
An ID of a Bank Account
UserId
string:
Maximum length is 255 characters
The object owner's UserId
ReturnURL
string:
Maximum length is 255 characters
The URL to redirect to after payment (whether successful or not)
RedirectURL
string:
Maximum length is 255 characters
The URL to redirect to user to for them to proceed with the payment
DocumentURL
string:
Maximum length is 255 characters
The URL to download the mandate
Culture
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:
SEPA, BACS
The mandate scheme
The type of mandate, but will only be completed once the mandate has been submitted
Status
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:
Maximum length is 255 characters
The result code
ResultMessage
string:
Maximum length is 255 characters
A verbal explanation of the ResultCode
ExecutionType
MandateExecutionType:
WEB
The execution type of the mandate
The execution type for creating the mandate
MandateType
MandateType:
DIRECT_DEBIT
The type of mandate
The type of Mandate
BankReference
string:
Maximum length is 255 characters
The banking reference for this mandate