Create a Mandate

Note – Mandate expires after 1 hour

If not confirmed within 1 hour of the CreationDate, the Mandate expires with the error 001807 and a new one must be created.

For SDD, if the BankAccountId is a Danish IBAN (starting DK), this endpoint returns a 400 error because they are not currently supported.

Body parameters

BankAccountId · string · required

The unique identifier of the bank account.

Warning: The Bank Account Type must be IBAN for the SEPA scheme and GB for the Bacs scheme.

Culture · string · required

Allowed values: One of the supported languages in the ISO 639-1 format: DE, EN, ES, FR, IT, NL, PL

The language in which the mandate confirmation page is to be displayed. This value only applies to mandates with the SEPA Scheme.

ReturnURL · string · required

Max. length: 220 characters

The URL to which the user is returned after the payment, whether the transaction is successful or not.

Tag · string

Max. length: 255 characters

Custom data that you can add to this object.

Responses

200

Scheme · string

The scheme of the mandate, which is available once the mandate is submitted. The value can be one of the following: 

• BACS – Covers payments in the UK, in GBP only.
• SEPA – Covers payments in the EU.

BankAccountId · string

The unique identifier of the bank account.

Warning: The Bank Account Type must be IBAN for the SEPA scheme and GB for the Bacs scheme.

BankReference · string

The banking reference for the Mandate.

Culture · string

Returned values: One of the supported languages in the ISO 639-1 format: DE, EN, ES, FR, IT, NL, PL

The language in which the mandate confirmation page is to be displayed. This value only applies to mandates with the SEPA Scheme.

DocumentURL · string

The URL at which the mandate document can be downloaded.

ReturnURL · string

Max. length: 220 characters

The URL to which the user is returned after the payment, whether the transaction is successful or not.

RedirectURL · string

The URL to which to redirect the user to complete the payment.

Caution: This variable URL is specific to each payment. You must rely on the returned URL in full (host, path, and queries) and not hardcode any part of it.

Id · string

Max length: 128 characters (see data formats for details)

The unique identifier of the object.

CreationDate · Unix timestamp

The date and time at which the object was created.

Status · string

Returned values: CREATED, SUBMITTED, ACTIVE, FAILED, EXPIRED

The status of the mandate:

• CREATED – The mandate has been generated but not yet confirmed.
• SUBMITTED – The mandate has been confirmed and sent to the user’s bank, and can be used to request a direct debit pay-in.
• ACTIVE – The mandate has been accepted by the user’s bank or successfully used to process a direct debit direct pay-in. Further pay-ins can be requested.
• FAILED – The mandate has been canceled or otherwise failed, and can no longer be used for payments.
• EXPIRED – No payment has been made against the mandate in the last 24 months. It can no longer be used for payments.

UserId · string

The unique identifier of the User (natural or legal) who owns the bank account.

ExecutionType · string

Returned values: WEB

The execution type of the mandate.

MandateType · string

The type of the mandate.

Tag · string

Max. length: 255 characters

Custom data that you can add to this object.

ResultCode · string

The code indicating the result of the operation. This information is mostly used to handle errors or for filtering purposes.

ResultMessage · string

The explanation of the result code.

400 - EN only for BACS

{
   "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
   "Type": "param_error",
   "Id": "277c7c4e-baf1-43f8-ba1d-d9f02d7939e2",
   "Date": 1727958031.0,
   "errors": {
       "Culture": "The requested language is not supported for this bank account"
   }
}  

400 - Language not supported

{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "9d45b954-4eda-4247-b4e3-91027628ab22",
    "Date": 1690294898.0,
    "errors": {
        "Culture": "The requested language is not supported"
    }
}  

200

{
    "Scheme": null,
    "BankAccountId": "bankacc_m_01J999AWHFHW2PQ1ADNQ46AYE9",
    "BankReference": null,
    "Culture": "EN",
    "DocumentURL": "https://api.sandbox.mangopay.com/webhook/eu/public/mandates/e8a73d/dfbdce2a12a442bfae973e56777b3ddb/document?version=2.01",
    "ReturnURL": "https://docs.mangopay.com/please-ignore?MandateId=mdt_m_01J999B9HSEDH9CZDEXXYZGHEZ",
    "RedirectURL": "https://api.sandbox.mangopay.com/mvc/eu/public/mandates/e8a73d/dfbdce2a12a442bfae973e56777b3ddb/confirmation?version=2.01",
    "Id": "mdt_m_01J999B9HSEDH9CZDEXXYZGHEZ",
    "CreationDate": 1727962392,
    "Status": "CREATED",
    "UserId": "user_m_01J8SY95DQ5CM7DH43NQCAS65T",
    "ExecutionType": "WEB",
    "MandateType": "DIRECT_DEBIT",
    "Tag": "Created using the Mangopay API Postman collection",
    "ResultCode": null,
    "ResultMessage": null
}

REST

{
    "BankAccountId": "bankacc_m_01J999AWHFHW2PQ1ADNQ46AYE9",
    "Culture": "EN",
    "ReturnURL": "https://docs.mangopay.com/please-ignore",
    "Tag": "Created using the Mangopay API Postman collection"
}