.. _mobile_device_transfer:

Mobile Device Transfer
======================

.. toctree::
    :maxdepth: 1

.. contents::
    :local:

.. role:: ex

.. role:: code

Introduction
------------

| Mobile device transfer can be performed with cardholder data of sender and receiver of funds or with card reference, previously made with :ref:`card verification<mobile_device_card_verification>` process or in previous transfer/sale transactions.
|
| See terms definitions in :ref:`Glossary<glossary>`.

Transfer Flow
-------------

.. uml::
    :align: center

    @startuml
    autonumber
    title Mobile Device - 3-D Secure card funds transfer
    skinparam ParticipantPadding 70
    participant "Consumer" as client
    participant "Mobile App" as mobile
    participant "Connecting Party's Server" as party
    participant "Payneteasy" as company
    client <-> mobile: Authentication
    mobile -> party: Request access token
    mobile <-- party: Response access token
    note right
    accessToken
    end note
    mobile -> party: Initiate transfer request
    mobile <-- party: Initiate transfer response
    mobile -> company: Perform transfer request
    mobile <-- company: Perform transfer response
    note right
    session token
    end note
    party <- company : Check transfer request
    party --> company : Check transfer response
    company -> company: Start processing
    mobile -> company: Transfer status request
    note left
    session token
    end note
    mobile <-- company: Transfer status response
    note right
    state = REDIRECT_REQUEST
    end note
    mobile -> mobile: Open browser and provide \nredirectUrl to redirect to 3DS page
    activate mobile
    client <-- mobile: Provide redirectUrl
    client -> mobile: The cardholder provides auth data
    mobile -> company: Transfer status update
    company --> mobile: Close browser request
    destroy mobile
    company -> company: Process transfer
	party <- company: Transfer card mapping notification request
    note right
    server card id
    end note
	party --> company: Transfer card mapping notification response
    mobile -> company: Transfer status request
    note left
    session token
    end note
    mobile <-- company: Transfer status response
    note right
    bankorder id
    state = APPROVED|DECLINED
    end note
    party <- company: Callback with final status request
    party --> company: Callback with final status response
    @enduml

| (1,2,3) To perform authentication of Consumer in Connecting Party’s app, Connecting Party can use any method which fits best to their needs. As a result, Connecting Party’s server generates :ex:`{accessToken}` and provides it to Connecting Party’s app. This parameter will be used to start and continue session.
| (4,5) To initiate funds transfer, Connecting Party’s app sends :ex:`{accessToken}` with transaction amount and other device parameters to Connecting Party’s server, which are used to start a session with unique random :ex:`{nonce}` and encrypted :ex:`{signature}`. To initiate transfer request see :ref:`Initiate Transfer<api_initiate_transfer>`.
| (6,7) On this stage Connecting Party’s app sends cardholder, device, session data and other parameters straight to Payneteasy to perform funds transfer from card to card. To implement perform transfer request see :ref:`Perform Transfer<api_perform_transfer>`.
| (8,9) Check transfer is used for security purposes and allows Payneteasy to compare the data sent by Connecting Party’s app with the data stored on Connecting Party’s server. To implement check transfer request see :ref:`Check Transfer<api_check_transfer>`.
| (11,12,21,22) Funds transfer status request is made by Connecting Party’s app to Payneteasy to get the status of transfer transaction. To implement transfer status request see :ref:`Status Transfer<api_transfer_status>`.
| (19,20) Payneteasy sends Transfer card mapping notification request to Connecting Party’s server/proxy with created on its side card reference - :ex:`{serverCardId}`. To implement transfer card mapping notification request see :ref:`Transfer card mapping notification<api_transfer_card_mapping_notification>`.
| (23,24) Connecting Party specified a callback URL, Payment Gateway sends message to the callback URL whenever transaction reaches final status, no matter if the result is :ex:`approved`, :ex:`declined` or other :ref:`final status<status_list>`. See more :ref:`Callbacks<merchant_callbacks>`.

.. _transfer-repeat:

Repeat Transfer Flow
--------------------

| After successful Card mapping procedure, new transfers with the same cardholder data can be done easier for Consumer.
| Connecting Party's app makes new transfer requests using :ex:`{clientCardId}` instead of source and/or destination cardholder data. Payneteasy sends these :ex:`{clientCardId}` to Connecting Party's server in "Check transfer request" and gets mapped to it :ex:`{serverCardId}` in "Check transfer response" from Connecting Party's server. These :ex:`{serverCardId}` are used to continue the processing of transfer transaction.
| Transaction flow remains the same: :ref:`Initiate Transfer<api_initiate_transfer>` -> :ref:`Perform Transfer<api_perform_transfer>` -> :ref:`Check Transfer<api_check_transfer>`.
| If there is no need to change Consumer's data (such as address, phone, etc.), "Perform transfer request" for Repeat transfer may be sent without any optional parameters and with card references for sender and receiver instead of cardholder data. If Consumer's data has to be changed, new source card reference must be created.
| If source and/or destination :ex:`{clientCardId}` are used in "Perform transfer request", source and/or destination :ex:`{serverCardId}` must be included in "Transfer check response" and signature.
| If source :ex:`{clientCardId}` was mapped to :ex:`{serverCardId}` in transaction with included :ex:`{consumer.email}` value, new "Perform transfer request" and "Check signature response" with this :ex:`{clientCardId}` must also contain the same :ex:`{consumer.email}` value.
|
|  For Repeat Transfer Flow use the following source of funds parameters in Perform Transfer request:
|

#. :ex:`{sourceOfFunds.reference.clientCardId}`
#. :ex:`{sourceOfFunds.reference.securityCode}`

| Instead of:
|

#. :ex:`{sourceOfFunds.card.expiry.month}`
#. :ex:`{sourceOfFunds.card.expiry.year}`
#. :ex:`{sourceOfFunds.card.holder}`
#. :ex:`{sourceOfFunds.card.holder.firstName}`
#. :ex:`{sourceOfFunds.card.holder.lastName}`
#. :ex:`{sourceOfFunds.card.number}`
#. :ex:`{sourceOfFunds.card.securityCode}`

| For destination of funds use :ex:`{destinationOfFunds.reference.clientCardId}` instead of :ex:`{destinationOfFunds.card.number}`.

.. uml::
    :align: center

    @startuml
    autonumber
    title Mobile Device - Card references for Repeat transfer
    participant "Mobile App" as mobile
    participant "Connecting Party's Server" as party
    participant "Payneteasy" as company
    skinparam ParticipantPadding 80
    == Last part of card verification or transfer ==
    party <- company: Card mapping notification request
    note right
    serverCardId
    end note
    party --> company: Card mapping notification response
    party --> party: Create clientCardId for serverCardId
    party -> mobile: Store reference in app or send it by request
    note right
    clientCardId
    end note
    == New transfer ==
    mobile -> party: Initiate transfer request
    mobile <-- party: Initiate transfer response
    mobile -> company: Perform transfer request
    note left
    clientCardId
    end note
    mobile <-- company: Perform transfer response
    party <- company: Check transfer request
    note right
    clientCardId
    end note
    party --> company: Check transfer response
    note left
    serverCardId
    end note
    company -> company: Process transfer
    @enduml

| (1,2) Payneteasy sends Transfer card mapping notification request to Connecting Party’s server/proxy with created on its side card reference - :ex:`{serverCardId}`. To implement transfer card mapping notification request see :ref:`Transfer card mapping notification<api_transfer_card_mapping_notification>`.
| (5,6) To initiate funds transfer, Connecting Party’s app sends :ex:`{accessToken}` with transaction amount and other device parameters to Connecting Party’s server, which are used to start a session with unique random :ex:`{nonce}` and encrypted :ex:`{signature}`. To initiate transfer transfer request see :ref:`Initiate Transfer<api_initiate_transfer>`.
| (7,8) On this stage Connecting Party’s app sends cardholder, device, session data and other parameters straight to Payneteasy to perform funds transfer from card to card. To implement perform transfer request see :ref:`Perform Transfer<api_perform_transfer>`.
| (9,10) Check transfer is used for security purposes and allows Payneteasy to compare the data sent by Connecting Party’s app with the data stored on Connecting Party’s server. To implement check transfer request see :ref:`Check Transfer<api_check_transfer>`.
|

Consumer Defined Transfer Rates Flow
------------------------------------

| Consumer defined transfer rates is an optional feature which allows the sender to choose the most suitable commission amount for his transfer transaction between several available payment provider gates.
| The possibility of such feature depends on the integration. Please ask support manager for details.

| When such feature is enabled, the Transfer Flow extends:

#. If Check transfer has been successful, Payneteasy pauses the processing, includes the list of possible commissions to next Transfer status response and awaits for confirmation from the Consumer.
#. Consumer selects the most suitable commission from the list in the Connecting Party's app.
#. Connecting Party's app sends the selected gate (using its :code:`assignedId` aliased name) in Complete transfer request to Payneteasy.
#. Payneteasy continues to process the transaction on the selected gate.


.. uml::
    :align: center

    @startuml
    autonumber
    title Consumer defined transfer rates
    participant "Consumer" as client
    participant "Mobile App" as mobile
    participant "Payneteasy" as company
    == Transfer has been checked successfully ==
    company -> company : Pause the transaction
    loop until Complete transfer is sent
    mobile -> company: Transfer status request
    note left
    session token
    end note
    mobile <-- company: Transfer status response
    note right
    state=TRANSFER_FEE_REQUEST
    transferFeeList
    end note
    end
    mobile -> client: Ask to select the commission
    mobile <-- client: Commission selected
    mobile -> company: Complete transfer request
	note left
	assignedId
	end note
    mobile <-- company: Complete transfer response
    company -> company: Continue processing
    @enduml

| (2,3) Funds transfer status request is made by Connecting Party’s app to Payneteasy to get the status of transfer transaction. To implement transfer status request see :ref:`Status Transfer<api_transfer_status>`. Transfer status response includes the :code:`state` parameter with :ex:`TRANSFER_FEE_REQUEST` value and the :code:`transferFeeList` object with a list of commissions for possible processing gates. Each processing gate is represented by it's own aliased name in :code:`assignedId` parameter. :ex:`TRANSFER_FEE_REQUEST` value in :code:`state` parameter exists only in "Consumer defined transfer rates" flow. The mentioned parameters may not be presented in first Transfer status response, so Connecting Party's app should continue polling the transaction status. When the transaction reaches :ex:`TRANSFER_FEE_REQUEST` state, the processing will remain paused until Complete transfer request is sent.
| (6,7) To implement Complete transfer request see :ref:`Complete transfer<api_complete_transfer>`.