Using a payment agreement

You can use our Payment Agreements API to set up recurring SEPA Direct Debit payments, giving you a unified view of all economically related transactions for a given consumer. As with one-time payments, you will need to collect the consumer's name, email, and IBAN details, obtain their approval for the direct debit mandate within your own checkout experience, and generate a mandate ID.

To create an SEPA Managed Mandate payment agreement, provide the following information when calling our payment agreements API

Create the payment agreement

To set up a recurring agreement, you'll need to provide at minimum the following data when calling our /v1/payment-agreements API:

Data Field	Required	Description
paymentMethod	M	SEPA_DIRECT_DEBIT
consumer.name	M	Full name of the consumer.
consumer.country	M	The country where the consumer is shopping.
instrument: BANK_ACCOUNT details.iban	M	The IBAN of the consumer's bank account.
instrument: BANK_ACCOUNT details.debitMandateId	M	The mandate ID you have generated in your system to identify the SEPA mandate.

You can also include the initialPaymentCharge object in this agreement creation call to immediately initiate the first payment without making a separate call. If you include this object, you'll need to specify the exact amount.value and amount.currency of the first payment.

If you don't include an initialPaymentCharge during agreement creation, you'll need to make a separate API call to /v1/payment-agreements/{agreement\_id}/payment-charges to create the first charge.

Request

POST /v1/payment-agreements

{
  "paymentMethod": "SEPA_DIRECT_DEBIT",
  "consumer": {
    "name": "John Smith",
    "country": "FR"
  },
  "instrument": {
    "type": "BANK_ACCOUNT",
    "details": {
      "iban": "FR1420041010050500013M02606",
      "debitMandateId": "YOURDIRECTDEBITMANDATEID12123"
    }
  }
}

{
  "paymentMethod": "SEPA_DIRECT_DEBIT",
  "consumer": {
    "name": "Connor Sumer",
    "country": "NL"
  },
  "instrument": {
    "type": "BANK_ACCOUNT",
    "details": {
      "iban": "FR1420041010050500013M02606",
      "debitMandateId": "YOURDIRECTDEBITMANDATEID12123"
    }
  },
  "initialPaymentCharge": {
    "amount": {
      "value": 1000,
      "currency": "EUR"
    }
  }
}

Response

{
  "id": "agr_v2tXTPKpmslWIJjUOIUtm",
  "status": "ACTIVE",
  "paymentMethod": "SEPA_DIRECT_DEBIT",
  "startDate": "2025-04-15T16:10:26.270Z",
  "instrumentId": "instr_ocU6uxar4Fo4zr50tMd9T",
  "consumer": {
    "name": "John Smith",
    "country": "FR"
  },
  "history": [
    {
      "id": "ahist_q08s0A5sQMUN32TFVdVq9",
      "status": "ACTIVE",
      "createdAt": "2025-04-15T16:10:26.439Z"
    }
  ],
  "createdAt": "2025-04-15T16:10:26.439Z",
  "updatedAt": "2025-04-15T16:10:26.439Z"
}

{
  "id": "agr_1vP51hJpDCzbZGu6Ch4Ah",
  "status": "ACTIVE",
  "paymentMethod": "SEPA_DIRECT_DEBIT",
  "startDate": "2025-04-15T16:15:18.892Z",
  "instrumentId": "instr_7Km0BopbXA0Pd0PtHwPDU",
  "consumer": {
    "name": "John Smith",
    "country": "FR"
  },
  "history": [
    {
      "id": "ahist_zqCTA06XqK9EsoBlUM9Tb",
      "status": "ACTIVE",
      "createdAt": "2025-04-15T16:15:20.026Z"
    }
  ],
  "initialPaymentChargeId": "charge_b5Lv9OQMrQWu1dAEgRe5f",
  "createdAt": "2025-04-15T16:15:20.026Z",
  "updatedAt": "2025-04-15T16:15:20.026Z"
}

Handling the result

As SEPA Direct Debit does not require a dedicated consumer authentication step, the agreement details will be returned directly in the response with the agreement status set to ACTIVE.

The same processing and status transition behavior applies to subsequent recurring charges.

Create a recurring payments

To initiate a subsequent recurring payment, send a request against an active agreement /v1/payment-agreements/{agreement-id}/payment-charges

Request

POST /v1/payment-agreements/{agreement-id}/payment-charges

{
  "amount": {
    "value": 1000,
    "currency": "EUR"
  }
}

Response

{
  "id": "charge_VVJbYlQuMKyWKMIT9lnR3",
  "paymentMethod": "SEPA_DIRECT_DEBIT",
  "currency": "EUR",
  "country": "FR",
  "instrumentId": "instr_ocU6uxar4Fo4zr50tMd9T",
  "status": "AUTHORIZATION_ASYNC",
  "consumer": {
    "name": "John Smith",
    "country": "FR"
  },
  "authorizations": [
    {
      "id": "authz_IGDaGFCRrfAwVdExlRoKo",
      "amount": 1000,
      "status": "PROVIDER_CONFIRMATION_PENDING",
      "createdAt": "2025-04-15T16:32:26.825Z",
      "updatedAt": "2025-04-15T16:32:26.825Z"
    }
  ],
  "captures": [],
  "refunds": [],
  "voids": [],
  "createdAt": "2025-04-15T16:32:26.646Z",
  "updatedAt": "2025-04-15T16:32:26.825Z"
}