Server2Server API
=================

API docs: `api.mobilum.com <https://api.mobilum.com/index.html#operations-tag-Server2ServerApi>`_

Authentication: :ref:`api_authentication_hmac`

Registration
------------

.. uml::
    :align: center

    skinparam monochrome true

    participant User
    participant App
    participant API
    participant KYC as "KYC provider"

    ==Registration==

    User -> App : Enter data
    App -> API : POST /s2s/users \n //User's data//
    API --> App : //id, required registration consents//

    alt User has unsigned consents
        App --> User : List of consents
        User -> App : Sign consents
        loop for each consent
            App -> API : POST /s2s/users/{userId}/consents/{consentId}/sign
        end
    end

    note over API: Registration completed

    ==User data==

    User -> App : Get user's data
    App -> API : GET /s2s/users/{userId}
    API --> App : //User's data//
    App --> User : //User's data//

Issuing card
------------

.. uml::
    :align: center

    skinparam monochrome true

    participant User
    participant App
    participant API

    ==Create card==

    User -> App : Claim new card
    App -> API : GET /s2s/users/{userId}/cards/configs
    API --> App : //card configs, required card's consents, KYC URL//

    alt User has not verified e-mail
        App --> API: POST /s2s/users/{userId}/email/otp
        API --> User: //verification code//
        User -> App : Enter verification code
        App --> API : POST /s2s/users/{userId}/email/confirm
    end

    alt User has not passed KYC
        App --> User : KYC URL
        User -> User : KYC + SMS verification \n //KYC provider//
    end

    alt User has unsigned consents
        App --> User : List of consents
        User -> App : Sign consents
        loop for each consent
            App -> API : POST /s2s/users/{userId}/consents/{consentId}/sign
        end
    end

    User -> App : Select card type
    App -> API : POST /s2s/users/{userId}/cards \n //configId, visualId//
    API --> App : //card or draft data//

    alt Payment needed
        User -> User : Top up balance

        User -> App : Pay for card
        App -> API : POST /s2s/cards/{cardId}/charge-draft
        API --> App : //draft data//

        User -> App : Issue card
        App -> API : POST /s2s/cards/{cardId}/complete-draft
        API --> App : //card or draft data//
    end

    alt Activation needed
        note over App: For physical cards only
        User -> User : Wait for order completed
        User -> App : Activate card
        App -> API : POST /s2s/cards/{cardId}/activation
        API --> App : //card data//
    end

    ==Get card data==

    User -> App : Get user's balances
    App -> API : GET /s2s/balances \n //userId//
    API --> App : //list of balances//
    App --> User : //list of balances//

    User -> App : Get user cards
    App -> API : GET /s2s/cards \n //userId//
    API --> App : //list of cards//
    App --> User : //list of cards//

    User -> App : Get card's details \n //public key//
    App -> API : GET /s2s/cards/{cardId}/details \n //cardId, public key//
    API --> App : //encrypted card's details//
    App --> User : //encrypted card's details//

Deposits
--------

.. uml::
    :align: center

    skinparam monochrome true

    participant User
    participant App
    participant API

    ==Claim deposit address==

    User -> App : Show deposit methods
    App -> API : GET /s2s/deposits/{balanceId}/types
    return //types of deposits//

    User -> App : Select deposit method

    alt User has unsigned consents
        App --> User : List of consents
        User -> App : Sign consents
        loop for each consent
            App -> API : POST /s2s/users/{userId}/consents/{consentId}/sign
        end
    end

    App -> API : GET /s2s/deposits/{balanceId}/{type} \n
    return //list of addresses//
    User -> App : Select deposit options

    alt Address not generated

        App -> API : POST /s2s/deposits/{balanceId}/{type} \n //deposit options//
        API --> App : //address data//

    end

    App --> User : Show deposit address

    ==Deposit crypto==

    User -> User: Deposit crypto
    App -> API : GET /s2s/deposits/verifications
    API -> App : //list of verifications//

    alt Verification needed

        User -> App : Verify deposit \n //verification data//
        App -> API : POST /s2s/deposits/verifications/{id}/approval \n //verification data//

    end

    API -> API : Credit balance