Returning payments with SEPA Credit Transfer (pacs.004)
This tutorial describes how you can return SEPA Credit Transfer (SCT) payments with the Payments Hub API it accompanies the information found in the Payment return general tutorial here
For this tutorial, consider a scenario where you are a payment provider, and your merchant has a customer who purchases an item for which they accidently send a duplicate payment. The Payments Hub API can be used to return the money of the duplicate payment from the merchant to the customer’s account.
Sandbox
The instructions in this tutorial apply to the Sandbox environment
Request body
The request must include a JSON payload object in the request body. The JSON payload is a pacs.004 ISO message with the pmtRtr root element, and it contains the request details for returning a payment.
The following table only provides information about some especially important fields. For details on all the required and optional message fields, see Message field definition for pacs.004 .
Table: Return the payment - Relevant request body elements.
Message field | Description | Data type | Required/Optional |
|---|---|---|---|
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 return request | String | Required |
grpHdr.nbOfTxs | Number of transactions within the message. Value: 1 | Number | Required |
grpHdr.sttlmInf.sttlmMtd | Settlement method. Value: CLRG | String | Required |
txInf.rtrId | Unique payment return ID for the end customer | String | Required |
txInf.rtrdIntrBkSttlmAmt | Data structure containing the payment currency and the amount to be returned. The currency must be EUR and the amount must be a positive value. | Object | Required |
txInf.chrgBr | Charge bearer type. Value: SLEV | String | Required |
Code for the payment reversal | String | Required | |
txInf.orgnlTxRef | Data structure containing the transaction reference used to identify the original transaction | Object | Required |
Example request body:
{
"pmtRtr": {
"grpHdr": {
"msgId": "MsgId-4268513950",
"creDtTm": "2022-03-09T16:30:22.868+01:00",
"nbOfTxs": "1",
"sttlmInf": {
"sttlmMtd": "CLRG"
}
},
"txInf": [
{
"rtrId": "transactionId-4268513950",
"rtrdIntrBkSttlmAmt": {
"value": 10.04,
"ccy": "EUR"
},
"intrBkSttlmDt": "2020-12-16",
"chrgBr": "SLEV",
"instgAgt": {
"finInstnId": {
"bicfi": "ABBYGB20XXX"
}
},
"instdAgt": {
"finInstnId": {
"bicfi": "BSCHESM0XXX"
}
},
"rtrRsnInf": [
{
"rsn": {
"cd": "AC01"
},
"addtlInf": [
"raw-code",
"raw-description"
]
}
],
"orgnlTxRef": {
"pmtTpInf": {
"svcLvl": [
{
"prtry": "SEPA"
}
],
"lclInstrm": {
"prtry": "TRF"
}
},
"dbtr": {
"pty": {
"nm": "Debtor",
"pstlAdr": {
"twnNm": "Madrid",
"ctry": "ES",
"adrLine": [
"Somewhere in Madrid"
]
},
"id": {
"prvtId": {
"othr": [
{
"id": "F99999"
}
]
}
}
}
},
"dbtrAcct": {
"id": {
"othr": {
"id": "12345678"
}
}
},
"dbtrAgt": {
"finInstnId": {
"bicfi": "ABBYGB20",
"clrSysMmbId": {
"mmbId": "777241"
}
}
},
"cdtrAgt": {
"finInstnId": {
"bicfi": "BSCHPTM0XXX",
"pstlAdr": {
"twnNm": "Lisbon",
"ctry": "PT",
"adrLine": [
"Somewhere in Lisbon"
]
}
}
},
"cdtrAcct": {
"id": {
"iban": "PT91BARC20032634945865"
},
"ccy": "EUR"
}
}
}
]
}
}