get-kyc-proof-PROVIDER_NAME.rst (3963B)
1 .. http:get:: /kyc-proof/$PROVIDER_NAME?state=$H_NORMALIZED_PAYTO 2 3 Upon completion of the process at the external KYC provider, the provider 4 must redirect the client (browser) to trigger a GET request to a new 5 ``/kyc-proof/$H_NORMALIZED_PAYTO/$PROVIDER_NAME`` endpoint. Once this endpoint is 6 triggered, the exchange will pass the received arguments to the respective 7 logic plugin. The logic plugin will then (asynchronously) update the KYC 8 status of the user. The logic plugin should redirect the user to the KYC 9 SPA. This endpoint deliberately does not use the ``$ACCESS_TOKEN`` as the 10 external KYC provider should not learn that token. 11 12 This endpoint is thus accessed from the user's browser at the *end* of a 13 KYC process, possibly providing the exchange with additional 14 credentials to obtain the results of the KYC process. 15 Specifically, the URL arguments should provide 16 information to the exchange that allows it to verify that the 17 user has completed the KYC process. The details depend on 18 the logic, which is selected by the "$PROVIDER_NAME". 19 20 While this is a GET (and thus safe, and idempotent), the operation 21 may actually trigger significant changes in the exchange's state. 22 In particular, it may update the KYC status of a particular 23 payment target. 24 25 **Request:** 26 27 Details on the request depend on the specific KYC logic 28 that was used. 29 30 If the KYC plugin logic is OAuth 2.0, the query parameters are: 31 32 :query code=CODE: 33 OAuth 2.0 code argument. 34 :query state=STATE: 35 OAuth 2.0 state argument, as issued by the exchange in the 36 authorization request: the H_NORMALIZED_PAYTO, a ``-`` and a tag 37 binding the state to the KYC process. Requests whose state does 38 not match the currently running KYC process are refused without 39 changing the process, whether they carry a ``code`` or an ``error``. 40 41 .. note:: 42 43 Depending on the OAuth variant used, additional 44 query parameters may need to be passed here. 45 46 **Response:** 47 48 Given that the response is returned to a user using a browser and **not** to 49 a Taler wallet, the response format is in human-readable HTML and not in 50 machine-readable JSON. 51 52 :http:statuscode:`200 OK`: 53 The KYC process was not required. The response may contain 54 status information. 55 :http:statuscode:`302 Found`: 56 The KYC operation succeeded and the 57 payment target is now authorized to transact. 58 The browser is redirected to a human-readable 59 page configured by the exchange operator. 60 :http:statuscode:`400 Bad Request`: 61 A query parameter is malformed. 62 This response comes with a standard `ErrorDetail` response with 63 a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. 64 :http:statuscode:`401 Unauthorized`: 65 The provided authorization token is invalid. 66 :http:statuscode:`403 Forbidden`: 67 The KYC process failed, or, with the OAuth 2.0 logic, the 68 ``state`` was not issued for the running KYC process. In the 69 latter case the KYC process remains unchanged and the response 70 comes with a code of ``TALER_EC_GENERIC_FORBIDDEN``. 71 :http:statuscode:`404 Not found`: 72 The payment target is unknown. 73 This response comes with a standard `ErrorDetail` response with 74 a code of ``TALER_EC_EXCHANGE_KYC_GENERIC_LOGIC_UNKNOWN`` or 75 ``TALER_EC_EXCHANGE_KYC_PROOF_REQUEST_UNKNOWN``. 76 :http:statuscode:`500 Internal Server Error`: 77 The exchange encountered an internal error processing the request. 78 This response comes with a standard `ErrorDetail` response with 79 a code of ``TALER_EC_GENERIC_DB_FETCH_FAILED``, 80 ``TALER_EC_GENERIC_DB_STORE_FAILED``, or 81 ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``. 82 :http:statuscode:`502 Bad Gateway`: 83 The exchange received an invalid reply from the 84 legitimization service. 85 :http:statuscode:`504 Gateway Timeout`: 86 The exchange did not receive a reply from the legitimization 87 service within a reasonable time period.