SEPA Direct Debit

You can accept SEPA Direct Debit payments from customers in countries within the Single Euro Payments Area.

The SEPA initiative aims to facilitate seamless, quick, and cost-effective direct debits across 36 (as of March 2019) European countries. Banks participating in SEPA are not permitted to charge higher fees for cross-border SEPA Direct Debits than they would for direct debits within their home country.

To accept payments by SEPA Direct Debit, please contact your customer success manager.

Process a SEPA payment

First, you need to collect your customers' euro-denominated bank account details, including their IBAN. The bank account holder is then required to accept a mandate to authorize you to debit their account. Once the mandate is approved, submit the mandate details to Checkout.com and we'll provide you with a source object with which you can complete the payment.

The mandate

Before any payment can occur, your customer must authorize the payment by accepting the terms of the mandate. By accepting, they are authorizing you to collect the specified amount from their bank account using SEPA Direct Debit.

There are two types of mandates:

  • One-off: allows a single payment to be made against the mandate. It can only be used once.
  • Recurring: allows multiple payments to be made against the mandate. It can be reused.

The mandate is accepted using ‘click’ acceptance. This method requires that the mandate’s terms are set out on the same page as where the customer enters their bank account details. The mandate should make it clear that if the customer submits their bank account details to the merchant, they are implicitly agreeing to the mandate.

Once the mandate is approved, you can submit the customer’s information to us, and we'll return the mandate reference to you. You should then present the mandate reference to your customer as confirmation that the mandate has been created.

For details about the mandate and more, please read the SEPA Direct Debit core rulebook.

Pre-notify the customer

Before debiting a customer's account with SEPA Direct Debits, it is mandatory that the customer is informed of the debit by the merchant in an agreed timeframe before the payment. We recommend you include details of this timeframe in your terms and conditions.

Notifications are sent to enable the customer to make sure they have the necessary funds available in their bank account and also to make them aware of the payment so they recognize it in their statement.

Funds will be removed from the customer’s account one or two days after the transaction is submitted. It is a SEPA requirement that you make sure your customers are aware of this.

For additional information about pre-notifications, please read the SEPA Direct Debit core rulebook.

Request a SEPA Direct Debit payment

SEPA is supported through direct integration with our API. When a payment is initially processed, the status of the SEPA charge will be pending. After the payment is settled, the status updates to captured and we will notify you with payment_captured webhook.

You can process a SEPA payment in two steps:

  1. Create a new SEPA payment source
  2. Request a SEPA payment

Step 1: Create a new SEPA payment source

Create a new SEPA payment source that can be used to make one or more payments. Creating a source will automatically create a new mandate as well. You'll receive the mandate reference in the response, and you can use this if you ever need to cancel a mandate.

Payment sources are linked to a specific customer and cannot be shared between customers.

The request

SEPA Direct Debit payments are requested using a POST API request. Use the URLs below to run the request in either your live or sandbox environment.

Endpoint live

https://api.checkout.com/sources

Endpoint sandbox

https://api.sandbox.checkout.com/sources

Header and required parameters

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Body parameters

Field name
Description

type
String
Required

The type of payment. Set this to sepa.

reference
String
Optional

A reference that you can later use to identify the source.

source_data
Object
Required

Additional data required to create SEPA payment sources.

source_data.first_name
String
Required

The bank account holder's first name.

source_data.last_name
String
Required

The bank account holder's last name.

source_data.account_iban
String
Required

The bank account's IBAN.

source_data.bic
String
Optional

The bank account's BIC.

In sandbox, this must be set to PBNKDEFFXXX.

source_data.billing_descriptor
String
Required

The billing descriptor.

source_data.mandate_type
String
Required

The type of mandate. Set to single for one-off payments or recurring for recurring payments.

billing_address
Object
Required

The bank account owner's billing address.

billing_address.address_line1
String
Required

Line 1 of the billing address.

billing_address.address_line2
String
Optional

Line 2 of the billing address.

billing_address.city
String
Required

The city.

billing_address.state
String
Optional

The state.

billing_address.zip
String
Required

The zip code.

billing_address.country
String
Required

The country — must be represented by an ISO2 country code (e.g. US).

phone
Object
Optional

The account holder's phone number.

phone.country_code
String
Optional

The valid country code for the phone number (e.g. 44 for the United Kingdom).

phone.number
String
Optional

The phone number itself.

customer
String
Optional

Details of the customer to associate with the source.

customer.id
String
Optional

The identifier of an existing customer. If neither customer id nor email is provided, we will automatically create a new customer profile and return the customer id in the response.

customer.email
String
Optional

The customer's email address.

customer.name
String
Optional

The customer's name. This will only set the name for new customers.

Request examples

Below is an example of the body of a SEPA source request.

SEPA only supports a pre-defined list of IBANs for testing purposes. The example below shows a successful request. Click here for a list of IBANs you can use in your sandbox environment.

{
  "type": "sepa",
  "reference": "X-080957-N34",
  "source_data": {
    "first_name": "Sophie",
    "last_name": "Bonneville",
    "account_iban": "DE25100100101234567893",
    "bic":"PBNKDEFFXXX",
    "billing_descriptor": "Thanks for shopping",
    "mandate_type": "recurring"
  },
  "billing_address": {
    "address_line1": "101 Avenue de Gaulle",
    "city": "Paris",
    "zip": "75013",
    "country": "FR"
  },
  "phone": {
    "country_code": "+33",
    "number": "6 78 91 01 11"
  },
  "customer": {
    "email": "sophie.bonneville@ckomail.com"
  }
}
{
  "type": "sepa",
  "reference": "X-080957-N34",
  "source_data": {
    "first_name": "Sophie",
    "last_name": "Bonneville",
    "account_iban": "DE25100100101234567893",
    "bic":"PBNKDEFFXXX",
    "billing_descriptor": "Thanks for shopping!",
    "mandate_type": "single"
  },
  "billing_address": {
    "address_line1": "101 Avenue de Gaulle",
    "city": "Paris",
    "zip": "75013",
    "country": "FR"
  },
  "phone": {
    "country_code": "+33",
    "number": "6 78 91 01 11"
  },
  "customer": {
    "email": "sophie.bonneville@ckomail.com"
	}
}

Please note:
The soft descriptor value will be prepended to the mandate reference when it appears on a customer's bank statement. For example, Thanks for shopping - Mandate: 1017424.

The response

{
  "id": "src_a3wfgafsyedefaobbqadqw34vy",
  "type": "Sepa",
  "response_code": "10000",
  "response_data": {
    "mandate_reference": "2476225"
  },
  "customer": {
    "id": "cus_uhpsey6culvuln3zfzfme7w5ea"
  },
  "_links": {
    "self": {
      "href": "https://api.checkout.com/sources/src_a3wfgafsyedefaobbqadqw34vy"
    },
    "sepa:mandate-cancel": {
      "href": "https://api.checkout.com/sepa-external/mandates/src_a3wfgafsyedefaobbqadqw34vy/cancel"
    },
    "sepa:mandate-get": {
      "href": "https://api.checkout.com/sepa-external/mandates/src_a3wfgafsyedefaobbqadqw34vy"
    }
  }
}

Step 2: Request a SEPA payment

The request

Endpoint live

https://api.checkout.com/payments

Endpoint sandbox

https://api.sandbox.checkout.com/payments

Header and required parameters

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Request example

{
  "source": {
    "type": "id",
    "id": "src_a3wfgafsyedefaobbqadqw34vy"
  },
  "amount": 5600,
  "currency": "EUR",
  "reference": "X-080957-N34"
}

Use the provided source ID in the payments endpoint to create a payment for a particular customer. For recurring payments, the source ID can be used multiple times.

The response

{
  "id": "pay_6thh5vhggyjudgzfznx2fkuede",
  "status": "Pending",
  "reference": "X-080957-N34",
  "customer": {
    "id": "cus_uhpsey6culvuln3zfzfme7w5ea",
    "email": "sophie.bonneville@ckomail.com"
  },
  "_links": {
    "self": {
      "href": "https://api.checkout.com/payments/pay_6thh5vhggyjudgzfznx2fkuede"
    }
  }
}

Cancel a SEPA mandate

If your customer requests to cancel a SEPA mandate, you can do so by using our cancel mandate endpoint. Once canceled, you will no longer be able to create payments using the mandate or its source object.

The request

Endpoint live

https://api.checkout.com/sepa/mandates/{source_id}/cancel

Endpoint sandbox

https://api.sandbox.checkout.com/sepa/mandates/{source_id}/cancel

Header and path parameters

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Path
Value

source_id
Required

The source ID, find this in the response of the source creation.

Mandates automatically expire after 36 months of inactivity.

Refund a SEPA payment

A captured SEPA charge can be refunded using our refund endpoint and the original payment ID (of the SEPA payment). Refunds must be claimed within eight weeks starting from the date on which the account was debited. Once the charge is refunded, its payment status updates to refunded, and we will notify you with a payment_refunded webhook.

The request

Endpoint live

https://api.checkout.com/payments/{payment_id}/refunds

Endpoint sandbox

https://api.sandbox.checkout.com/payments/{payment_id}/refunds

Header and path parameters

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Path
Value

payment_id
Required

The payment ID found in the response of the initial payment.

Request example

An example body of the refund API request. Make sure you edit the fields to represent your required needs.

{
  "amount": 6540,
  "reference": "ORD-5023-4E89",
}

The response

Response example

If you receive a success response, your refund was processed correctly.

{
  "action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
  "reference": "ORD-5023-4E89",
  "_links": {
    "payment": {
      "href": "https://api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
    }
  }
}

Refunds can take up to four days to be processed.

Retrieve a SEPA payment source

Use this request to get more information on a SEPA payment source, based on its id.

The request

Replace {id} with the source id. It is prefixed by src.

Endpoint live

GEThttps://api.checkout.com/sources/{id}

Endpoint sandbox

GEThttps://api.sandbox.checkout.com/sources/{id}

The response

If a source response object returns, your request was successful.

Response example

Take a look at the example response below.

{
  "id": "src_y3oqhf46pyzuxjbcn2giaqnb44",
  "type": "sepa",
  "_links": {
    "self": {
      "href": "https://api.checkout.com/sources/src_y3oqhf46pyzuxjbcn2giaqnb44"
    },
    "sepa:mandate": {
      "href": "https://api.checkout.com/sepa/mandates/src_y3oqhf46pyzuxjbcn2giaqnb44"
    }
  }
}

Additional error responses:

  • 404 - Payment source not found

SEPA chargebacks

Due to the asynchronous nature of SEPA Direct Debits, the reasons for a SEPA chargeback go beyond the traditional customer-initiated chargebacks, such as whether or not a customer has insufficient funds available. If a chargeback occurs, we will let you know through a payment_chargeback webhook notification.

Chargebacks can be initiated up to 13 months after a payment was first processed. A customer can dispute a payment with their bank when they believe that they did not authorize the payment.

If you and your customer did not agree upon the mandate, then the SEPA chargeback cannot be represented. You must handle representing a SEPA chargeback directly with the customer.

Testing SEPA

If you want to test the different use cases for SEPA payment results, please use the following test IBANs. These IBANs have a valid checksum and should be supplied when creating a new mandate.

IBAN
Description

DE09100100101234567890

The customer's mandate and payment can't be set up because their bank details are invalid. Payment not accepted.

DE79100100101234567891

The customer's payment is accepted, but not collected yet. The mandate is marked as activated. The payment will remain on Status 1 (accepted).

DE52100100101234567892

The customer's payment is accepted, but then cancelled before collection. The mandate is marked as activated. The payment is marked as Status 1 (accepted), then Status 2 (canceled)

DE25100100101234567893

The customer's payment is collected successfully and paid out to you. The mandate is marked as activated. The payment is marked as Status 1 (accepted), then Status 3 (paid).

DE95100100101234567894

The customer’s payment is provided to the bank successfully, but is then charged back due to a request by a merchant. The mandate is marked as activated. The payment is marked as Status 1 (accepted), then Status 3 (paid). Finally, the payment is marked as Status 4 (charge-back) with Token (RFND).

DE68100100101234567895

The customer's payment is collected successfully, but is then charged back by the customer disputing it with their bank (actively initiated by the customer). The mandate is marked as activated. The payment is marked as status 1 (accepted), then status 3 (paid). Finally, the payment is marked as status 4 (chargeback) with token (ACT).

DE41100100101234567896

The customer's payment is provided to the bank successfully, but is then charged back by their bank due to no sufficient funds. The mandate is marked as activated. The payment is marked as Status 1 (accepted), then Status 3 (paid). Finally, the payment is marked as Status 4 (chargeback) with Token (NSF).

DE14100100101234567897

The customer's payment is provided to the bank successfully, but is then charged back by the bank due to other reasons (no bank account, saving account). The mandate is marked as activated. The payment is marked as Status 1 (accepted), then Status 3 (paid). Finally, the payment is marked as Status 4 (chargeback) with Token (OTHR).

DE84100100101234567898

The customer's payment is provided to the bank successfully, but is then charged back by the bank due to format errors. The mandate is marked as activated. The payment is marked as Status 1 (accepted), then Status 3 (paid). Finally, the payment is marked as Status 4 (chargeback) with Token (FRM).

BIC in sandbox:
If you've chosen to use the optional bic field, you must set this to PBNKDEFFXXX. This is the only accepted value.

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at support@checkout.com.

SEPA Direct Debit


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.