post-private-orders-ORDER_ID-refund-external.rst (5156B)
1 .. http:post:: [/instances/$INSTANCE]/private/orders/$ORDER_ID/refund-external 2 3 Record a refund that was settled outside of Taler, for example a cash or 4 card return. Unlike Taler refunds, this is a bookkeeping entry only: the 5 point-of-sale or external payment integration performs the actual return of 6 funds, and no wallet pickup step exists or is needed. The recorded entries 7 are exposed through the order status as ``refunds_external``. 8 9 External refunds are available for any *paid* order, including pure Taler 10 orders without ``amount_external``. This is relevant because Taler refunds 11 are constrained by the contract's refund deadline; once it has passed, the 12 amount can only be returned through an external method, which is recorded 13 here. 14 15 The refund channel does not need to match the payment channel. The backend 16 validates external refunds against the order total: the cumulative 17 externally refunded amount must not exceed the full order total (the Taler 18 ``amount`` plus all ``amount_external`` entries) minus the amount already 19 refunded through Taler, and must use the currency of the order. 20 21 Each external refund is identified by an ``id`` chosen by the merchant and 22 unique within the order. Recording a refund under an ``id`` that already 23 exists is *idempotent* if the request body is identical, which makes it safe 24 for a point-of-sale application to retry after a network failure without 25 consuming the refundable amount twice. Reusing an existing ``id`` with a 26 different body is refused as a conflict. 27 28 The identifier is mandatory: a recorded external refund cannot be removed, 29 so a duplicate would permanently consume part of the amount that may still 30 be refunded for the order. 31 32 **Required permission:** ``orders-refund`` 33 34 Since protocol **vMixedPayments**. 35 36 **Request:** 37 38 The request body is an `ExternalRefundRequest` object. 39 40 **Response:** 41 42 :http:statuscode:`200 OK`: 43 The external refund was recorded, or had already been recorded with 44 an identical request body. The response is an 45 `ExternalRefundResponse` object containing the identifier of the 46 refund. 47 :http:statuscode:`400 Bad Request`: 48 The request body is malformed, for example the ``method`` is empty, 49 is ``taler``, contains non-ASCII characters, or the ``id`` is empty. 50 Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. 51 :http:statuscode:`401 Unauthorized`: 52 The request is unauthorized. 53 :http:statuscode:`404 Not found`: 54 The order is unknown to the merchant. 55 Returned with ``TALER_EC_MERCHANT_GENERIC_ORDER_UNKNOWN``. 56 :http:statuscode:`409 Conflict`: 57 The external refund could not be recorded. 58 Returned with 59 ``TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_REFUND_ORDER_UNPAID`` 60 if the order is not paid, 61 ``TALER_EC_MERCHANT_GENERIC_CURRENCY_MISMATCH`` 62 if the refund uses a different currency than the order, or 63 ``TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_REFUND_EXTERNAL_INCONSISTENT_AMOUNT`` 64 if the cumulative external refunds would exceed the order total minus 65 the amount already refunded through Taler, or 66 ``TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_REFUND_EXTERNAL_ALREADY_EXISTS`` 67 if an external refund with the same ``id`` was already recorded for 68 this order with different details. 69 :http:statuscode:`500 Internal Server Error`: 70 The server experienced an internal failure. 71 Returned with ``TALER_EC_GENERIC_DB_START_FAILED``, 72 ``TALER_EC_GENERIC_DB_FETCH_FAILED``, 73 ``TALER_EC_GENERIC_DB_STORE_FAILED``, 74 ``TALER_EC_GENERIC_DB_COMMIT_FAILED``, 75 ``TALER_EC_GENERIC_DB_SOFT_FAILURE``, 76 ``TALER_EC_GENERIC_FAILED_COMPUTE_JSON_HASH`` or 77 ``TALER_EC_MERCHANT_GENERIC_DB_CONTRACT_CONTENT_INVALID``. 78 79 **Details:** 80 81 .. ts:def:: ExternalRefundRequest 82 83 interface ExternalRefundRequest { 84 // Method by which the funds were returned to the customer, 85 // for example "cash" or "card". May differ from the methods used 86 // to pay the order. Must be a stable, non-empty ASCII identifier 87 // and must never be "taler". 88 method: string; 89 90 // Identifier of this refund within the order, chosen by the 91 // merchant. Must be non-empty. Re-using an identifier with an 92 // identical request body is idempotent; re-using it with 93 // different details is a conflict. 94 id: string; 95 96 // Optionally, the ``id`` of the ``amount_external`` entry this 97 // refund reverses, when the refund maps to a specific original 98 // payment (for example a card transaction reversal). 99 payment_id?: string; 100 101 // Amount returned to the customer via the external method. 102 // Must use the currency of the order. 103 amount: Amount; 104 105 // Human-readable refund justification, mirroring Taler refunds. 106 reason: string; 107 } 108 109 .. ts:def:: ExternalRefundResponse 110 111 interface ExternalRefundResponse { 112 // Identifier of the recorded external refund within the order, 113 // either the one given in the request or the one assigned by the 114 // backend. Can be used to reference the refund later. 115 refund_id: string; 116 }