Contents x
    Pacs.004.001.09
    • 17 Sep 2024
    • 12 Minutes to read
    • Print
    • Dark
      Light
    Contents

    Pacs.004.001.09

    • Updated on 17 Sep 2024
    • 12 Minutes to read
    • Print
    • Dark
      Light
    Article summary

    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:

    • In case of Answer to a Recall: AT-R7 Specific Reference of the bank initiating the recall

    • In case of Response to the Request for Recall by the Originator or to the Request for Status Update on a Request for a Recall: AT-51 The specific reference of the Originator Bank for the Request for Recall by the Originator

    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"
                        }
                    }
                }
            }
        ]
    }
}

    ISO20022 API Specification

    Was this article helpful?
    What's Next

    Let's have a conversation

    Reach out to us and will help you to solve your questions

    Get in touch

    © 2024 PagoNxt S.L. PagoNxt is a registered trademark. All rights reserved.
    www.pagonxt.com