girocard and Direct Debit

📘

Your account must be enabled for these features.

🚧

girocard and terminal-based ELV are limited to Germany. IBAN-based SEPA transactions are limited to supported SEPA countries and acquiring routes.

Use this guide to accept girocard and SEPA Direct Debit (SDD), also known in Germany as electronic direct debit or ELV, and to return funds through an enabled SEPA credit flow using the Fiserv Payments REST API.

Availability depends on your merchant agreement, store and terminal configuration, terminal certification, and the services enabled by Fiserv. Contact your Fiserv representative before enabling a new transaction path.

Choose the correct request type

The REST API supports two different ways of supplying German direct-debit account information. Do not mix their request structures.

SepaCreditTransaction and PaymentTerminalCreditTransaction create a new credit. They do not cancel or change the status of the original girocard or ELV purchase.

Before you begin

Confirm that:

• your Fiserv merchant account and store are enabled for the required girocard, ELV and/or SEPA credit services;
• each terminal is registered, attested and enabled for the intended transaction paths;
• the terminal model and software are certified for the card-reading, encryption, PIN and signature flows you use;
• you have the assigned Store ID, Merchant ID and Terminal ID;
• production Terminal IDs for Germany have been assigned through the applicable German business process;
• the terminal can display host-provided messages and print the required receipt data;
• the transaction currency and refund limits are supported by your merchant agreement; and
• referenced and/or unreferenced credits are enabled if required by your business process.

Protect PAN, track, PIN, EMV and IBAN data according to the applicable security requirements. Never place live account data, cryptographic keys or unmasked customer information in source control, application logs or support tickets.

Endpoint and authentication

Submit primary transactions to:

POST {baseUrl}/payments

Use the API credentials, mutual TLS configuration and message-signature procedure assigned to your application. Each request should use a unique Client-Request-Id and merchant transaction reference.

girocard purchases

Use PaymentTerminalSaleTransaction. Because most cards issued in Germany include girocard, send DEBITDE_GIRO as the selected brand when the terminal application selects the girocard route.

The brand belongs to the protected payment-card data. Do not select girocard merely because the physical card is co-branded; send the route selected by the certified terminal application.

Supported transaction types

girocard supports purchases and cancellation of eligible transactions. The girocard scheme does not provide a native card refund. Return funds through the SEPA credit flow agreed with Fiserv.

Online and offline processing

Whether a girocard transaction is processed online or offline depends on the card, terminal decision and applicable terminal limits.

A contactless girocard transaction can be processed online with:

• no cardholder verification, when permitted; or
• online PIN.

Populate terminalRequestData with the actual card-entry mode, verification result, online/offline decision and EMV data produced by the terminal. Do not manufacture terminal or EMV values.

Terminal transaction counter

Send the terminal transaction counter in terminalRequestData.traceNumber.

For transactions routed to the German authorization platform:

• use a numeric value from 0 through 999999;
• use a new value for every new transaction;
• increase the counter by 10 so the Gateway can use intermediate values during automatic cutover or routing;
• after values above 900000, the counter may restart below 100000; and
• retain the original counter and transaction identifiers for cancellation and investigation.

If the response contains processor.correctedTraceNumber, update the terminal counter as instructed. The response can additionally indicate UpdateTraceNumber in processor.requiredActionOnTerminal.

German KSN format

Use the German KSN format for applicable DUKPT-protected terminal data. Follow the encryption, key-derivation and MAC profile supplied during terminal onboarding and certification.

Terminal ELV / SEPA Direct Debit

Terminal ELV is a card-present flow. The terminal reads a girocard using the contact interface and sends protected PAN, track and EMV data. The PAN is not an IBAN.

Use:

• requestType: PaymentTerminalSaleTransaction;
• transactionOrigin: RETAIL;
• protected card brand DEBITDE_ELV;
• terminalRequestData.posEntryMode: CONTACT_EMV;
• terminalRequestData.offlineVerificationMethod: PAPER_SIGNATURE or DIGITAL_SIGNATURE, matching the method actually performed; and
• cardPresentIndicator and cardholderPresentIndicator set according to the physical transaction.

ELV is supported through the certified contact-chip flow. A girocard read through the contactless interface is processed as girocard rather than ELV.

Protected card data

Production terminal requests must use paymentMethod.paymentCardProtected. The decrypted card-data object contains the PAN, expiry information, track data and selected brand, for example:

{
  "number": "<girocard-pan>",
  "expiryDate": {
    "month": "12",
    "year": "28"
  },
  "track2": "<track-2-data>",
  "brand": "DEBITDE_ELV"
}

This example shows the logical data before encryption. Do not transmit this plaintext object in production. Encrypt it using the terminal encryption profile and keys agreed with Fiserv.

Online ELV request

The following example shows the surrounding REST structure. Replace every placeholder with certified terminal output and your assigned values.

{
  "requestType": "PaymentTerminalSaleTransaction",
  "transactionAmount": {
    "total": 49.90,
    "currency": "EUR"
  },
  "transactionOrigin": "RETAIL",
  "merchantTransactionId": "ELV-20260901-0001",
  "order": {
    "orderId": "ORDER-20260901-0001",
    "clientLocale": {
      "language": "de"
    }
  },
  "terminalId": "<terminal-id>",
  "merchantId": "<merchant-id>",
  "paymentMethod": {
    "paymentCardProtected": {
      "encryptedData": "<base64-encrypted-card-data>",
      "key": {
        "index": "<key-serial-number>",
        "name": "<key-name>",
        "version": "<key-version>",
        "derivationAlgo": "DUKPT2009",
        "encryptionAlgo": "DES112CBC"
      }
    }
  },
  "terminalRequestData": {
    "posEntryMode": "CONTACT_EMV",
    "offlineVerificationMethod": "PAPER_SIGNATURE",
    "cardholderPresentIndicator": true,
    "cardPresentIndicator": true,
    "offlineIndicator": false,
    "onlineReason": "ICC_FORCED",
    "attendanceContext": "ATTENDED",
    "emvData": "<base64-emv-data>",
    "traceNumber": 120010
  },
  "pointOfSaleDevice": {
    "terminalProvider": "<terminal-provider>",
    "model": "<terminal-model>",
    "serialNumber": "<terminal-serial-number>",
    "softwareProvider": "<software-provider>",
    "softwareVersion": "<software-version>",
    "capabilities": {
      "cardholderVerificationCapabilities": [
        "PAPER_SIGNATURE"
      ],
      "cardReadingCapabilities": [
        "CONTACT_EMV"
      ],
      "terminalType": "POS",
      "pinCapability": "NONE"
    }
  }
}

For an online transaction, onlineReason is required. The terminal must send the actual reason determined by its payment application.

For an offline-approved transaction, set offlineIndicator to true and provide the applicable terminal approval data. Use offline processing only when enabled and certified.

ELV receipt and returned IBAN

The German authorization platform can derive the IBAN from the terminal-supplied card data and return it in the authorization response. Use only the response field intended for receipt generation, and print or display the account information according to the certified receipt format.

The returned IBAN does not change the request model: the terminal request still carries PAN/track data, not an IBAN in the PAN field.

The merchant normally carries the risk of an unpaid or returned ELV debit unless an agreed protection service applies. Optional TSD, TSD+ and GLV services are enabled by Fiserv configuration; they are not selected through a different REST request type.

IBAN-based SEPA Direct Debit

When the merchant already holds the payer's IBAN and mandate, use SepaSaleTransaction instead of PaymentTerminalSaleTransaction.

{
  "requestType": "SepaSaleTransaction",
  "transactionAmount": {
    "total": 49.90,
    "currency": "EUR"
  },
  "transactionOrigin": "ECOM",
  "merchantTransactionId": "SDD-20260901-0001",
  "order": {
    "orderId": "ORDER-20260901-0002"
  },
  "paymentMethod": {
    "sepa": {
      "iban": "<payer-iban>",
      "name": "Max Mustermann",
      "email": "[email protected]",
      "mandate": {
        "reference": "MANDATE-2026-0001",
        "signatureDate": "2026-08-20",
        "type": "SINGLE"
      }
    }
  }
}

The mandate type is one of SINGLE, FIRST_COLLECTION, RECURRING_COLLECTION or FINAL_COLLECTION. Retain the original mandate reference and signature date throughout a recurring series.

This is an IBAN-and-mandate flow. Do not place an IBAN in paymentMethod.paymentCard.number when using a terminal transaction request.

SEPA credit after a girocard or ELV purchase

A SEPA credit is a new transaction that sends money to the customer's bank account. It does not reverse the original authorization or change the original purchase status.

Before sending credits, confirm that:

• SEPA credits are enabled for the merchant, store and terminal;
• the beneficiary account is obtained through the certified terminal or IBAN-entry flow;
• full, partial, referenced and unreferenced credits are enabled as required;
• the cumulative credited amount is controlled by your application; and
• your process prevents duplicates after timeouts or uncertain responses.

Never construct a credit from a masked IBAN printed on a receipt. A masked value is not a valid payment instruction.

Terminal-initiated credit using card data

Use PaymentTerminalCreditTransaction when the certified terminal obtains the beneficiary through the card/PAN flow:

{
  "requestType": "PaymentTerminalCreditTransaction",
  "transactionAmount": {
    "total": 10.00,
    "currency": "EUR"
  },
  "transactionOrigin": "RETAIL",
  "merchantTransactionId": "SEPA-CREDIT-20260901-0001",
  "order": {
    "orderId": "REFUND-20260901-0001"
  },
  "terminalId": "<terminal-id>",
  "merchantId": "<merchant-id>",
  "paymentMethod": {
    "paymentCardProtected": {
      "encryptedData": "<base64-encrypted-card-data>",
      "key": {
        "index": "<key-serial-number>",
        "name": "<key-name>",
        "version": "<key-version>",
        "derivationAlgo": "DUKPT2009",
        "encryptionAlgo": "DES112CBC"
      }
    }
  },
  "terminalRequestData": {
    "posEntryMode": "CONTACT_EMV",
    "offlineVerificationMethod": "PAPER_SIGNATURE",
    "cardholderPresentIndicator": true,
    "cardPresentIndicator": true,
    "offlineIndicator": false,
    "onlineReason": "MERCHANT_FORCED",
    "attendanceContext": "ATTENDED",
    "emvData": "<base64-emv-data>",
    "traceNumber": 120020
  },
  "pointOfSaleDevice": {
    "terminalProvider": "<terminal-provider>",
    "model": "<terminal-model>",
    "serialNumber": "<terminal-serial-number>",
    "capabilities": {
      "cardholderVerificationCapabilities": [
        "PAPER_SIGNATURE"
      ],
      "cardReadingCapabilities": [
        "CONTACT_EMV"
      ],
      "terminalType": "POS",
      "pinCapability": "NONE"
    }
  }
}

The protected card-data object must contain brand: DEBITDE_ELV and the PAN/track information produced by the certified terminal. Send the credit amount as a positive amount; the request type determines the credit direction.

Credit using a known IBAN

Use SepaCreditTransaction when your approved business process already holds the beneficiary's full IBAN and account-holder name:

{
  "requestType": "SepaCreditTransaction",
  "transactionAmount": {
    "total": 10.00,
    "currency": "EUR"
  },
  "transactionOrigin": "ECOM",
  "merchantTransactionId": "SEPA-CREDIT-20260901-0002",
  "order": {
    "orderId": "REFUND-20260901-0002"
  },
  "paymentMethod": {
    "sepa": {
      "iban": "<beneficiary-iban>",
      "name": "Max Mustermann"
    }
  }
}

No direct-debit mandate is required for a credit. Do not use an unlinked SEPA credit as a substitute for a linked return unless this has been agreed during onboarding.

Displaying and printing response text

The German authorization platform can return text that must be displayed on the terminal or printed on the receipt. The relevant fields are under processor.terminalPrintAndDisplayData:

Use order.clientLocale.language to request the applicable language. If no language is supplied, the response text is normally returned in German. Display and print the host-provided text without replacing it with a generic message.

Emergency processing

If the terminal performed an approved emergency process, send:

{
  "terminalRequestData": {
    "emergencyProcessing": true
  }
}

Use emergency processing only when permitted by the card, terminal certification, scheme rules and your Fiserv configuration.

Approval number

Send the approval number (provided by the German Banking Industry Committee (GBIC)) in terminalRequestData.approvalCode.

Response handling

An HTTP 200 response alone does not mean that the transaction was approved. Evaluate transactionResult and retain the gateway and merchant identifiers from the response.

For SEPA Direct Debit, approval means that the collection instruction was accepted for processing. It does not guarantee settlement and does not remove applicable return or refund rights.

For a SEPA credit, approval means that the credit was accepted for processing. It does not guarantee that the beneficiary bank has already posted the funds.

After a timeout or communication failure, retrieve the transaction state before sending another debit or credit:

GET {baseUrl}/payments/{ipgTransactionId}

Cancellation, return and credit rules

• Cancel an eligible transaction through the documented void operation while cancellation is still permitted.
• Use a linked return when the original transaction and configured route support it.
• Use PaymentTerminalCreditTransaction or SepaCreditTransaction only for an enabled SEPA credit flow.
• A credit is a separate transaction and requires its own unique client and merchant references.
• Never send a negative purchase amount to represent a refund.
• Prevent the total credited amount from exceeding the refundable amount under your merchant policy.
• After an uncertain result, inquire and reconcile before resubmitting.

Security

• In production, send terminal card data only through paymentCardProtected using the certified encryption profile.
• Protect PIN data with the agreed key-management and PIN-block process.
• Treat IBANs, account-holder names, mandate information and transaction references as sensitive banking and personal data.
• Mask PANs and IBANs in logs, receipts and support material according to the applicable rules.
• Never log API secrets, message signatures, full track data, PIN blocks, reusable tokens or decrypted payment-card objects.