Cancel or Refund a Payment Transaction

As long as the payment is not executed yet, the amount is reduced or the transaction is cancelled fully. After the payment is executed, it must be refunded (paid back). Therefore, refund transactions are created each time the endpoint is called. The refund transactions are linked to the original payment. A refund may also fail. In no way you can cancel or refund more than the original amount, even in combination.

The endpoint to cancel or refund a Payment Transaction fully or partially is POST /api/v2/Payment/Transactions/{id}/cancel.

Request
POST /api/v2/Payment/Transactions/PCI_ZHZAJ2FD31H73WDW7M1KMMWSM278VW/cancel HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
"amount": 995,
"reason": "One piece less"
}

These are the parameters:

Parameter

Type

Explanation

amount

int

Optional amount:

  • invoice payment: remaining amount

  • other payment methods: decrease

Monetary amounts are expressed in the smallest currency unit (e. g. Euro Cent).

You can call this endpoint one time without amount to achieve a full cancellation or refund. When you have called it once with amount for a transaction, you must also pass an amount in the subsequent calls. .

reason

string

Optional reason. Appears as part of the purpose line in the bank statements, if the refund is made by bank transfer.

If everything is fine, the API responds with 200 OK, and the Payment Transactions. The original transaction may be accompanied by a resulting refund transaction. In case of a cancellation there is no refund transaction.

Example with partial cancellation:

Response
HTTP/1.1 200 OK
Content-Type: application/json
...
 
[
   {
"object": "payment.transactions",
"id": "PCI_QG4KQVERGJWPG3UXDU6NQZ5400XANJ",
// ...
"related_transactions": [],
// ...
"amount": 3990,
"currency": "EUR",
// ...
"status": 25,
"status_text": "Vorkasse wartend",
"details": {
"cleared": "open",
"status": 25,
"status_text": "Vorkasse wartend",
"status_simple": 10,
"status_simple_text": "pending",
"amount": 3990,
// ...
},
// ...
}
]

Example with full cancellation:

Response
HTTP/1.1 200 OK
Content-Type: application/json
...
 
[
{
"object": "payment.transactions",
"id": "PCI_6B9CTH3V7FC6Y9HSVA24YG5400XANZ",
// ...
"related_transactions": [],
// ...
"amount": 5985,
"currency": "EUR",
"created": "2022-04-07T17:38:50+02:00",
"completion_date": null,
"updated": "2022-04-07T17:41:02+02:00",
"description": "Bestellung am 07.04.2022 via secupay bei Secupay Test-Shop (264748)",
"description_raw": "Bestellung am 07.04.2022 via secupay bei Secupay Test-Shop (264748)",
"status": 10,
"status_text": "Storniert",
"details": {
"cleared": "open",
"status": 10,
"status_text": "Storniert",
"status_simple": 5,
"status_simple_text": "void",
"amount": 5985,
// ...
},
// ...
}
]

Example with partial refund:

Response
HTTP/1.1 200 OK
Content-Type: application/json
...
 
[
{
"object": "payment.transactions",
"id": "PCI_GUZH7U8WH00WHRS0JT4EPG5400XANY",
// ...
"related_transactions": [
{
"object": "payment.transactions",
"id": "PCI_J7GVETFVRCMZU3WD975ZGV5400XANM",
"hierarchy": "child",
"ref_type_id": 19,
"ref_type_raw": "Gutschrift / Refund",
"trans_id": 48006156
}
],
// ...
"amount": 5985,
"currency": "EUR",
// ...
"status": 6,
"status_text": "abgeschlossen",
"details": {
"cleared": "open",
"status": 6,
"status_text": "abgeschlossen",
"status_simple": 1,
"status_simple_text": "accepted",
"amount": 5985,
// ...
},
// ...
},
{
"object": "payment.transactions",
"id": "PCI_J7GVETFVRCMZU3WD975ZGV5400XANM",
// ...
"related_transactions": [
{
"object": "payment.transactions",
"id": "PCI_GUZH7U8WH00WHRS0JT4EPG5400XANY",
"hierarchy": "parent",
"ref_type_id": 19,
"ref_type_raw": "Gutschrift / Refund",
"trans_id": 48006155
}
],
// ...
"product_id": 479,
"product": "Erstattung",
"product_raw": "Erstattung",
// ...
"amount": -1995,
"currency": "EUR",
// ...
"description": "TA-Code 48006155 (07.04.22)|Refund TA-Code 48006156 Teilerstattung|One piece less",
"description_raw": "TA-Code 48006155 (07.04.22)|Refund TA-Code 48006156 Teilerstattung|One piece less",
"status": 118,
"status_text": "auf Genehmigung wartend",
"details": {
"cleared": "open",
"status": 118,
"status_text": "auf Genehmigung wartend",
"status_simple": 10,
"status_simple_text": "pending",
"amount": -1995,
"description": "TA-Code 48006155 (07.04.22)|Refund TA-Code 48006156 Teilerstattung|One piece less",
"description_raw": "TA-Code 48006155 (07.04.22)|Refund TA-Code 48006156 Teilerstattung|One piece less"
},
// ...
}
]

As you can see, the refund may still wait for its final execution. A refund may also fail.