- 18 Sep 2024
- 19 Minutes to read
- Print
- DarkLight
Cancelling payments with SEPA Credit Transfer (camt.056 and camt.029)
- Updated on 18 Sep 2024
- 19 Minutes to read
- Print
- DarkLight
This tutorial describes how you can cancel SEPA Credit Transfer (SCT) payments with the Payments Hub API.
For this tutorial, consider a scenario where a customer has sent a payment, but realizes that it was incorrect, and wants to cancel it. The Payments Hub API can be used to request the cancellation of any payment like this.
This tutorial describes, in 2 separate sections, how:
You can initiate a cancellation for an SCT payment using the ISO camt.056 message.
You can retrieve the cancellation status using the ISO camt.029 message.
Note
The instructions in this tutorial apply to the sandbox environment.
Prerequisites
Before obtaining the access token, make sure you have a public-private key pair that you can use to sign JWT Bearer tokens.
Click here to email your public key, along with the kid and iss claim values you will use in your JWT Bearer tokens.
Note
The public key must be created with RSA and sent in PEM format, without password encryption, and must have a length of at least 2048 bits. If these criteria are not met, the token will be rejected.
If you don't have a public-private key pair yet, you can use a predefined JWT Bearer token in the sandbox with no need to create or sign your own tokens for authentication:
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ikh1YnRlc3RfcHJvX3NhbmRib3gifQ.eyJzdWIiOiJxTWtaOTBxb0hBTjVJbkE2V2xNYVZBaE41dDhBQWVPeCIsImlzcyI6IlNhbnRhbmRlciIsImlhdCI6MTY2MTMyNzQyNSwibmJmIjoxNjYxMzI3NDI1LCJleHAiOjE2OTI4NjM0MjUsImp0aSI6IjRmMjM0ZmIxLWM3ODAtNGVhNS05YmI5LTBkMTZiYzU3MmFmNyJ9.lz19moa2xSUeBoz4-55qF15CY_LU-1Vb7bh14Q1pGjqR7hEL3OdxK9-EnWSP4eDMivMZWTHOXbFTj9WcH0eiX1u7fNJVVhyWTUqvIfI5Qcpal2j2pQElLe9mv7bytMGPbDpK-9kNqkuNX4J_LB7qLZJtPwSbsFtICORpLrBeMHwqWLRnaFVOMuiMM14CXG31YaKNVphowthVA_21CuE0P5Tl5iIlJIx0MENoq_pbmQpFkuN0VlxW7gv9Zrqo44Vd4TtoZiF4uY-PgbT3JDnbEe5pRa7C4vF-LHrdgfpNW9fjW9kut-ZuyeEIH240t6emstsdtcFAC18TpZjo9HM3sw
In the sandbox environment, you can use a predefined test SCA JWT Bearer token:
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InByb1BheW1lbnRzSHViU2IifQ.eyJoZCI6Im1qbHRHRGU0Ni93c2dubkxyMFZpSEVPUEw2SW1MNm9CK2hHam1lOENrZzQ9Iiwibm9uY2UiOiI0ODEwZjQ2Y2I1OGViNzI4ZDI4NSIsImFsZyI6IlNIQTI1NiIsImlhdCI6MTcxMjMxMTUxMSwibmJmIjoxNzEyMzExNTExLCJleHAiOjE3NDM4NDc1MTEsImp0aSI6IjZiZmYxMzJhLTUyNTItNDJhYS1iODk0LWRhMTA0ZWU3NmQzZiJ9.f56W53dj2ztor5qf0JZFdOg35ly1Y2szDQU1qQR0yJ-EjQgEJBbyob4TZpWFk5yOq5F8bTW50OHb8mYfl3wDRovNlSZFQlshLQOF8TYlXte6n44sMN7kcFq4rAV_SrRJjUmt_4uoBdw-KNgaMQ5NIO6EQqY5G9qBfEFdK9BdzuL72Mz8o_rUGn4nfGlAy8R2LayynOEjIeStypmgKBqYcMI5v804Unar7p9AXCUhD-OfSXmAJ3vVlQTupTKd0WfjgAVNxJNp3Ybu196s48kDzzeB3zCQCUFrvrDqnlY49U9y3BikcomPPLAbV_HcaPHk_SAp7lyi7HblXezwgyBwpw
1. Authenticate to get an access token
The Payments Hub API endpoints are protected with OAuth 2.0 JWT Bearer grant. To use the API, you must create a JWT Bearer token and use it to get an access token:
To create a JWT Bearer token, see the Appendix in Authentication guide . For a predefined token that you can use in the sandbox for testing purposes, see the Prerequisites in Authentication guide .
For detailed instructions on how to get the access token, see Authentication guide .
2. Cancel the payment
This section describes how to request the cancellation of a payment via a camt.056 HTTP request to the Payments Hub API. It also illustrates a successful response.
Request
Create and send a request using the following operation:
POST https://sandbox.api.pagonxt.com/payments/camt056/v08
Headers
The request must contain the headers shown in the following table.
Table: Cancel the payment - Required request headers.
Header name | Description | Required/ Optional | Values |
---|---|---|---|
Authorization | Authorization security header | Required | Bearer <Access token> |
X-Client-Id | Client ID | Required | <Client ID> |
Content-Type | Format of the request body | Required | application/json |
sca-token |
| Required | <SCA token> |
Accept | Format of the response body | Required | application/json |
Request body
The request must include a JSON payload object in the request body. The JSON payload is a camt.056 ISO message with the fitoFIPmtCxlReq root element, and it contains the request details for cancelling 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 camt.056 .
Table: Cancel the payment - Relevant request body elements.
Message field | Description | Data type | Required/Optional |
---|---|---|---|
assgnmt.id | Assignment ID that uniquely identifies the investigation assignment. This ID is used internally for idempotency of the API. | String | Required |
assgnmt.assgnr | Data structure containing the assigner details. For this scenario, this is the customer’s agent. | Object | Required |
assgnmt.assgne | Data structure containing the assignee details. For this scenario, this is the merchant’s agent. | Object | Required |
undrlyg.txInf.cxlId | Unique payment cancellation ID for the end customer | String | Required |
undrlyg.txInf.orgnlTxRef.intrBkSttlAmt | Data structure containing the payment currency and the amount of the original transaction. The currency must be EUR and the amount must be a positive value. | Object | Optional |
undrlyg.txInf.cxlRsnInf | Array of information about the cancellation reason | Array | Required |
undrlyg.txInf.orgnlTxRef | Data structure containing the transaction reference used to identify the original transaction | Object | Required |
Example request body:
{
"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"
}
}
}
]
}
]
}
}
Request example
The following example illustrates the request using raw HTTP code:
POST /payments/camt056/v08 HTTP/1.1
Host: sandbox.api.pagonxt.com
X-Client-Id: YOUR_CLIENT_ID
Content-Type: application/json
sca-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InByb1BheW1lbnRzSHViU2IifQ.eyJoZCI6Im1qbHRHRGU0Ni93c2dubkxyMFZpSEVPUEw2SW1MNm9CK2hHam1lOENrZzQ9Iiwibm9uY2UiOiI0ODEwZjQ2Y2I1OGViNzI4ZDI4NSIsImFsZyI6IlNIQTI1NiIsImlhdCI6MTcxMjMxMTUxMSwibmJmIjoxNzEyMzExNTExLCJleHAiOjE3NDM4NDc1MTEsImp0aSI6IjZiZmYxMzJhLTUyNTItNDJhYS1iODk0LWRhMTA0ZWU3NmQzZiJ9.f56W53dj2ztor5qf0JZFdOg35ly1Y2szDQU1qQR0yJ-EjQgEJBbyob4TZpWFk5yOq5F8bTW50OHb8mYfl3wDRovNlSZFQlshLQOF8TYlXte6n44sMN7kcFq4rAV_SrRJjUmt_4uoBdw-KNgaMQ5NIO6EQqY5G9qBfEFdK9BdzuL72Mz8o_rUGn4nfGlAy8R2LayynOEjIeStypmgKBqYcMI5v804Unar7p9AXCUhD-OfSXmAJ3vVlQTupTKd0WfjgAVNxJNp3Ybu196s48kDzzeB3zCQCUFrvrDqnlY49U9y3BikcomPPLAbV_HcaPHk_SAp7lyi7HblXezwgyBwpw
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Length: 2792
{
"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"
}
}
}
]
}
]
}
}
Response
If the request is valid, you receive an HTTP 201 Created response, which means that the payment cancellation request was successfully submitted. In addition, the response body returns the data JSON object, which contains payment cancellation details. If the request is submitted again with the same message ID, you receive an HTTP 200 OK response. For further details of HTTP response codes and instructions on how to handle errors, see HTTP codes and request error handling .
The following table shows the response body elements that are relevant for the current use case. For details on all the response body elements, see Message field definition for camt.056 .
Table: Cancel the payment - Relevant response body elements.
Element | Description | Data type |
---|---|---|
paymentsHubId | Payments Hub ID, which uniquely identifies your payment cancellation request in Payments Hub. You can use it if you later need to retrieve the payment cancellation details. | String |
paymentsId | Message ID you defined in the request as the assgnmt.id field value | String |
status | Current status of the payment cancellation. Since Payments Hub stores all requests for a while before performing the transaction settlement, this value is returned as PENDING. | String |
Extract the value of the paymentsHubId key, as you'll need it in the next section.
Example response body:
{
"data": {
"paymentsHubId": "aa0420ae-e742-3082-ba3a-a24ebd765798",
"paymentId": "MsgId-2046908283",
"status": "PENDING",
"creationDateTime": "2022-05-30T12:45:23.089088"
}
}
3. Retrieve the payment cancellation status
This section describes how to retrieve the payment cancellation status via a camt.029 HTTP request to the Payments Hub API. To send this request, you need to provide the Payments Hub ID that you received in the response to the camt.056 HTTP request sent in the previous section, or that was provided in the notification (if you have it enabled for camt.056 requests). For information, see Notifications . This section also illustrates a successful response.
Note
The payment scheme-specific service that receives a camt.056 payment cancellation request accepts the cancellation if it has not yet processed the original payment. If the original payment has been processed already, the cancellation is rejected. The camt.029 request tells you whether the cancellation was accepted or rejected.
If the cancellation is rejected, you have to contact the beneficiary of the original payment and ask them to return the payment via a pacs.004 request. For information on pacs.004 requests, see Tutorial: Returning payments with SEPA Credit Transfer (pacs.004 and pacs.002) .
Notifications are not used in the sandbox environment.
Request
Create and send a request using the following operation:
GET https://sandbox.api.pagonxt.com/payments/camt029/v09/{paymentsHubId}
Headers
The request must contain the headers shown in the following table.
Table: Retrieve the payment cancellation status - Required request headers.
Header name | Description | Required/Optional | Values |
---|---|---|---|
Authorization | Authorization security header | Required | Bearer <Access token> |
X-Client-Id | Client ID | Required | <Client ID> |
Accept | Format of the response body | Required | application/json |
Parameters
The request must contain the path parameter shown in the following table.
Table: Retrieve the payment cancellation status - Request parameter.
Parameter type | Parameter name | Description | Data format | Required/Optional |
---|---|---|---|---|
Path | paymentsHubId | Payments Hub ID related to the payment cancellation, received in the response to the camt.056 request | String | Required |
Request example
The following example illustrates the request using raw HTTP code:
GET /payments/camt029/v09/YOUR_PAYMENTS_HUB_ID HTTP/1.1
Host: sandbox.api.pagonxt.com
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
X-Client-Id: YOUR_CLIENT_ID
Response
If the request is valid, you receive an HTTP 200 OK response, which means that the payment cancellation status was 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 rsltnOfInvstgtn JSON object, which contains a camt.029 ISO message.
The following table shows the response body elements that are relevant for the current use case. For details on all the response body elements, see Message field definition for camt.029 .
Table: Retrieve the payment cancellation status – Relevant response body elements.
Element | Description | Data type |
---|---|---|
assgnmt | Data structure containing information about the assignment of an investigation from an assigner to an assignee | Object |
sts.conf | Payment cancellation status. The possible values are based on the ISO standard. For example: ACCC (accepted) or RJTC (rejected). For more information on the status and the related codes that provide the reason for the payment acceptance or rejection, see Payment status and codes. | String |
cxlDtls | Array of the details of the transactions being cancelled | Array |
Extract the value of the sts.conf key to see the payment cancellation status. Information on the reason for the cancellation status can be found in the cxlDtls.txInfAndSts.cxlStsRsnInf object, if it is included in the response body.
Example response body:
{
"rsltnOfInvstgtn": {
"assgnmt": {
"id": "dd742f2478c4421791b255787211d38a",
"assgnr": {
"agt": {
"finInstnId": {
"bicfi": "BBVAESMMXXX"
}
}
},
"assgne": {
"agt": {
"finInstnId": {
"bicfi": "BSCHESMMXXX"
}
}
},
"creDtTm": "2022-05-30T12:45:23.126Z"
},
"sts": {
"conf": "CNCL"
},
"cxlDtls": [
{
"orgnlGrpInfAndSts": {
"orgnlMsgId": "MsgId-2046908283",
"orgnlMsgNmId": "camt.056.001.08"
},
"orgnlPmtInfAndSts": [
{
"orgnlPmtInfId": "endToEndId",
"txInfAndSts": [
{
"orgnlEndToEndId": "endToEndId"
}
]
}
],
"txInfAndSts": [
{
"cxlStsId": "TransactionId-2046908283",
"txCxlSts": "ACCR",
"cxlStsRsnInf": [
{
"addtlInf": [
null,
null,
"SCT:TransactionId-2046908283",
null
]
}
]
}
]
}
]
}
}