Returning payments with CHAPS
Accompanying information
This tutorial accompanies the header information found in the Payment Return message tutorial
A payment return is an operation sent by an agent to the previous agent in the payment chain to undo a previously settled payment. The Payment/Return message is exchanged between agents to return funds after settlement of credit transfer instructions.
The request must include a JSON payload object in the request body. The JSON payload is a pacs.004 v9 ISO message with the TxInf root element, and it contains the request details to return a payment. The return operation must be initiated on an already existing incoming payment in Payments Hub. It is allowed to initiate returns on Pacs.008.001.08, Pacs.009.001.08 and Pacs.009.001.08 COV messages
In this scenario imagine an international company which has an account at Bank A, and wants to make a payment to another company, bank B. This payment will be made through the CHAPS system using a pacs.009 message.
Upon receiving the message, the account of the company in the bank B has been recently closed or blocked. As a result, bank B is unable to complete the transaction and to return the funds, sends a pacs.004 message through CHAPS.
The following table only provides information about some especially important fields.
Message field | Description | Data type | Required/ Optional |
|---|---|---|---|
grpHdr.msgId | Point to point reference, as assigned by the instructing party, and sent to the next party in the chain to unambiguously identify the message. Usage: The instructing party has to make sure that MessageIdentification is unique per instructed party for a pre-agreed period. | String | Optional |
grpHdr.CreDtTm | Date and time at which the message was created. | Date | Optional |
grpHdr.NbOfTxs | Number of individual transactions contained in the message. | String | Required |
grpHdr.Cd | Type of address expressed as a code. | String | Required |
TxInf.RtrId | Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the returned transaction. Usage: The instructing party is the party sending the return message and not the party that sent the original instruction that is being returned. | String | Required |
TxInf.OrgnlEndToEndId | Unique identification, as assigned by the original initiating party, to unambiguously identify the original transaction. | String | Required |
TxInf.OrgnlUETR | Universally unique identifier to provide the original end-to-end reference of a payment transaction. | String | Required |
TxInf.IntrBkSttlmDt | Date on which the amount of money ceases to be available to the agent that owes it and when the amount of money becomes available to the agent to which it is due. | Date | Required |
TxInf.RtrdInstdAmt | Amount of money to be moved between the debtor and the creditor, before deduction of charges, in the returned transaction. | Numeric | Optional |
TxInf.ChrgBr | Specifies which party/parties will bear the charges associated with the processing of the payment transaction. Usage: The ChargeBearer applies to the return message, not to the original instruction. | String | Required |
TxInf.InstgAgt | gent that instructs the next party in the chain to carry out the (set of) instruction(s). Usage: The instructing agent is the party sending the return message and not the party that sent the original instruction that is being returned. | String | Required |
TxInf.InstdAgt | Agent that is instructed by the previous party in the chain to carry out the (set of) instruction(s). Usage: The instructed agent is the party receiving the return message and not the party that received the original instruction that is being returned. | String | Required |
TxInf.RtrRsnInf | Provides detailed information on the return reason. Annotation:
| String | Required |
Example request body:
{
"hubMessage": {
"messageType": "pacs_004_v09",
"document": {
"pmtRtr": {
"txInf": [
{
"rtrdInstdAmt": {
"ccy": "GBP",
"value": 66.66
},
"orgnlIntrBkSttlmAmt": {
"ccy": "GBP",
"value": 66.66
},
"rtrdIntrBkSttlmAmt": {
"ccy": "GBP",
"value": 66.66
},
"instdAgt": {
"finInstnId": {
"bicfi": "BSCHGB22XXX"
}
},
"orgnlEndToEndId": "NOTPROVIDED",
"intrBkSttlmDt": "2022-08-31",
"sttlmPrty": "NORM",
"orgnlUETR": "c47812f0-e34d-4752-8013-455de1793f00",
"orgnlIntrBkSttlmDt": "2025-06-25",
"rtrChain": {
"cdtr": {
"agt": {
"finInstnId": {
"bicfi": "BSCHGB22XXX",
"nm": "SCREENING_AML_OK"
}
}
},
"dbtr": {
"agt": {
"finInstnId": {
"bicfi": "UBSWGB55XXX"
}
}
},
"dbtrAgt": {
"finInstnId": {
"bicfi": "UBSWGB55XXX"
}
},
"cdtrAgt": {
"finInstnId": {
"bicfi": "BSCHGB22XXX"
}
}
},
"chrgBr": "SHAR",
"orgnlGrpInf": {
"orgnlMsgNmId": "pacs.008.001.08",
"orgnlMsgId": "802b60921fe146cc"
},
"instgAgt": {
"finInstnId": {
"bicfi": "UBSWGB55XXX"
}
},
"rtrId": "2ee03165906a-4c",
"orgnlTxRef": {
"dbtrAcct": {
"id": {
"othr": {
"id": "1100650068280"
}
}
},
"dbtrAgt": {
"finInstnId": {
"bicfi": "BSCHGB22XXX"
}
}
},
"rtrRsnInf": [
{
"rsn": {
"cd": "BE08"
}
}
],
"orgnlInstrId": "JAWAS-CHAPS1750846599927"
}
],
"grpHdr": {
"nbOfTxs": "1",
"msgId": "2ee03165906a-4c",
"sttlmInf": {
"clrSys": {
"cd": "STG"
},
"sttlmMtd": "CLRG"
},
"creDtTm": "2025-06-25T10:17:04.318Z"
}
}
},
"client": {
"internalId": "3741",
"initiator": "migration-test"
},
"flow": "reception"
},
"executionId": {
"paymentHubId": "07618b1c-2bbe-3d65-969b-7b502ccad99d",
"executionNumber": 0
}
}