How to process a SEPA Direct Debit payment
Introduction
This how-to guide will show you how to successfully process a direct debit payment with the SEPA network.
Prerequisites
- A
ClientId
and an API key – if you don’t have these, contact Sales to get access to the Mangopay Hub - A user with a wallet, in order to make the payment
- Activation of the feature by Mangopay teams
Direct debit is a way of processing payments by pulling funds from the end user’s bank account directly to a wallet.
To process direct debits, Mangopay relies on a mandate, which is an agreement from the end user allowing a third party to collect the payment in the future.
Learn more about direct debits
1. Create the user’s Bank Account
Create the Bank Account object from which the funds will be pulled.
Note that:
- You need to use the
UserId
of the user as a path parameter for the following steps to be successful. - You can use Mangopay’s IBAN bank account available in the Testing payouts article.
Caution - The bank account must belong to the SEPA network
Only IBAN-type Bank Accounts can be used for SEPA Direct Debits.
You’ll need the returned Bank Account Id
value for the next step.
2. Create the Mandate
Create the Mandate for the IBAN Bank Account you’ve just created.
You’ll need the returned Mandate Id
value for some of the next steps.
3. Make sure the end user confirms the mandate in due time
Mandates expire 1 hour after their CreationDate
.
Provide the RedirectURL
returned with the Mandate object to the end user. We advise you to indicate the expiration time as well.
Once the user has visited the page and clicked on the Confirm button, the Mandate Status
becomes SUBMITTED
.
Best practice - Rely on webhooks for mandate activation
You can get notified when a Mandate turns active or expires by subscribing to the corresponding events:
- MANDATE_EXPIRED
- MANDATE_SUBMITTED
Learn more about Hook notifications and Event types.
4. Make the direct debit pay-in
Once your Mandate has a Status
of SUBMITTED
, you can make the direct debit pay-in.
If the pay-in is successful, the SEPA Mandates will become ACTIVE
.
Note - 5-day processing time
Direct debit pay-ins are not instantaneous, there will always be a delay between the moment the transaction is CREATED
until it reaches the SUCCEEDED
status. For SEPA Mandates, it usually takes 5 business days.
5. Cancel the Mandate
Once you no longer need to make payment against the mandate, you need to cancel it.
Use the Cancel a Mandate endpoint to do so.
Warning - Call requires Content-Length
adjustment
For this call to succeed, you need to define the header Content-Length
to 0
.
As a result, the Mandate Status
turns to FAILED
, and you can no longer make payments against it.