SEPA Direct Debit

In order to perform a SEPA (Single Euro Payments Area) direct debit via the RESTful payment API you need to use the requestType = "SepaSaleTransaction" in combination with paymentMethod = "sepa". For a credit use requestType = "SepaCreditTransaction" in combination with paymentMethod = "sepa".

Under the sepa object the following fields are expected:

Field name	Type	Description
`iban`	Mandatory	Send the IBAN (International Bank Account Number) of the cardholder
`name`	Mandatory	Name of the cardholder
`email`	Optional	Mail address of the cardholder
`mandate.reference`	Mandatory for `requestType` 'SepaSaleTransaction'	Number of the SEPA mandate
`mandate.signatureDate`	Mandatory for `requestType` 'SepaSaleTransaction'	Date when the cardholder has provided the approval for the direct debit
`mandate.type`	Mandatory for `requestType` 'SepaSaleTransaction'	Type of the mandate. Possible values: SINGLE, FIRST_COLLECTION; RECURRING_COLLECTION, FINAL_COLLECTION

In case you want to initiate recurring SEPA direct debits, then we recommend to include the createToken object into the request for first collection. In the response you will receive a token from our gateway which you can use for recurring and final collection. Otherwise, you will need to save the IBAN from the customer.

For more details please refer to the API reference.

Sale

The following JSON document represent an example of request and response of SepaSaleTransaction including minimal set of elements:

{
    "requestType": "SepaSaleTransaction",
    "order": {
        "orderId": 330655
    },
    "transactionAmount": {
        "total": 2.5,
        "currency": "EUR"
    },
    "paymentMethod": {
        "sepa": {
            "iban": "DE1234567895678912345",
            "name": "Max Mustermann",
            "mandate": {
                "reference": "REXF199901629623-01",
                "signatureDate": "2024-05-08",
                "type": "SINGLE"
            }
        }
    },
    "transactionOrigin": "ECOM"
}

{
    "type": "transactionResponse",
    "clientRequestId": "xxxba39-f99b-43a2-xxxx-e56xxxb5ec2b",
    "apiTraceId": "Zk8@xxxKDTEnxxxzublAAAAn4",
    "ipgTransactionId": "8300000006305",
    "orderId": "31234455",
    "transactionType": "SALE",
    "paymentToken": {
        "reusable": true,
        "declineDuplicates": false,
        "type": "PAYMENT_CARD"
    },
    "transactionOrigin": "ECOM",
    "paymentMethodDetails": {
        "paymentCard": {
            "number": "DE1234...2345",
            "bic": "BYLXXXM1001"
        },
        "paymentMethodType": "DEBITDE",
        "paymentMethodBrand": "DEBITDE"
    },
    "terminalId": "99998877",
    "merchantId": "77889966",
    "transactionTime": 1716469469,
    "approvedAmount": {
        "total": 2.50,
        "currency": "EUR",
        "components": {
            "subtotal": 2.50
        }
    },
    "transactionAmount": {
        "total": 2.50,
        "currency": "EUR",
        "components": {
            "subtotal": 2.50
        }
    },
    "transactionStatus": "APPROVED",
    "approvalCode": "Y:000000:9896846305:PPXM:0603158503",
    "processor": {
        "referenceNumber": "000000",
        "authorizationCode": "000000",
        "responseCode": "00",
        "responseMessage": "Function performed error-free"
    }

Recurring Direct Debit

In order to send a subsequent direct debit you will need to use the requestType 'PaymentTokenSaleTransaction' and include the same fields as for single direct debit or first collection of a direct debit but placed under the paymentMethod.sepaMandate object. For this approach, you can use the paymentToken.value object.

Alternatively, you can use the same requestType as for a single or recurring collection of a direct debit but send the iban to our gateway. Please note that this means, that you will need to comply with rules of PCI DSS.

Independent of the chosen approach, for a recurring or final collection you will need to use one of the following values for mandate.type:

RECURRING_COLLECTION
FINAL_COLLECTION

Credit (naked refund)

The following JSON document represent an example of request and response of SepaCreditTransaction including minimal set of elements:

{
    "requestType": "SepaCreditTransaction",
    "transactionOrigin": "ECOM",
    "transactionAmount": {
        "total": "12.76",
        "currency": "EUR"
    },
    "paymentMethod": {
        "sepa": {
            "iban": "DE89370400440532013000",
            "name": "Demo Merchant"
        }
    }
}

{
    "type": "transactionResponse",
    "clientRequestId": "1ef7e391-a7c3-4044-91fa-6468a7ab45a1",
    "apiTraceId": "Zv1HwMcdhTUSRd-8BKB5iQAAA4s",
    "ipgTransactionId": "84668712481",
    "orderId": "R-599686be-a032-460d-b425-daaf21b1befb",
    "transactionType": "CREDIT",
    "paymentToken": {
        "reusable": true,
        "declineDuplicates": false,
        "type": "PAYMENT_CARD"
    },
    "transactionOrigin": "ECOM",
    "paymentMethodDetails": {
        "paymentCard": {
            "number": "DE8937...3000",
            "bic": "COBADEFFXXX"
        },
        "paymentMethodType": "DEBITDE",
        "paymentMethodBrand": "DEBITDE"
    },
    "terminalId": "54080602",
    "merchantId": "54080602",
    "transactionTime": 1727875008,
    "approvedAmount": {
        "total": 12.76,
        "currency": "EUR",
        "components": {
            "subtotal": 12.76
        }
    },
    "transactionAmount": {
        "total": 12.76,
        "currency": "EUR",
        "components": {
            "subtotal": 12.76
        }
    },
    "transactionStatus": "APPROVED",
    "approvalCode": "Y:000000:4668712481:PPXM:5945276816",
    "processor": {
        "referenceNumber": "000000",
        "authorizationCode": "000000",
        "responseCode": "00",
        "responseMessage": "Function performed error-free",
        "taxRefundData": {}
    }
}

Sale

Recurring Direct Debit

Credit (naked refund)

API Products

Point of Sale

Developer

Resources