get-choices-for-payment.rst (5471B)
1 .. ts:op:: getChoicesForPayment 2 3 Get the list of contract choices for a payment transaction in the 4 dialog (confirmation) state, together with information on whether each 5 choice can be paid with the funds available in the wallet, and whether 6 a specific choice should be paid automatically without user 7 confirmation, based on the user's configuration or the type of payment 8 requested. 9 10 For a contract v1 order, the ``choices`` array of the result mirrors 11 the choices of the contract. For a contract v0 order, which has no 12 choices, it contains a single choice with no inputs/outputs. 13 14 **Request:** 15 16 The ``args`` must be a `GetChoicesForPaymentRequest` object. 17 18 **Response:** 19 20 On success, the result is a `GetChoicesForPaymentResult` object. 21 22 **Side effects:** 23 24 None; this operation is a pure read. The payability of each choice 25 is evaluated against the coin, exchange and token information 26 already stored in the wallet database, without any network access. 27 28 **Expected errors:** 29 30 The caller can handle the following errors inline: 31 ``WALLET_REQUEST_TRANSACTION_STATE_UNSUPPORTED``, 32 ``WALLET_TRANSACTION_NOT_FOUND``, ``WALLET_CORE_API_BAD_REQUEST``. 33 34 The ``WALLET_REQUEST_TRANSACTION_STATE_UNSUPPORTED`` error is 35 returned while the contract terms of the payment have not been 36 downloaded yet; the caller should wait for the corresponding 37 transaction state transition and try again. 38 39 .. ts:def:: GetChoicesForPaymentRequest 40 41 interface GetChoicesForPaymentRequest { 42 // Transaction identifier of the payment. 43 transactionId: string; 44 45 // Force a particular coin selection when evaluating 46 // whether the choices are payable. 47 forcedCoinSel?: ForcedCoinSel; 48 } 49 50 .. ts:def:: ForcedCoinSel 51 52 interface ForcedCoinSel { 53 coins: { 54 value: AmountString; 55 contribution: AmountString; 56 }[]; 57 } 58 59 .. ts:def:: GetChoicesForPaymentResult 60 61 type GetChoicesForPaymentResult = { 62 // Details for all choices in the contract. 63 // 64 // The index in this array corresponds to the choice 65 // index in the original contract v1. For contract v0 66 // orders, it will only contain a single choice with no 67 // inputs/outputs. 68 choices: ChoiceSelectionDetail[]; 69 70 // Index of the choice in the `choices` array to present 71 // to the user as default. 72 // 73 // Won't be set if no default selection is configured 74 // or no choice is payable; otherwise it will always 75 // be 0 for v0 orders. 76 defaultChoiceIndex?: number; 77 78 // Whether the choice referenced by `automaticExecutableIndex` 79 // should be confirmed automatically without user interaction. 80 // 81 // If true, the wallet should call `confirmPay` immediately 82 // afterwards; if false, the user should first be prompted 83 // to select and confirm a choice. Undefined when no 84 // choices are payable. 85 automaticExecution?: boolean; 86 87 // Index of the choice that would be set to automatically 88 // execute if the choice was payable. When `automaticExecution` 89 // is set to true, the payment should be confirmed with this 90 // choice index without user interaction. 91 automaticExecutableIndex?: number; 92 93 // Data extracted from the contract terms that 94 // is relevant for payment processing in the wallet. 95 contractTerms: MerchantContractTerms; 96 }; 97 98 .. ts:def:: ChoiceSelectionDetail 99 100 type ChoiceSelectionDetail = 101 | ChoiceSelectionDetailPaymentPossible 102 | ChoiceSelectionDetailInsufficientBalance; 103 104 .. ts:def:: ChoiceSelectionDetailPaymentPossible 105 106 interface ChoiceSelectionDetailPaymentPossible { 107 status: ChoiceSelectionDetailType.PaymentPossible; 108 109 // Amount requested by the contract for this choice. 110 amountRaw: AmountString; 111 112 // Total cost of this choice for the wallet, including fees. 113 amountEffective: AmountString; 114 115 // Scope of the coins that would be spent, if known. 116 scopeInfo: ScopeInfo | undefined; 117 118 tokenDetails?: PaymentTokenAvailabilityDetails; 119 } 120 121 .. ts:def:: ChoiceSelectionDetailInsufficientBalance 122 123 interface ChoiceSelectionDetailInsufficientBalance { 124 status: ChoiceSelectionDetailType.InsufficientBalance; 125 126 // Amount requested by the contract for this choice. 127 amountRaw: AmountString; 128 129 balanceDetails?: PaymentInsufficientBalanceDetails; 130 tokenDetails?: PaymentTokenAvailabilityDetails; 131 } 132 133 .. ts:def:: ChoiceSelectionDetailType 134 135 type ChoiceSelectionDetailType = 136 | "payment-possible" 137 | "insufficient-balance"; 138 139 .. ts:def:: PaymentTokenAvailabilityDetails 140 141 interface PaymentTokenAvailabilityDetails { 142 // Number of tokens requested by the merchant. 143 tokensRequested: number; 144 145 // Number of tokens available to use. 146 tokensAvailable: number; 147 148 // Legacy compatibility field. Always zero: tokens from another 149 // merchant are counted as untrusted and cannot be used. 150 tokensUnexpected: number; 151 152 // Number of tokens not issued by the receiving merchant. 153 // 154 // Cannot be used to pay, so an error should be displayed. 155 tokensUntrusted: number; 156 157 perTokenFamily: { 158 [slug: string]: { 159 causeHint?: TokenAvailabilityHint; 160 requested: number; 161 available: number; 162 unexpected: number; 163 untrusted: number; 164 }; 165 }; 166 } 167 168 .. ts:def:: TokenAvailabilityHint 169 170 type TokenAvailabilityHint = 171 | "wallet-tokens-available-insufficient" 172 | "merchant-unexpected" 173 | "merchant-untrusted";