tops-stage-devtesting.rst (10730B)
1 Testing in the TOPS Staging Environment 2 ======================================= 3 4 This document contains a detailled, step-by-step instructions for testing 5 with the staging environment for the Taler Operations deployment. 6 7 The staging environment (on host ``rusty``) is almost equivalent to the production 8 environment. It is, however, not connected to a real bank account. 9 10 Prerequisites 11 ------------- 12 13 An administrator needs to enable your SSH key for testing 14 in the staging environment. 15 16 17 Withdrawals: Basic Withdrawal 18 ----------------------------- 19 20 1. Scan the following QR code to start a withdrawal from the `stage exchange <https://exchange.stage.taler-ops.ch/>`_: 21 22 .. image:: ./qr-withdraw-tops-stage.png 23 24 ``taler://withdraw-exchange/exchange.stage.taler-ops.ch/`` 25 26 2. Confirm the withdrawal in the wallet. 27 28 3. Run the following command to fake a wire transfer, using a randomly 29 generated creditor IBAN. The ``$AMOUNT`` and ``$SUBJECT`` should be 30 taken from the wire transfer instructions in the wallet UI. 31 32 .. code:: none 33 34 ssh -T devtesting@rusty.taler-ops.ch "fake-incoming --amount $AMOUNT --subject '$SUBJECT'" 35 36 4. Check that the withdrawal succeeded in the wallet. 37 38 39 Deposits: Basic Deposit 40 ----------------------- 41 42 1. Do a basic withdrawal. 43 2. Initiate a deposit in the wallet UI, using the receiver account known to the wallet from the withdrawal. 44 3. The deposit transaction should now ask for KYC information. Fill out the corresponding form(s). 45 4. The deposit transaction should finish. 46 47 Deposits: Deposit with KYC Auth 48 ------------------------------- 49 50 1. Do a basic withdrawal. 51 52 2. Generate an IBAN via: 53 54 .. code:: none 55 56 ssh -T devtesting@rusty.taler-ops.ch geniban 57 58 3. Initiate a deposit in the wallet UI to the randomly generated IBAN. 59 60 4. The deposit transaction should now ask for a KYC auth transfer. Satisfy the auth transfer by running: 61 62 .. code:: none 63 64 ssh -T devtesting@rusty.taler-ops.ch "fake-incoming --amount $AMOUNT --subject '$SUBJECT' --debit-payto '$DEBIT_PAYTO'" 65 66 with the information shown in the wallet UI, where the ``$DEBIT_PAYTO`` must contain the IBAN generated in step (2). 67 68 69 5. The deposit transaction should now ask for KYC information. Fill out the corresponding form(s). 70 71 6. The deposit transaction should finish. 72 73 74 75 Merchant: End-to-end onboarding (staging) 76 ----------------------------------------- 77 78 Stage-specific glue for the merchant path already described elsewhere: 79 :ref:`taler-merchant-backend-operator-manual` (SPA and HTTP API) and 80 *Merchant: Onboarding* in :doc:`tops` (bank account → KYC auth → accept 81 exchange terms of service → accept payments). Authentication is 82 documented under :ref:`merchant-api-authentication`. Wire faking 83 reuses ``geniban`` / ``fake-incoming`` from *Deposits: Deposit with KYC 84 Auth* above. 85 86 Two variants: **SPA (mostly manual)** below, then **API** (curl / 87 scripted self-provision, login tokens, and orders). 88 89 This page is written for **TOPS stage** (``$BASE`` below). Deployments 90 like **regional currencies** — overview at 91 `https://regio.taler.net/ <https://regio.taler.net/>`_, setup via 92 ``taler-deployment.git`` ``regional-currency/`` (see the :doc:`automated 93 setup<../regional/regional-automated-manual>` and :doc:`custom 94 setup<../regional/regional-custom-manual>` manuals) — can differ. 95 Look at the merchant ``/config``: if ``mandatory_tan_channels`` is 96 empty, MFA for self-provisioning is effectively off and 97 ``POST /instances`` often returns **204** (instance exists immediately, 98 no ``/challenge/…`` round-trip) — typical for many **regio** setups. 99 Creating orders still needs at least one active bank account (otherwise 100 the backend rejects with a missing-account error). Wire faking via 101 ``rusty`` / ``taler-devtesting`` is TOPS-stage specific (not the usual 102 regional-bank funding path). 103 104 Variables used below (set your own values): 105 106 .. code:: none 107 108 BASE=https://stage.my.taler-ops.ch 109 INSTANCE=my-shop # instance id (slug) 110 INSTANCE_PASSWORD=… # password chosen at signup 111 EMAIL=you@example.com # inbox that can receive stage TAN mail 112 PHONE=+41 7x xxx xx xx # real CH mobile; must match phone_regex 113 # from $BASE/config *and* be accepted by 114 # the SMS helper (dummy numbers fail with 115 # TALER_EC 2132 on /challenge/$ID) 116 IBAN=… # from geniban 117 DEBIT_PAYTO=payto://iban/$IBAN 118 TOKEN=… # access_token from /private/token 119 ORDER_ID=… # from PostOrderResponse 120 121 ``$BASE/`` redirects to ``$BASE/webui/``. Use the 122 `stage exchange <https://exchange.stage.taler-ops.ch/>`_ for payments. 123 Check ``have_self_provisioning`` and ``mandatory_tan_channels`` on 124 ``$BASE/config``. 125 126 Shared bank / KYC steps 127 ^^^^^^^^^^^^^^^^^^^^^^^ 128 129 1. Generate an IBAN for the merchant bank account: 130 131 .. code:: none 132 133 IBAN=$(ssh -T devtesting@rusty.taler-ops.ch geniban) 134 DEBIT_PAYTO="payto://iban/$IBAN" 135 136 2. Register that IBAN on the instance (:ref:`instance-account-setup`) — 137 in the portal under **Bank account**, or via API after you have a 138 ``$TOKEN``: 139 140 .. code:: none 141 142 curl -sS \ 143 -H "Authorization: Bearer $TOKEN" \ 144 -H 'Content-Type: application/json' \ 145 -d "{\"payto_uri\":\"$DEBIT_PAYTO\"}" \ 146 "$BASE/instances/$INSTANCE/private/accounts" 147 148 Skip revenue-API credentials unless an administrator provided stage 149 ones. 150 151 3. When the exchange requires the KYC auth transfer (*Merchant: 152 Onboarding* in :doc:`tops`), satisfy it like *Deposits: Deposit with 153 KYC Auth*. Take ``$AMOUNT`` and ``$SUBJECT`` from the KYC UI: 154 155 .. code:: none 156 157 ssh -T devtesting@rusty.taler-ops.ch \ 158 "fake-incoming --amount $AMOUNT --subject '$SUBJECT' --debit-payto '$DEBIT_PAYTO'" 159 160 4. If the deposit limit is still zero, accept the TOPS exchange terms 161 of service on the exchange KYC page (*Merchant: Onboarding* in 162 :doc:`tops`). For stuck account validation, see 163 :doc:`tops-troubleshooting`. 164 165 5. Fund a wallet via *Withdrawals: Basic Withdrawal* above, then pay 166 the order (*Paying an order* in the merchant manual). 167 168 SPA (login with password) 169 ^^^^^^^^^^^^^^^^^^^^^^^^^ 170 171 Normal interactive path (:ref:`Instance-setup`, *Self-provisioning*, 172 *Manually creating an order using the SPA*). 173 174 1. Open ``$BASE/webui/``. **Sign up** or **log in** with ``$INSTANCE`` 175 and ``$INSTANCE_PASSWORD``. Confirm e-mail and SMS TAN when asked 176 (both channels are mandatory on this backend). 177 178 2. Complete *Shared bank / KYC steps* in the portal (**Bank account**, 179 KYC links). 180 181 3. **Orders** → create (summary + amount). Keep the payment QR / pay 182 link from the order status page. 183 184 4. Pay from the wallet (shared step 5) and confirm paid status in the 185 SPA. 186 187 API (self-provision → password → login token → Bearer) 188 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 189 190 Same backend via HTTP 191 (:http:post:`/instances`, :ref:`merchant-api-authentication`, 192 :http:post:`[/instances/$INSTANCE]/private/token`, 193 :http:post:`[/instances/$INSTANCE]/private/orders`). 194 Private endpoints need 195 ``Authorization: Bearer secret-token:…`` (RFC 8959). 196 197 On this stage backend, expect the MFA path below (``mandatory_tan_channels`` 198 is ``email`` and ``sms``). Where that list is empty, skip to step 3 after a 199 **204** create. 200 201 1. Self-provision (:http:post:`/instances`). Example body 202 (`InstanceConfigurationRequest`; ``auth.method`` = ``token``): 203 204 .. code:: none 205 206 curl -sS -H 'Content-Type: application/json' \ 207 -d "{ 208 \"id\": \"$INSTANCE\", 209 \"name\": \"Example Shop\", 210 \"email\": \"$EMAIL\", 211 \"phone_number\": \"$PHONE\", 212 \"auth\": {\"method\": \"token\", \"password\": \"$INSTANCE_PASSWORD\"}, 213 \"address\": {\"country\": \"CH\"}, 214 \"jurisdiction\": {\"country\": \"CH\"}, 215 \"use_stefan\": true 216 }" \ 217 "$BASE/instances" 218 219 Typical response before MFA: **HTTP 202** `ChallengeResponse` with 220 ``combi_and: true`` and one challenge per TAN channel, e.g.: 221 222 .. code:: none 223 224 { 225 "combi_and": true, 226 "challenges": [ 227 {"tan_channel": "email", "tan_info": "…", "challenge_id": "$CHALLENGE_EMAIL"}, 228 {"tan_channel": "sms", "tan_info": "…", "challenge_id": "$CHALLENGE_SMS"} 229 ] 230 } 231 232 Until both TANs are solved, ``$INSTANCE`` does **not** exist 233 (``/instances/$INSTANCE/private/…`` → **404**). 234 235 2. Request and confirm each TAN on the **unprefixed** challenge URLs 236 (instance path segment optional; before create, only this form 237 works — see *Solving challenges* in the merchant API): 238 239 .. code:: none 240 241 curl -sS -H 'Content-Type: application/json' -d '{}' \ 242 "$BASE/challenge/$CHALLENGE_ID" 243 curl -sS -H 'Content-Type: application/json' \ 244 -d "{\"tan\":\"$TAN\"}" \ 245 "$BASE/challenge/$CHALLENGE_ID/confirm" 246 247 Repeat for every ``challenge_id``. A successful request returns 248 **200**; a rejected SMS/e-mail address returns **400** with code 249 **2132** (fix ``$PHONE`` / ``$EMAIL``). Wrong ``$TAN`` on confirm 250 returns **409**. 251 252 Retry the **same** ``POST $BASE/instances`` body with: 253 254 .. code:: none 255 256 -H "Taler-Challenge-Ids: $CHALLENGE_EMAIL,$CHALLENGE_SMS" 257 258 Expect **200** / **204** when the instance is created. With 259 unsolved challenges the retry stays at **202**. 260 261 3. Password → login token (Basic: user ``$INSTANCE``, password 262 ``$INSTANCE_PASSWORD``; `LoginTokenRequest`): 263 264 .. code:: none 265 266 curl -sS -u "$INSTANCE:$INSTANCE_PASSWORD" \ 267 -H 'Content-Type: application/json' \ 268 -d '{"scope":"order-simple"}' \ 269 "$BASE/instances/$INSTANCE/private/token" 270 271 From `LoginTokenSuccessResponse`, set ``TOKEN`` to ``access_token`` 272 (already includes the ``secret-token:`` prefix). Scopes such as 273 ``spa`` or ``all`` work the same way if you need broader rights. 274 275 4. Create an order with the Bearer token: 276 277 .. code:: none 278 279 curl -sS \ 280 -H "Authorization: Bearer $TOKEN" \ 281 -H 'Content-Type: application/json' \ 282 -d '{"order":{"summary":"stage test","amount":"CHF:1"}}' \ 283 "$BASE/instances/$INSTANCE/private/orders" 284 285 5. Read ``order_id`` from `PostOrderResponse`. Fetch ``taler_pay_uri`` 286 via :http:get:`[/instances/$INSTANCE]/private/orders/$ORDER_ID` 287 (or the public order status URL). Finish *Shared bank / KYC steps* 288 if needed, then pay from the wallet. 289 290 .. note:: 291 292 Prefer login tokens from ``/private/token``. Long-lived 293 ``Authorization: Bearer secret-token:$INSTANCE_PASSWORD`` is the 294 deprecated ``token`` method and will be phased out.