Desktop / Mobile Website Browser
Use this step-by-step guide to build an integration to accept SEPA Direct Debit payments.
Step 1: Create a PaymentIntent
Create a PaymentIntent object with a request_id, amount, currency and a merchant_order_id from your backend server.
If you want to skip verification for all transactions, please contact your Airwallex account manager for instructions.
Step 2: [Optional] Get available payment methods
To be able to display SEPA Direct Debit as a payment option on your checkout page, you need to get available payment methods from Airwallex API.
When the PaymentIntent is created, send a GET request with parameters country_code, transaction_currency, transaction_mode to Get available Payment Method types API to query for a list of available payment methods based on the information provided.
The response will contain the required fields and necessary resources of each payment method for you to display them on your page. Render payment methods returned in items to show all available payment methods to the shopper at checkout page.
Alternatively, you can maintain available payment methods and corresponding resources locally on your server if you do not want to use this API endpoint. However, we highly recommend you get available payment methods dynamically from this API to avoid any trouble when payment method information or resources get updated.
Step 3. Collect payment method details and mandate acknowledgement
When a shopper submits SEPA Direct Debit on checkout form, you should use payment_intent.confirm to collect the mandate and complete the payment. For SEPA Direct Debit, we support two verification methods: TrueLayer and micro-deposit.
Option 1: TrueLayer verification
TrueLayer requires bank_name when confirming the PaymentIntent. You can call Get available bank names API with payment_method_type to get the supported banks. Supported country codes include GB, AT, BE, DE, ES, FI, FR, IE, IT, LT, NL, PL, PT, SE.
Example request
Set the verification method to truelayer using thepayment_method_options.sepa_direct_debit.verification_method field. You can also provide owner_name and owner_email in the request so that the shopper will see these fields pre-filled on the confirmation page.
Example request
Example response
Option 2: Micro-deposit verification
You can also verify SEPA Direct Debit with micro-deposits by providing the following payload.
Example request
When fraud scanning requires you to VERIFY the account, you will find the next actions in the response of Confirm a PaymentIntent API.
Example response
Airwallex will send a notification email to your shopper automatically to guide them on micro-deposits verification. If you want to customize the experience, please contact our Sales Support to turn off the Airwallex notification email and use the url returned in the response to build your own verification flow.
You can use instructions as below to guide your shoppers on checkout. Learn more about micro-deposit verification.
This account cannot be charged at the moment, please verify the account.
You will receive two micro-deposits to your account in 1-2 business days. You can click the verify button or verify through the email we have sent you.
Step 4: [Optional] Send Direct Debit confirmation email
Airwallex will send Direct Debit confirmation emails on your behalf to shoppers. You can customize the emails by providing your company logo and support email address to your account manager. If you choose to turn off Airwallex notification emails and send your own, you should use payment_consent.verified or payment_intent.pending to trigger advance notice email. For more information, see Mandate.
Step 5: Wait for notification from Airwallex
SEPA Direct Debit is a delayed notification payment method, which means that the transaction cannot be authorized instantly. A SEPA Direct Debit PaymentIntent remains in a pending state after submission to the SEPA network. Once the payment succeeds, the associated PaymentIntent status updates from PENDING to SUCCEEDED.
The following events are sent when the status is updated.
| EVENT | DESCRIPTION | NEXT STEPS |
|---|---|---|
payment_intent.pending | The customer’s payment is submitted to Airwallex successfully. | Wait for the initiated payment to succeed or fail. |
payment_intent.succeeded | The customer’s payment has succeeded. | Provision goods and services. |
payment_attempt.authorization_failed | The customer’s payment is declined. | Contact the customer and request for another payment method. |
payment_consent.pending_verification | The payment is undergoing the verification process. | N/A. This status should last for a short time for TrueLayer verification, but may take 1-2 days for micro-deposit verification. |
payment_consent.verified | The customer’s Direct Debit has been successfully set up. | If you have disabled the mandate confirmation emails sent from Airwallex, you should notify your customers that the Direct Debit mandate has been successfully set up. |
dispute.accepted | Any bank rejections or chargebacks are treated as disputes by Airwallex. The amount of the dispute is deducted from your pending settlement amount. | You cannot defend against SEPA Direct Debit disputes. You must contact your customer to resolve the situation. |
Succeeded PaymentIntents can be disputed due to various reasons. You should familiarize with the dispute risks of direct debits and contact your customers to resolve the situation. Learn more about disputes.
If the transaction fails after the request is sent to bank, you can get the failed reason from the webhook event payment_attempt.authorization_failed.
You can also query the status of a payment anytime using Retrieve a PaymentIntent API.
Step 6: Test SEPA Direct Debit in Demo environment
Use the following details to test SEPA Direct Debit in the demo environment.
1. Account verification
1.1 Account verification using Truelayer
| Account holder name | Test scenario |
|---|---|
| John Doe | For successful Truelayer verification |
| Any other name | For failed Truelayer verification |
1.2 Account verification using micro-deposits
| Account number | Test scenario |
|---|---|
| DE400000000000000 | Verification required |
| DE100000000000000 | No verification required |
| Verification amounts | Test scenario |
|---|---|
| 0.04, 0.04 | For failed verification |
| Any other amount | For successful verification |
2. Payment
| Payment amounts | Test scenario |
|---|---|
| 400 | For failed payment intent |
| Any other amount | For successful payment intent |
3. Refund
| Refund amounts | Test scenario |
|---|---|
| 4 | For failed refund |
| Any other amount less than payment amount | For successful partial/full refund |