- 17 Sep 2024
- 12 Minutes to read
- Print
- DarkLight
Pacs.004.001.09
- Updated on 17 Sep 2024
- 12 Minutes to read
- Print
- DarkLight
The request must include a JSON payload object in the request body. The JSON payload is a pacs.004.001.09 ISO message with the pmtRtr root element, and it contains the request details for submitting a payment.
The functional changes for SEPA Rulebook 2023 are highlighted.
Table: pacs.004.01.09.
Message field | Description | Data type | Required/Optional | Example |
---|---|---|---|---|
grpHdr.msgId | Message ID, which must uniquely identify each request you send. This ID is used internally for idempotency of the API. | String | Required | |
grpHdr.creDtTm | Date and time of the payment request | String | Required | |
grpHdr.nbOfTxs | Number of transactions within the message. Value: 1 | Number | Required | |
grpHdr.ttlRtrdIntrBkSttlmAmt | Total amount of money moved between the instructing agent and the instructed agent in the return message. The currency must be EUR and the amount must be a positive value. | Object | Optional | |
grpHdr.intrBkSttlmDt | Date when the interbank settlement amount moves from the instructing agent to the instructed agent | String | Required | |
grpHdr.sttlmInf.sttlmMtd | Settlement method. | String | Required | CLRG |
grpHdr.sttlmInf.clrSys.prtry | Clearing System. | String | Optional | ST2 |
grpHdr.instgAgt.finInstnId.bicfi | Instructing Agent's BICFI. | Object | Optional | BSCHESMMXXX |
grpHdr.instdAgt.finInstnId.bicfi | Instructed Agent's BICFI. | Object | Optional | BSCHESMMXXX |
txInf.rtrId | Return Identification, which must uniquely identify each request you send. | String | Required | |
txInf.orgnlGrpInf.orgnlMsgId | Original Message Identification. | String | Required | |
txInf.orgnlGrpInf.orgnlMsgNmId | Original Message Name Identification. | String | Required | pacs.008.001.08 |
txInf.orgnlInstrId | Original Instruction Identification. | String | Optional | |
txInf.orgnlEndToEndId | Original End To End Identification. | String | Required | |
txInf.orgnlTxId | Original Transaction Identification. | String | Required | |
txInf.orgnlIntrBkSttlmAmt | Data structure containing the amount of money moved between the instructing agent and the instructed agent, as provided in the original instruction. The currency must be EUR and the amount must be a positive value. | Object | Required | |
txInf.rtrdIntrBkSttlmAmt | Data structure containing the amount of money to be moved between the instructing agent and the instructed agent in the returned instruction. The currency must be EUR and the amount must be a positive value. | Object | Required | |
txInf.rtrdInstdAmt | Returned Instructed Amount. Only allowed in the case of a return in response to a cancellation request. The currency must be EUR and the amount must be a positive value. | Object | Optional | |
txInf.chrgBr | Charge bearer type. Value: SLEV | String | Required | |
txInf.chrgsInf.amt | Charges Amount. The currency must be EUR and the amount must be a positive value. | Object | Optional | |
txInf.rtrRsnInf.orgtr.nm | Return originator name. | String | Required | |
txInf.rtrRsnInf.orgtr.id.orgId.anyBIC | Return originator BICFI. | Object | Required | |
txInf.rtrRsnInf.rsn | Return reason. Can be cd or prtry ► .cd only EBA codes are allowed (see below) ► .prtry | Object | Required | |
txInf.rtrRsnInf.addtlInf | Aditional Info Only allowed when "FOCR" is present in "Reason". In this case, it is mandatory and only one occurrence is allowed. To be populated as follows:
| String | Optional | |
txInf.orgnlTxRef.intrBkSttlmDt | Interbank Settlement Date. | String | Optional | |
txInf.orgnlTxRef.sttlmInf.sttlmMtd | Settlement Method. Value: CLRG | String | Optional | |
txInf.orgnlTxRef.pmtTpInf.svcLvl.prtry | Payment scheme type. Value: SEPA | String | Optional | |
txInf.orgnlTxRef.pmtTpInf.lclInstrm | Local Instrument. Can be cd or prtry. | String | Optional | |
txInf.orgnlTxRef.pmtTpInf.ctgyPurp | Category Purpose. Can be cd or prtry. | String | Optional | |
txInf.orgnlTxRef.rmtInf | Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts receivable system. Can be strd or ustrd. | Object | Optional | |
txInf.orgnlTxRef.ultmtDbtr.pty.nm | Name by which a party is known and which is usually used to identify that party. | String | Optional | |
txInf.orgnlTxRef.ultmtDbtr.pty.id.orgId.anyBIC | String | Optional | ||
txInf.orgnlTxRef.dbtr.pty.nm | Name by which a party is known and which is usually used to identify that party. | String | Required | |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.dept | Identification of a division of a large organisation or building. | String | Optional | |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.subDept | Identification of a sub-division of a large organisation or building. | String | Optional | |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.strNme | Name of a street or thoroughfare. | String | Optional | |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.bldgNm | Name of the building or house. | String | Optional | |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.bldgNb | Number that identifies the position of a building on a street. | String | Optional | |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.Flr | Floor or storey within a building. | String | Optional | |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.pstBx | Numbered box in a post office, assigned to a person or organisation, where letters are kept until called for. | String | Optional | |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.room | Building room number. | String | Optional | |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.pstCd | Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail. | String | Optional | |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.twnNm | Name of a built-up area, with defined boundaries, and a local government. | String | Optional | |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.twnLctnNm | Specific location name within the town. | String | Optional | |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.dstrctNm | Identifies a subdivision within a country sub-division. | String | Optional | |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.ctrySubDvsn | Identifies a subdivision of a country such as state, region, county. | String | Optional | |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.ctry | Code to identify a country, a dependency, or another area of particular geopolitical interest, on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code). | String | Optional | BE |
txInf.orgnlTxRef.dbtr.pty.pstlAdr.adrLine | String | Optional | ||
txInf.orgnlTxRef.dbtr.pty.id.orgId.anyBIC | String | Optional | ||
txInf.orgnlTxRef.dbtrAcct.id.iban | String | Required | ||
txInf.orgnlTxRef.dbtrAgt.finInstnId.bicfi | String | Required | ||
txInf.orgnlTxRef.cdtrAgt.finInstnId.bicfi | String | Required | ||
txInf.orgnlTxRef.cdtr.pty.nm | Name by which a party is known and which is usually used to identify that party. | String | Required | |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.dept | Identification of a division of a large organisation or building. | String | Optional | |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.subDept | Identification of a sub-division of a large organisation or building. | String | Optional | |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.strNme | Name of a street or thoroughfare. | String | Optional | |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.bldgNm | Name of the building or house. | String | Optional | |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.bldgNb | Number that identifies the position of a building on a street. | String | Optional | |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.Flr | Floor or storey within a building. | String | Optional | |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.pstBx | Numbered box in a post office, assigned to a person or organisation, where letters are kept until called for. | String | Optional | |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.room | Building room number. | String | Optional | |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.pstCd | Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail. | String | Optional | |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.twnNm | Name of a built-up area, with defined boundaries, and a local government. | String | Optional | |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.twnLctnNm | Specific location name within the town. | String | Optional | |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.dstrctNm | Identifies a subdivision within a country sub-division. | String | Optional | |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.ctrySubDvsn | Identifies a subdivision of a country such as state, region, county. | String | Optional | |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.ctry | Code to identify a country, a dependency, or another area of particular geopolitical interest, on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code). | String | Optional | BE |
txInf.orgnlTxRef.cdtr.pty.pstlAdr.adrLine | String | Optional | ||
txInf.orgnlTxRef.cdtr.pty.id.orgId.anyBIC | String | Optional | ||
txInf.orgnlTxRef.cdtrAcct.id.iban | String | Required | ||
txInf.orgnlTxRef.ultmtCdtr.pty.nm | Name by which a party is known and which is usually used to identify that party. | String | Optional | |
txInf.orgnlTxRef.ultmtCdtr.pty.id.orgId.anyBIC | String | Optional | ||
txInf.orgnlTxRef.purp | Purpose | String | Optional |
Allowed EBA codes for Return reason:
Table: Allowed EBA codes
EBA code | ISO code description |
---|---|
AC01 | Incorrect Account Number |
AC04 | Closed Account Number |
AC06 | Blocked Account |
AG01 | Transaction Forbidden |
AG02 | Invalid Bank Operation Code |
AM05 | Duplication |
BE04 | Missing Creditor Address |
CNOR | Creditor Bank is not registered |
ERIN | ERI Option Not Supported |
FOCR | Following Cancellation Request |
MD07 | End Customer Deceased |
MS02 | Not Specified Reason Customer Generated |
MS03 | Not Specified Reason Agent Generated |
RC01 | Bank Identifier Incorrect |
RR01 | Missing Debtor Account Or Identification |
RR02 | Missing Debtor Name or Address - Code used by banks to indicate a Return for Regulatory Reason |
RR03 | Missing Creditor Name or Address – Code used by banks to indicate a Return for Regulatory Reason |
RR04 | Regulatory Reason |
Example request body:
{
"pmtRtr": {
"grpHdr": {
"msgId": "MsgId-2581783931",
"creDtTm": "2021-02-03T04:05:06.000Z",
"nbOfTxs": "1",
"intrBkSttlmDt": "2021-02-03",
"sttlmInf": {
"sttlmMtd": "CLRG"
}
},
"txInf": [
{
"pmtId": {
"endToEndId": "E2eId-893748283"
},
"rtrId": "rtrId-3842348347",
"orgnlGrpInf": {
"orgnlMsgNmId": "pacs.008.001.08",
"orgnlMsgId": "MsgId-2581783930"
},
"orgnlEndToEndId": "E2eId-893748281",
"orgnlTxId": "txId-1688023443",
"orgnlIntrBkSttlmAmt": {
"ccy": "EUR",
"value": 100.00
},
"rtrdIntrBkSttlmAmt": {
"ccy": "EUR",
"value": 100.00
},
"chrgBr": "SLEV",
"rtrRsnInf": [
{
"orgtr": {
"nm": "Originator name",
"id": {
"orgId": {
"anyBIC": "BSCHESM0XXX"
}
}
},
"rsn": {
"cd": "AC01"
}
}
],
"intrBkSttlmDt": "2021-02-03",
"orgnlTxRef": {
"dbtr": {
"pty": {
"nm": "Mr Debtor"
}
},
"dbtrAcct": {
"nm": "Mr Debtor",
"id": {
"iban": "ES9300492060833000002503"
}
},
"dbtrAgt": {
"finInstnId": {
"bicfi": "EBURESM1XXX"
}
},
"cdtr": {
"nm": "Mr Creditor"
},
"cdtrAcct": {
"id": {
"iban": "FI9580002811571214"
}
},
"cdtrAgt": {
"finInstnId": {
"bicfi": "BSCHESMMXXX"
}
}
}
}
]
}
}
Request
The following example illustrates the request using raw HTTP code:
POST /payments/pacs004/v08 HTTP/1.1
Host: sandbox.api.pagonxt.com
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
X-Client-Id: YOUR_CLIENT_ID
sca-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ikh1YnRlc3RfcHJvX3NhbmRib3gifQ.eyJoZCI6ImMrMkRKZEUyeklSTkNTS3hMVEU1TnIzVGpmQzRaVUFreTlxM0FuNFZLc3M9Iiwibm9uY2UiOiI2ZGNmOTgyZmM4ZTQ0YmVlOTRiYiIsImFsZyI6IlNIQTI1NiIsImlhdCI6MTY1NDUyNjUyMSwibmJmIjoxNjU0NTI2NTIxLCJleHAiOjE2ODYwNjI1MjEsImp0aSI6IjcwNDJjMjNhLWMzYmItNGU2MS04NjI4LTA1ZDRjODg2MWM0ZSJ9.KqRmUansjP5c-TRg8HcCS65x8I7w6EjT8xDQS83MoYMJiITAX50p1-gtnhtNAD-1l2CdUJfbyV9TzOn7qzm0uXx0rdWOaJ79efV5gEamc3jQNNFfhok9kwwKnlOX5d60UwGfLYbAJdZBZc49eyYRIojacTSVAewcKdXpTbwPPJE140WEYLwWkSXmUCPg1dPNyrogduHGl8DYEPdiaPytty-Bp9H_wApvQ5VAYmu111WzMCI0SPmo-eLGAj20C1sRVgKpl_-Puo-9gT2XOK1EBoD6qG_a2PaPuFxkAcm3W0-NtbEiYFnkvcS8zbMpHjdKq84qmh7Fq9ZsrsKgVJMfug
Content-Length: 3283
{
"pmtRtr": {
"grpHdr": {
"msgId": "MsgId-2581783931",
"creDtTm": "2021-02-03T04:05:06.000Z",
"nbOfTxs": "1",
"intrBkSttlmDt": "2021-02-03",
"sttlmInf": {
"sttlmMtd": "CLRG"
}
},
"txInf": [
{
"pmtId": {
"endToEndId": "E2eId-893748283"
},
"rtrId": "rtrId-3842348347",
"orgnlGrpInf": {
"orgnlMsgNmId": "pacs.008.001.08",
"orgnlMsgId": "MsgId-2581783930"
},
"orgnlEndToEndId": "E2eId-893748281",
"orgnlTxId": "txId-1688023443",
"orgnlIntrBkSttlmAmt": {
"ccy": "EUR",
"value": 100.00
},
"rtrdIntrBkSttlmAmt": {
"ccy": "EUR",
"value": 100.00
},
"chrgBr": "SLEV",
"rtrRsnInf": [
{
"orgtr": {
"nm": "Originator name",
"id": {
"orgId": {
"anyBIC": "BSCHESM0XXX"
}
}
},
"rsn": {
"cd": "AC01"
}
}
],
"intrBkSttlmDt": "2021-02-03",
"orgnlTxRef": {
"dbtr": {
"pty": {
"nm": "Mr Debtor"
}
},
"dbtrAcct": {
"nm": "Mr Debtor",
"id": {
"iban": "ES9300492060833000002503"
}
},
"dbtrAgt": {
"finInstnId": {
"bicfi": "EBURESM1XXX"
}
},
"cdtr": {
"nm": "Mr Creditor"
},
"cdtrAcct": {
"id": {
"iban": "FI9580002811571214"
}
},
"cdtrAgt": {
"finInstnId": {
"bicfi": "BSCHESMMXXX"
}
}
}
}
]
}
}