Skip to main content

​
Overview

The PAIN_VERSIONS type defines the supported ISO 20022 payment initiation message formats. These versions determine the XML schema structure for either Credit Transfers (pain.001) or Direct Debits (pain.008).

​
Type Definition

type PAIN_VERSIONS =
  | "pain.001.001.02"
  | "pain.001.003.02"
  | "pain.001.001.03"
  | "pain.001.003.03"
  | "pain.008.001.01"
  | "pain.008.003.01"
  | "pain.008.001.02"
  | "pain.008.003.02";

​
Version Types

​
Credit Transfer (pain.001)

Used for SEPA Credit Transfers - sending money from debtor to creditor.
  • Legacy version 2 format
  • Uses pain.001.001.02 as the root element name
  • Includes batch booking at group header level
  • Uses “MIXD” grouping indicator
  • Version 2 format for Swiss implementations
  • Uses pain.001.003.02 as the root element name
  • Similar structure to pain.001.001.02
  • Current standard (default in library)
  • Uses CstmrCdtTrfInitn as the root element name
  • Version 3 format with enhanced transaction details
  • Requires end2endReference for each payment
  • BIC is optional for creditor in SEPA zone
  • Version 3 format for Swiss implementations
  • Uses CstmrCdtTrfInitn as the root element name
  • Enhanced features similar to pain.001.001.03

​
Direct Debit (pain.008)

Used for SEPA Direct Debits - collecting money from debtor accounts.
  • Legacy version 1 format
  • Uses pain.008.001.01 as the root element name
  • Requires mandate information for each transaction
  • Version 1 format for Swiss implementations
  • Uses pain.008.003.01 as the root element name
  • Version 2 format
  • Uses CstmrDrctDbtInitn as the root element name
  • Requires localInstrumentation and sequenceType
  • BIC is optional for debtor in SEPA zone
  • Version 2 format for Swiss implementations
  • Uses CstmrDrctDbtInitn as the root element name

​
Usage

Specify the PAIN version in the SepaData object when calling createSepaXML(): 
import { createSepaXML } from "sepa-js-xml";

// Credit Transfer with version 3 (default)
const creditTransferXML = createSepaXML({
  painVersion: "pain.001.001.03",
  id: "MSG-001",
  creationDate: new Date(),
  initiatorName: "My Company",
  positions: [
    {
      id: "BATCH-001",
      name: "My Company",
      iban: "DE89370400440532013000",
      bic: "COBADEFFXXX",
      requestedExecutionDate: new Date(),
      payments: [
        {
          id: "PMT-001",
          name: "Supplier Ltd",
          iban: "GB29NWBK60161331926819",
          amount: 1000.00,
          remittanceInformation: "Invoice #12345",
          end2endReference: "INV12345",
        },
      ],
    },
  ],
});

// Direct Debit with version 2
const directDebitXML = createSepaXML({
  painVersion: "pain.008.001.02",
  localInstrumentation: "CORE",
  sequenceType: "RCUR",
  id: "MSG-002",
  creationDate: new Date(),
  initiatorName: "My Company",
  positions: [
    {
      id: "BATCH-002",
      name: "My Company",
      iban: "DE89370400440532013000",
      bic: "COBADEFFXXX",
      collectionDate: new Date(),
      requestedExecutionDate: new Date(),
      payments: [
        {
          id: "PMT-002",
          name: "Customer Name",
          iban: "GB29NWBK60161331926819",
          bic: "NWBKGB2L",
          amount: 50.00,
          mandateId: "MANDATE-123",
          mandateSignatureDate: new Date("2023-01-15"),
          remittanceInformation: "Monthly subscription",
        },
      ],
    },
  ],
});

​
Version Detection

The library automatically determines the payment method based on the version:
  • pain.001.x.x → Credit Transfer (TRF)
  • pain.008.x.x → Direct Debit (DD)

​
Default Version

If no painVersion is specified, the library defaults to pain.001.001.03. 
// Uses pain.001.001.03 by default
const xml = createSepaXML({
  id: "MSG-001",
  creationDate: new Date(),
  initiatorName: "My Company",
  positions: [/* ... */],
});

​
Key Differences

​
Version 2 vs Version 3

FeatureVersion 2 (.02)Version 3 (.03)
Root elementpain.00x.00x.0xCstmrCdtTrfInitn / CstmrDrctDbtInitn
Batch bookingGroup header levelPayment info level
Transaction countsGroup header onlyBoth group header and payment info
End-to-end referenceOptionalRequired for pain.001.001.03
Grouping indicator”MIXD” requiredNot used

​
Credit Transfer vs Direct Debit

FeatureCredit Transfer (pain.001)Direct Debit (pain.008)
DirectionPush paymentPull payment
Local instrumentationNot usedRequired (CORE/COR1/B2B)
Sequence typeNot usedRequired (FRST/RCUR/OOFF/FNAL)
Mandate infoNot requiredRequired
Collection dateNot usedRequired

Build docs developers (and LLMs) love

Get started for freeTalk to us