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.
POST /api/v2/Payment/Transactions/PCI_ZHZAJ2FD31H73WDW7M1KMMWSM278VW/cancel HTTP/1.1Host: connect-testing.secupay-ag.deAuthorization: Bearer qb56tjj1bcvo9n2nj4u38k84loContent-Type: application/jsonAccept: application/json{ "reduce_amount_by": 995, "reason": "One piece less"}These are the parameters:
|
Parameter |
Type |
Explanation |
|
reduce_amount_by |
int |
Optional amount in the smallest currency unit, e. g. Euro Cents. When called without an amount, the transaction will be cancelled in full or the entire remaining amount will be refunded. |
|
amount |
int |
DEPRECATED Replaced by reduce_amount_by. Optional amount in the smallest currency unit, e. g. Euro Cents. When called without an amount, the transaction will be cancelled in full or the entire remaining amount will be refunded. Note: The meaning of this field differs depending on the payment method!
|
|
reason |
string |
Optional reason. Appears as part of the purpose line in the bank statements, if the refund is made by bank transfer. Allowed are up to 100 characters of A-Z, a-z, 0-9, space and these special characters: .,+-:?()/' Regex: /^[A-Za-z0-9 .,+\-:?()\/'] {0,100}$/ |
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:
HTTP/1.1 200 OKContent-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:
HTTP/1.1 200 OKContent-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:
HTTP/1.1 200 OKContent-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.