Getting payment cancellation details (camt.056)

API Docs

Swagger file

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 for 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.

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.

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

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. Retrieve the payment cancellation details

This section describes how to retrieve the payment cancellation details via a camt.056 HTTP request to the Payments Hub API. To send this request, you need to provide the Payments Hub ID. This section also illustrates a successful response.

Request

Create and send a request using the following operation:

GET https://sandbox.api.pagonxt.com/payments/camt056/v08/{paymentsHubId}

Headers

The request must contain the headers shown in the following table.

Table: Retrieve payment cancellation details – Required request headers.

Parameters

The request must contain the path parameter shown in the following table.

Table: Retrieve payment cancellation details – Request parameter.

Request example

The following example illustrates the request using raw HTTP code:

GET /payments/camt056/v08/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 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.

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