Cancel or Refund a Payment

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.

Credit card transactions can be lowered exactly one time (partial cancellation), and only as long as they have status 9, "authorized". When an "authorized" credit card transaction is cancelled fully, the reservation is released, and thus the card limit restored.

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 in the smallest currency unit, e. g. Euro Cents.

You can call this endpoint once per transaction without amount for a full cancellation or refund. After you have called it with an amount for partial cancellation or refund, you must also pass an amount in the subsequent calls.

Note: The meaning of this field differs depending on the payment method!

  • For invoice payment, you must pass the remaining amount.

  • For other payment methods, you must pass the reduction.

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.