Getting payment cancellation details (camt.056)
This tutorial describes how you can get payment cancellation details with the Payments Hub API.
For this tutorial, consider a scenario where a customer has sent a payment which they have cancelled f or some reason, and they later want to see the payment cancellation ID and amount for that cancellation. The Payments Hub API can be used to retrieve these details. The tutorial describes how you can retrieve the payment cancellation details using the ISO camt.056 message.
Sandbox
The information in this tutorial applies to the Sandbox only
Parameters
The request must contain the path parameter shown in the following table.
Table: Retrieve payment cancellation details – Request parameter.
Parameter type | Parameter name | Description | Data format | Required/ Optional |
|---|---|---|---|---|
Path | paymentsHubId | Payments Hub ID related to the payment cancellation whose details you want to retrieve. This is the value you received when you originally submitted the payment cancellation request. | String | Required |
Response
If the request is valid, you receive an HTTP 200 OK response, which means that the payment cancellation details were successfully retrieved. For further details of HTTP response codes and instructions on how to handle errors, see HTTP codes and request error handling .
In addition to the response code, the response body returns the fitoFIPmtCxlReq JSON object, which contains a camt.056 ISO message.
Response body
The following table shows the response body elements that are relevant for the current use case for the SCT payment scheme. For details on all the response body elements, see the Message field definition for camt.056 .
Table: Retrieve payment cancellation details – Relevant response body elements.
Element | Description | Data type |
|---|---|---|
undrlyg.txInf.cxlId | Unique payment cancellation ID for the end customer | String |
undrlyg.txInf.orgnlTxRef.intrBkSttlmAmt | Data structure containing the payment currency and the amount to be cancelled. The currency is EUR. | Object |
Extract the values of the undrlyg.txInf.cxlId, undrlyg.txInf.orgnlTxRef.intrBkSttlmAmt.value, and undrlyg.txInf.orgnlTxRef.intrBkSttlmAmt.ccy keys to see the payment cancellation ID, amount, and currency.
Example response body for the SCT payment scheme:
{
"fitoFIPmtCxlReq": {
"assgnmt": {
"id": "MsgId-2046908283",
"assgnr": {
"agt": {
"finInstnId": {
"bicfi": "BSCHESMMXXX"
}
}
},
"assgne": {
"agt": {
"finInstnId": {
"bicfi": "BBVAESMMXXX"
}
}
},
"creDtTm": "2022-03-10T13:20:31.475+01:00"
},
"undrlyg": [
{
"txInf": [
{
"cxlId": "TransactionId-2046908283",
"orgnlEndToEndId": "endToEndId",
"cxlRsnInf": [
{
"orgtr": {
"nm": "customer-error-name",
"id": {
"orgId": {
"anyBIC": "BSABESBBXXX"
}
}
},
"rsn": {
"cd": "DUPL"
}
}
],
"orgnlTxRef": {
"intrBkSttlmAmt": {
"value": 10.04,
"ccy": "EUR"
},
"pmtTpInf": {
"svcLvl": [
{
"prtry": "SEPA"
}
]
},
"cdtrAgt": {
"finInstnId": {
"bicfi": "BSCHGBM0XXX",
"pstlAdr": {
"twnNm": "Madrid",
"ctry": "ES",
"adrLine": [
"Somewhere in Madrid"
]
}
}
},
"cdtrAcct": {
"id": {
"iban": "GB91BARC20032634945865"
},
"ccy": "EUR"
}
}
}
]
}
]
}
}