This tutorial describes how to initiate SEPA Direct Debit (SDD) collections with the PagoNxt Payments Hub API and accompanies the information Perform a Direct Debit Payment message tutorial
For this tutorial, consider a scenario where a business in Madrid (creditor) needs to collect a subscription from a customer (debtor) in Barcelona. To do so, the creditor initiates an SDD collection, which instructs funds in EUR to be pulled from the debtor’s account and credited to the creditor’s account on the requested collection date. The Payments Hub API is used to send the instruction between PSPs.
Request body
The request must include a JSON payload object in the request body. The JSON payload is a pacs.003 ISO message with the fitoFICstmrDrctDbt root element, and it contains the request details for submitting a payment.
Table: Submit the direct debit- Relevant request body elements.
Message field | Description |
|---|---|
grpHdr.msgId | Message ID, which must uniquely identify each request you send. The instructing party must make sure that the Message Identification is unique as this reference is used internally for the idempotency of the API. |
grpHdr.creDtTm | Date and time of the direct debit request |
grpHdr.nbOfTxs | Number of transactions within the message Value: 1 |
grpHdr.sttlmInf.sttlmMtd | Settlement method. Value: CLRG |
drctDbtTxInf[].pmtId.endToEndId | End‑to‑end ID Mirrors creditor’s reference. |
drctDbtTxInf[].pmtId.txId | Interbank transaction ID Unique per transaction. |
drctDbtTxInf[].pmtTpInf.svcLvl[0].cd | Payment scheme type. Value: SEPA |
drctDbtTxInf[].pmtTpInf.lclInstrm.cd | Local instrument CORE or B2B. |
drctDbtTxInf[].pmtTpInf.seqTp | Sequence type FRST / RCUR / OOFF / FNAL. FRST.- First collection of a series of direct debit instructions. RCUR.- Recurring Direct debit instruction where the debtor's authorisation is used for regular direct debit transactions initiated by the creditor OOFF.- OneOff Direct debit instruction where the debtor's authorisation is used to initiate one single direct debit transaction FNAL .- Final collection of a series of direct debit instructions.
|
drctDbtTxInf[].reqdColltnDt | Requested Collection Date Requested date to pull funds. |
drctDbtTxInf[].intrBkSttlmAmt | Interbank settlement amount The currency must be EUR and the amount must be a positive value. |
drctDbtTxInf[].chrgBr | Charge bearer type. Value: SLEV |
drctDbtTxInf[].drctDbtTx.mndtRltdInf.* | Mandate information Mandate ID, signature date, amendments. |
drctDbtTxInf[].drctDbtTx.cdtrSchmeId.* | Creditor Scheme ID (SCI) Creditor identifier. |
cdtrAgt.finInstnId.bicfi / dbtrAgt.finInstnId.bicfi | Creditor/Debtor agents PSP BICs. |
cdtrAcct.id.iban / dbtrAcct.id.iban | Creditor/Debtor accounts IBANs. |
rmtInf.ustrd | Remittance information Free text (e.g., invoice/ref). |
Request body example:
{
"fitoFICstmrDrctDbt": {
"grpHdr": {
"msgId": "9b5e2c3d-36c1-41c6-9c81-8a2a3c4f1200",
"nbOfTxs": "1",
"creDtTm": "2025-10-21T10:32:00Z",
"sttlmInf": { "sttlmMtd": "CLRG" }
},
"drctDbtTxInf": [
{
"pmtId": {
"endToEndId": "E2E-INV-2025-0001",
"txId": "TX-0001"
},
"pmtTpInf": {
"svcLvl": [{ "cd": "SEPA" }],
"lclInstrm": { "cd": "CORE" },
"seqTp": "FRST"
},
"reqdColltnDt": "2025-10-25",
"intrBkSttlmAmt": { "ccy": "EUR", "value": 100.00 },
"chrgBr": "SLEV",
"drctDbtTx": {
"mndtRltdInf": {
"mndtId": "MND-00004567",
"dtOfSgntr": "2024-03-15"
},
"cdtrSchmeId": {
"id": {
"prvtId": {
"othr": {
"id": "ES12ZZZ123456",
"schmeNm": { "prtry": "SEPA" }
}
}
}
}
},
"cdtrAgt": { "finInstnId": { "bicfi": "BBVAESMMXXX" } },
"cdtr": {
"nm": "Creditor Company SA",
"pstlAdr": {
"twnNm": "Madrid",
"ctry": "ES",
"adrLine": ["Calle Mayor 1", "28013"]
}
},
"cdtrAcct": { "id": { "iban": "ES7620770024012345678901" } },
"dbtrAgt": { "finInstnId": { "bicfi": "DEUTDEFFXXX" } },
"dbtr": {
"nm": "Debtor Client SL",
"pstlAdr": {
"twnNm": "Berlin",
"ctry": "DE",
"adrLine": ["Unter den Linden 5", "10117"]
}
},
"dbtrAcct": { "id": { "iban": "DE89370400440532013000" } },
"rmtInf": { "ustrd": ["Invoice 2025/0001"] }
}
]
}
}