SEPA direct debit

Parameters for SEPA Direct Debit Payments

As the first step you have to send full qualified mandate data. An integrated mandate management will be available soon.

Structure sepaDirectDebitPaymentMethodSpecificInput

paymentProductId

771

paymentProduct771SpecificInput.mandate.bankAccountIban.iban

IBAN of the end customer's bank account. The IBAN is the International Bank Account Number.

paymentProduct771SpecificInput.mandate.bankAccountIban.accountHolder

Account holder of the bank account with the given IBAN. Does not necessarily have to be the end customer (e.g. joint accounts).

paymentProduct771SpecificInput.mandate.recurrenceType

Specifies whether the mandate is for one-off or recurring payments. Possible values are:

  • UNIQUE
  • RECURRING
paymentProduct771SpecificInput.mandate.uniqueMandateReference

The unique identifier of the mandate

paymentProduct771SpecificInput.mandate.dateOfSignature

The date of signature of the mandate.

paymentProduct771SpecificInput.mandate.creditorId

Your unique creditor identifier.

Example

Simple example for a giropay payment via Commerce Platform

  • Creating a checkout (here in one step, creating in multiple steps possible)
  • Creating an order for the entire checkout (partial orders also possible), SEPA Direct Debit payment is done automatically

Create CommerceCase with Checkout

Creating a CommerceCase with the initial Checkout including reference, information about the end customer and the items in the shopping cart.

POST Commerce Case
Request
/v1/{merchantId}/commerce-cases
{
    "merchantReference": "commerce-case-sepadd-1",
    "customer": {
        "billingAddress": {
            "city": "Musterstadt",
            "countryCode": "DE",
            "houseNumber": "1",
            "street": "Musterstra├če",
            "zip": "12345"
        },
        "merchantCustomerId": "Kunde2345",
        "contactDetails": {
            "emailAddress": "max@mustermann.de",
            "phoneNumber": "+1234567890"
        },
        "personalInformation": {
            "gender": "MALE",
            "name": {
                "firstName": "Max",
                "surname": "Mustermann"
            }
        }
    },
    "checkout": {
        "references": {
            "merchantReference": "sepadd-001"
        },
        "shoppingCart": {
            "items": [
                {
                    "invoiceData": {
                        "description": "sepa pain"
                    },
                    "orderLineDetails": {
                        "productCode": "SDD01",
                        "productPrice": 1299,
                        "productType": "GOODS",
                        "quantity": 1,
                        "taxAmount": 19
                    }
                }
            ]
        }
    }
}

Response
{
    "commerceCaseId": "d3433dbf-8521-4137-8f72-a2060b05c7a0",
    "checkoutId": "38080b46-a6ba-48e6-ab70-6b245d525bd9",
    "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "sepa pain"
                },
                "orderLineDetails": {
                    "id": "e983f355-e015-4089-b140-3da377704195",
                    "productCode": "SDD01",
                    "productPrice": 1299,
                    "productType": "GOODS",
                    "quantity": 1,
                    "taxAmount": 19
                }
            }
        ]
    }
}
Order with SEPA Direct Debit payment

Creating an order for the entire checkout with data for a SEPA Direct Debit payment.

POST Order
Request
/v1/{merchantId}/commerce-cases/{commerceCaseId}/checkout/{checkoutId}/order
{
    "orderType": "FULL",
    "orderReferences": {
        "descriptor": "SEPA SDD payment",
        "merchantReference": "Order-2234521246"
    },
    "paymentMethodSpecificInput": {
        "sepaDirectDebitPaymentMethodSpecificInput": {
            "paymentProductId": 771,
            "paymentProduct771SpecificInput": {
                "mandate": {
                    "bankAccountIban": {
                        "iban": "DE02370502990000684712",
                        "accountHolder": "Max Mustermann"
                    },
                    "recurrenceType": "UNIQUE",
                    "uniqueMandateReference": "your-mandate-id",
                    "dateOfSignature": "20220101",
                    "creditorId": "DE98ZZZ09999999999"
                }
            }
        },
        "paymentChannel": "ECOMMERCE"
    }
}

Response
{
    "createPaymentResponse": {
        "payment": {
            "paymentOutput": {
                "amountOfMoney": {
                    "amount": 1299,
                    "currencyCode": "EUR"
                },
                "references": {
                    "merchantReference": "Order-2234521246"
                },
                "paymentMethod": "directDebit",
                "sepaDirectDebitPaymentMethodSpecificOutput": {
                    "paymentProductId": 771,
                    "paymentProduct771SpecificOutput": {
                        "mandateReference": "your-mandate-id"
                    }
                }
            },
            "status": "CAPTURED",
            "statusOutput": {
                "isCancellable": false,
                "statusCategory": "COMPLETED",
                "isAuthorized": false,
                "isRefundable": true
            },
            "id": "PP2AAD9Q7J6GK6GD"
        },
        "paymentExecutionId": "8a82d57b-14cb-443f-852f-a1dd8b4c4906"
    },
    "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "sepa pain"
                },
                "orderLineDetails": {
                    "id": "e983f355-e015-4089-b140-3da377704195",
                    "productCode": "SDD01",
                    "productPrice": 1299,
                    "productType": "GOODS",
                    "quantity": 1,
                    "taxAmount": 19,
                    "status": [
                        {
                            "lineItemStatus": "ORDERED",
                            "quantity": 1
                        }
                    ]
                }
            }
        ]
}

Webhook after successful SEPA Direct Debit payment

You can identify the corresponding transaction by the field createPaymentResponse.payment.id in the order response. The status CAPTURED shows that the SEPA Direct Debit was processed successfully in the payment gateway and will be sent with the next batch processing to the bank.

Webhook
{
    "apiVersion": "v1",
    "created": "2023-11-15T12:31:32.278828330+00:00",
    "id": "5553da0b-5ec0-4f94-8f02-b2d1fd082bf4",
    "merchantId": "P1_18323_2013224",
    "payment": {
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 1299,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Order-2234521246"
            },
            "sepaDirectDebitPaymentMethodSpecificOutput": {
                "paymentProductId": 771
            },
            "paymentMethod": "directDebit"
        },
        "status": "CAPTURED",
        "statusOutput": {
            "isCancellable": false,
            "statusCategory": "COMPLETED",
            "isAuthorized": false,
            "isRefundable": true
        },
        "id": "PP2AAD9Q7J6GK6GD"
    },
    "type": "payment.captured"
}