SEPA Direct Debit

Integration

One-off payments
Recurring payments
Refunds
Webhooks

This product doesn't support the MyCheckout hosted payment pages integration. You can build your SEPA Direct Debit integration using our APIs or available SDKs in different programming languages.

Before you begin

To follow along with this guide, please ensure that you have the following ready:

Correct API endpoint
Way to construct the authorization header (API Explorer, SDKs, etc.)
Way to send REST API calls (API Explorer, SDKs, etc.)
Your own checkout page UI

One-off payments

Create a token

Before making a SEPA Direct Debit payment you need to obtain a token using POST https://{domainname}/v1/{merchantId}/tokens API call.

Below, you'll find an example request containing the essential data. For more information, please refer to our API Reference.

Property	Data type	Required
paymentProductId	integer	yes
sepaDirectDebit	object	yes
customer	object	yes
billingAddress	object	yes
countryCode	string	yes
mandate	object	yes
bankAccountIban	object	yes
accountHolderName	string	yes
iban	string	yes
debtor	object	yes
surname	string	yes

POST TOKENS REQUEST

{
  "paymentProductId": 770,
  "sepaDirectDebit": {
    "customer": {
      "billingAddress": {
        "countryCode": "NL"
      }
    },
    "mandate": {
      "bankAccountIban": {
        "accountHolderName": "Theo Mayer",
        "iban": "NL40ABNA5861098352"
      },
      "debtor": {
        "surname": "Mayer"
      }
    }
  }
}

The result of processing this request is shown below. You need to save this token because further communication is not possible without specifying this token.

POST TOKENS RESPONSE

{
    "isNewToken": true,
    "token": "a326af5e-db47-43b8-bbb4-8b8fa04b5391"
}

Confirm token

After creating a token, you need to confirm it using POST https://{domainname}/v1/{merchantId}/tokens/{tokenId}/approvesepadirectdebit API call.

Property	Data type	Required
mandateSignatureDate	string	yes
mandateSignaturePlace	string	yes
mandateSigned	boolean	yes

APPROVE SEPA DD MANDATE REQUEST

{
    "mandateSignaturePlace": "Monument Valley",
    "mandateSignatureDate": "20200107",
    "mandateSigned": true
}

A successful response for this request will be an HTTP status of 204. If the token has already been validated, the response will look like this:

APPROVE SEPA DD MANDATE RESPONSE

{
    "errorId": "6617caba5da562890912d54db99fc09d",
    "errors": [
        {
            "code": "700647",
            "requestId": "463",
            "message": "MANDATE ALREADY SIGNED",
            "httpStatusCode": 400
        }
    ]
}

Initiate the payment

To create a payment, use POST https://{domainname}/v1/{merchantId}/payments API call.

Property	Data type	Required
order	object	yes
amountOfMoney	object	yes
currencyCode	string	yes
amount	integer	yes
customer	object	yes
billingAddress	string	yes
countryCode	string	yes
sepaDirectDebitPaymentMethodSpecificInput	object	yes
recurringPaymentSequenceIndicator	string	depends
isRecurring	boolean	yes
directDebitText	string	yes
paymentProductId	string	no
token	string	yes

POST PAYMENTS REQUEST

{
  "order": {
    "amountOfMoney": {
      "currencyCode": "EUR",
      "amount": 1599
    },
    "customer": {
      "billingAddress": {
        "countryCode": "NL"
      }
    }
  },
  "sepaDirectDebitPaymentMethodSpecificInput": {
    "isRecurring": false,
    "directDebitText": "Portable record player mini",
    "paymentProductId": 770,
    "token": "df8e21c5-de6d-4df9-9c67-f9cccdb2c6ca"
  }
}

POST PAYMENTS RESPONSE

{
   "creationOutput" : {
      "additionalReference" : "00000880051000014065",
      "externalReference" : "000008800510000140650000100001"
   },
   "merchantAction" : {
      "actionType" : "SHOW_TRANSACTION_RESULTS",
      "showData" : [ {
         "key" : "PAYMENTREFERENCE",
         "value" : "0"
      }, {
         "key" : "ORDERID",
         "value" : "1000014065"
      } ]
   },
   "payment" : {
      "id" : "000008800510000140650000100001",
      "paymentOutput" : {
         "amountOfMoney" : {
            "amount" : 1599,
            "currencyCode" : "EUR"
         },
         "references" : {
            "paymentReference" : "0"
         },
         "paymentMethod" : "directDebit",
         "sepaDirectDebitPaymentMethodSpecificOutput" : {
            "paymentProductId" : 770
         }
      },
      "status" : "PENDING_APPROVAL",
      "statusOutput" : {
         "isCancellable" : true,
         "isRetriable" : false,
         "statusCategory" : "PENDING_MERCHANT",
         "statusCode" : 600,
         "statusCodeChangeDateTime" : "20240501160545",
         "isAuthorized" : false,
         "isRefundable" : false
      }
   }
}

Approve payment

To approve/capture the payment, use POST https://{domainname}/v1/{merchantId}/payments/{paymentId}/approve API call.

Property	Data type	Required
token	string	no
dataCollect	string	no

APPROVE PAYMENT REQUEST

{
    "directDebitPaymentMethodSpecificInput" : {
        "token" : "df8e21c5-de6d-4df9-9c67-f9cccdb2c6ca",
        "dateCollect" : "20240508"
    },
    "order" : {
        "references" : {
            "merchantReference" : "MusicWorld"
        }
    },
    "amount" : 1599
}

APPROVE PAYMENT RESPONSE

{
   "payment" : {
      "id" : "000008800510000140650000100001",
      "paymentOutput" : {
         "amountOfMoney" : {
            "amount" : 1599,
            "currencyCode" : "EUR"
         },
         "references" : {
            "paymentReference" : "0"
         },
         "paymentMethod" : "directDebit",
         "sepaDirectDebitPaymentMethodSpecificOutput" : {
            "paymentProductId" : 770
         }
      },
      "status" : "CAPTURE_REQUESTED",
      "statusOutput" : {
         "isCancellable" : true,
         "isRetriable" : false,
         "statusCategory" : "PENDING_CONNECT_OR_3RD_PARTY",
         "statusCode" : 800,
         "statusCodeChangeDateTime" : "20240508152943",
         "isAuthorized" : false,
         "isRefundable" : false
      }
   }
}

The sequence of approving SEPA Direct Debit payment and creating a payment does not matter, either API call can be submitted first. However, the payment can only be approved (captured) after the SEPA Direct Debit mandate has been approved.

Recurring payments

Create token for recurring payments

The process for creating recurring payments is only slightly different from regular once-off payments. You need to create a token with POST https://{domainname}/v1/{merchantId}/tokens API call, specifying additional properties:

Property	Data type	Required
paymentProductId	integer	yes
sepaDirectDebit	object	yes
customer	object	yes
billingAddress	object	yes
countryCode	string	yes
mandate	object	yes
bankAccountIban	object	yes
accountHolderName	string	yes
iban	string	yes
debtor	object	yes
surname	string	yes
isRecurring	boolean	no

POST TOKENS REQUEST (RECURRING)

{
  "paymentProductId": 770,
  "sepaDirectDebit": {
    "customer": {
      "billingAddress": {
        "countryCode": "NL"
      }
    },
    "mandate": {
      "bankAccountIban": {
        "accountHolderName": "Theo Mayer",
        "iban": "NL40ABNA5861098352"
      },
      "debtor": {
        "surname": "Mayer"
      },
      "isRecurring": true
    }
  }
}

Confirm recurring payment token

After creating a token, you need to confirm it using POST https://{domainname}/v1/{merchantId}/tokens/{tokenId}/approvesepadirectdebit API call.

Property	Data type	Required
mandateSignatureDate	string	no
mandateSignaturePlace	string	no
mandateSigned	boolean	no

APPROVE SEPA DD MANDATE REQUEST

{
    "mandateSignaturePlace": "Monument Valley",
    "mandateSignatureDate": "20200107",
    "mandateSigned": true
}

A successful response for this request will be an HTTP status of 204. If the token has already been validated, the response will look like this:

APPROVE SEPA DD MANDATE RESPONSE

{
    "errorId": "6617caba5da562890912d54db99fc09d",
    "errors": [
        {
            "code": "700647",
            "requestId": "463",
            "message": "MANDATE ALREADY SIGNED",
            "httpStatusCode": 400
        }
    ]
}

Submit recurring payment request

When submitting a payment request, you can omit some request details, such as the payment product ID.

recurringPaymentSequenceIndicator - this property is required for the recurring payment. It comes with one of three values:
- first = transaction is the first of a series of recurring transactions
- recurring = transaction is a subsequent in a series of recurring transactions
- last = transaction is the last one in a series of recurring transactions

Property	Data type	Required
order	object	yes
amountOfMoney	object	yes
currencyCode	string	yes
amount	integer	yes
customer	object	yes
billingAddress	string	yes
countryCode	string	yes
sepaDirectDebitPaymentMethodSpecificInput	object	yes
recurringPaymentSequenceIndicator	string	depends
isRecurring	boolean	yes
directDebitText	string	yes
paymentProductId	string	no
token	string	yes
tokenize	boolean	no
requiresApproval	boolean	no

POST PAYMENTS REQUEST

{
    "order": {
        "amountOfMoney": {
            "currencyCode": "EUR",
            "amount": 1000
        },
        "customer": {
            "billingAddress": {
                "countryCode": "NL"
            }
        }
    },
    "sepaDirectDebitPaymentMethodSpecificInput": {
        "directDebitText": "Trainmore B.V.",
        "isRecurring": true,
        "recurringPaymentSequenceIndicator": "first",
        "tokenize": true,
        "token": "df8e21c5-de6d-4df9-9c67-f9cccdb2c6ca",
        "requiresApproval": false
    }
}

POST PAYMENTS RESPONSE

{
    "creationOutput": {
        "additionalReference": "00000880051000013997",
        "externalReference": "000008800510000139970000100001"
    },
    "merchantAction": {
        "actionType": "SHOW_TRANSACTION_RESULTS",
        "showData": [
            {
                "key": "PAYMENTREFERENCE",
                "value": "0"
            },
            {
                "key": "ORDERID",
                "value": "1000013997"
            }
        ]
    },
    "payment": {
        "id": "000008800510000139970000100001",
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 1000,
                "currencyCode": "EUR"
            },
            "references": {
                "paymentReference": "0"
            },
            "paymentMethod": "directDebit",
            "sepaDirectDebitPaymentMethodSpecificOutput": {
                "paymentProductId": 770
            }
        },
        "status": "CAPTURE_REQUESTED",
        "statusOutput": {
            "isCancellable": true,
            "isRetriable": false,
            "statusCategory": "PENDING_CONNECT_OR_3RD_PARTY",
            "statusCode": 800,
            "statusCodeChangeDateTime": "20240429152330",
            "isAuthorized": false,
            "isRefundable": false
        }
    }
}

Approve payment

To approve/capture the payment, use POST https://{domainname}/v1/{merchantId}/payments/{paymentId}/approve API call.

Property	Data type	Required
token	string	no
dataCollect	string	no

APPROVE PAYMENT REQUEST

{
    "directDebitPaymentMethodSpecificInput" : {
        "token" : "df8e21c5-de6d-4df9-9c67-f9cccdb2c6ca",
        "dateCollect" : "20240508"
    },
    "order" : {
        "references" : {
            "merchantReference" : "Subscription01"
        }
    },
    "amount" : 1000
}

APPROVE PAYMENT RESPONSE

{
   "payment" : {
      "id" : "000008800510000139970000100001",
      "paymentOutput" : {
         "amountOfMoney" : {
            "amount" : 1000,
            "currencyCode" : "EUR"
         },
         "references" : {
            "paymentReference" : "0"
         },
         "paymentMethod" : "directDebit",
         "sepaDirectDebitPaymentMethodSpecificOutput" : {
            "paymentProductId" : 770
         }
      },
      "status" : "CAPTURE_REQUESTED",
      "statusOutput" : {
         "isCancellable" : true,
         "isRetriable" : false,
         "statusCategory" : "PENDING_CONNECT_OR_3RD_PARTY",
         "statusCode" : 800,
         "statusCodeChangeDateTime" : "20240508152943",
         "isAuthorized" : false,
         "isRefundable" : false
      }
   }
}

Refunds

To start a refund process, use the API call POST https://{domainname}/v1/{merchantId}/payments/{paymentId}/refund. This action is only possible if the payment status is PAID.

To refund the full order amount, send the request with an empty body
To do a partial refund, include the following properties in the request:

Property	Data type	Required
amountOfMoney	object	no
currencyCode	string	no
amount	integer	no

POST REFUND REQUEST

{
    "amountOfMoney": {
        "amount": 1000,
        "currencyCode": "EUR"
    }
}

Additionally, if you want to view the details of your refund, you can use the GET https://{domainname}/v1/{merchantId}/payments/{paymentId}/refunds API call.

Webhooks

To track transaction status updates, you can subscribe to the following webhooks notifications:

payment.created
payment.redirected
payment.pending_payment
payment.captured
payment.paid