085-transfer-status.rst (3660B)
1 DD 85: Transfer status 2 ###################### 3 4 Summary 5 ======= 6 7 We need a way to handle wire gateway incoming and outgoing transfer failures. 8 Automatically when possible with fallbacks to manual resolution. 9 10 Motivation 11 ========== 12 13 Right now when we make a deposit the wallet show confirmation before the transfer is actually made. 14 In case of failure nothing is done automatically and the user has no way to see it from it's wallet. 15 16 We already have a transfer status API in place but it's not suitable for automation as it's expose a paginated list of transfers and we need a pagniated list of transfer status changes. 17 18 I think the Wire Gateway API should expose a transfer status history endpoint and the logic for failure resolution should be done at a higher level in the exchange. 19 20 We also need an API for incoming transactions that are malformed but cannot be bounce. 21 22 Proposed Solution 23 ================= 24 25 Database 26 -------- 27 28 For each transfer we would store a list of all status it whent through. 29 30 TODO 31 32 Wire Gateway API 33 ---------------- 34 35 .. http:get:: /transfers-status 36 37 Return a list of transfers status changes. 38 39 **Request:** 40 41 :query limit: *Optional.* 42 At most return the given number of results. Negative for descending by 43 ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. 44 :query offset: *Optional.* 45 Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. 46 :query status: *Optional*. 47 Filters by status. 48 :query transfer_id: *Optional* 49 Only list statuses for a specific transfer. 50 51 **Response:** 52 53 :http:statuscode:`200 OK`: 54 JSON object of type `TransferList`. 55 :http:statuscode:`204 No content`: 56 There are no transfers statuses to report (under the given filter). 57 :http:statuscode:`400 Bad request`: 58 Request malformed. 59 :http:statuscode:`401 Unauthorized`: 60 Authentication failed, likely the credentials are wrong. 61 :http:statuscode:`404 Not found`: 62 The endpoint is wrong or the user name is unknown. 63 64 **Details:** 65 66 .. ts:def:: TransferStatusList 67 68 interface TransferStatusList { 69 // Array of transfers statuses 70 statuses: TransferListStatus[]; 71 } 72 73 .. ts:def:: TransferStatus 74 75 interface TransferStatus { 76 // Opaque ID of the status change. 77 // Is is different from the /transfers 78 row_id: SafeUint64; 79 80 // Opaque ID of the wire transfer initiation performed by the bank. 81 // It is different from the /history endpoints row_id. 82 transfer_id: SafeUint64; 83 84 // Status of the transfer at this time 85 // pending: the transfer is in progress 86 // transient_failure: the transfer has failed but may succeed later 87 // permanent_failure: the transfer has failed permanently and will never appear in the outgoing history 88 // success: the transfer has succeeded and appears in the outgoing history 89 status: "pending" | "transient_failure" | "permanent_failure" | "success"; 90 91 // Timestamp that indicates when this status was reached. 92 timestamp: Timestamp; 93 } 94 95 Exchange aggregation 96 -------------------- 97 98 I think all this information should be stored and aggregated within the exchange. Wire adapters should only contain code to abstract the underlying system internal workings, but the remediation logic should be at another level. 99 100 The exchange should read the status anyway to refund in case of failure, but if we want to add more complex rules and manual remediation, we could create another component that I could maintain if it makes life easier for Christian. 101 102 Test Plan 103 ========= 104 105 106 Alternatives 107 ============ 108 109 110 Drawbacks 111 ========= 112 113 114 Discussion / Q&A 115 ================