.. _mobile_device_sale:

Mobile Device Sale
==================

.. toctree::
    :maxdepth: 1

.. contents::
    :local:

.. role:: ex

.. role:: code


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

| Mobile device sale transaction can be performed with cardholder data 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>`.

Sale Flow
---------

.. uml::
    :align: center

    @startuml
    autonumber
    title Mobile Device - 3-D Secure sale
    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
    party <- mobile: Initiate sale request
    party --> mobile: Initiate sale response
    mobile -> company: Perform sale request
    mobile <-- company: Perform sale response
    note right
    session token
    end note
    company -> party: Check sale request
    company <-- party: Check sale response
    company -> company: Start processing
    mobile -> company: Sale status request
    note left
    session token
    end note
    mobile <-- company: Sale status response
    note right
    state = REDIRECT_REQUEST
    redirectUrl
    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: 3DS status update
    company --> mobile: Close browser request
    destroy mobile
    company -> company: Process sale
	party <- company: Sale card mapping notification request
    note right
    server card id
    end note
    party --> company: Sale card mapping notification response
    mobile -> company: Sale status request
    note left
    session token
    end note
    mobile <-- company: Sale 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 his 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 sale, 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 implement initiate sale request see :ref:`Initiate Sale<api_initiate_sale>`.
| (6,7) On this stage Connecting Party’s app sends cardholder, device, session data and other parameters straight to Payneteasy to perform sale transaction. To implement perform sale request see :ref:`Perform sale<api_perform_sale>`.
| (8,9) Check sale 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 sale request see :ref:`Check Sale<api_check_sale>`.
| (11,12,21,22) Sale status request is made by Connecting Party’s app to Payneteasy to get the status of sale transaction.To implement sale status request see :ref:`Sale status<api_sale_status>`.
| (19,20) Payneteasy sends Sale card mapping notification request to Connecting Party’s server/proxy with created on its side card reference - :ex:`{serverCardId}`. To implement sale card mapping notification request see :ref:`Sale card mapping notification<api_sale_card_mapping_notification>`.
| (23,24) If Connecting Party callback URL is specified on endpoint level, Payment Gateway sends message to this callback URL whenever transaction reaches final status, no matter if the result is :ex:`approved`, :ex:`declined` or has other :ref:`final status<status_list>`. See more in :ref:`Callbacks<merchant_callbacks>`.

Repeat Sale Flow
----------------

| After successful Card mapping procedure, new sale transactions with the same cardholder data can be done easier for Consumer.
| Connecting Party's app makes new sale requests using :ex:`{clientCardId}` instead of cardholder data. Payneteasy sends this :ex:`{clientCardId}` to Connecting Party's server in "Check sale request" and gets mapped to it :ex:`{serverCardId}` in "Check sale response" from Connecting Party's server. This :ex:`{serverCardId}` is used to continue the processing of sale transaction.
| Transaction flow remains the same: :ref:`Initiate Sale<api_initiate_sale>` -> :ref:`Perform sale<api_perform_sale>` -> :ref:`Check Sale<api_check_sale>`.
| If there is no need to change Consumer's data (such as address, phone, etc.), "Perform sale request" for Repeat sale may be sent without any optional parameters. If Consumer's data has to be changed, new source card reference must be created.
| If :ex:`{clientCardId}` is used in "Perform sale request", :ex:`{serverCardId}` must be included in "Check sale response" and signature.
| If :ex:`{clientCardId}` was mapped to :ex:`{serverCardId}` in transaction with included :ex:`{consumer.email}` value, new "Perform sale request" and "Check sale response" with this :ex:`{clientCardId}` must also contain the same :ex:`{consumer.email}` value.
|
| For Repeat Sale Flow use the following parameters in Perform Sale 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}`

.. uml::
    :align: center

    @startuml
    autonumber
    title Mobile Device - Card references for Repeat sale
    participant "Mobile App" as mobile
    participant "Connecting Party's Server" as party
    participant "Payment Gateway" as company
    skinparam ParticipantPadding 80
    == Last part of previous transaction ==
    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 sale ==
    mobile -> party: Initiate sale request
    mobile <-- party: Initiate sale response
    mobile -> company: Perform sale request
    note left
    clientCardId
    end note
    mobile <-- company: Perform sale response
    party <- company: Check sale request
    note right
    clientCardId
    end note
    party --> company: Check sale response
    note left
    serverCardId
    end note
    company -> company: Process sale
    @enduml

| (1,2) Payneteasy sends Sale card mapping notification request to Connecting Party’s server/proxy with created on its side card reference - :ex:`{serverCardId}`. To implement sale card mapping notification request see :ref:`Sale card mapping notification<api_sale_card_mapping_notification>`.
| (5,6) To initiate sale, 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 implement initiate sale request see :ref:`Initiate Sale<api_initiate_sale>`.
| (7,8) On this stage Connecting Party’s app sends cardholder, device, session data and other parameters straight to Payneteasy to perform sale transaction. To implement perform sale request see :ref:`Perform sale<api_perform_sale>`.
| (9,10) Check sale 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 sale request see :ref:`Check Sale<api_check_sale>`.