.. _mpos_api: mPOS API ######## .. contents:: :local: .. role:: ex .. role:: code Introduction ============ | mPOS is a device that is able to read card data from plastic cards (like magnetic stripe tracks) or other devices and transmit this data to the Payneteasy mPOS API in an encrypted form. | mPOS API (MAPI) supports :ref:`Sale` and :ref:`Preauth` transactions with status requests and callbacks for transaction status handling. | Depending on the exact acquiring solution, it might be required to implement regular Close Day procedure for bank payment clearing via :ref:`/api/v2/close-day/` API command. Please contact support manager for details. Mobile App Integration flow ============================ Payneteasy team creates a dedicated account on sandbox environment and provides integrator with test :ex:`ENDPOINTID`, :ex:`merchant_control_key` and test mPOS devices with pre-installed encryption key for processing test transactions. mPOS devices (each has a serial number) are handed to integrator along with SDK for communication (see :ref:`mPOS SDK for iOS` and :ref:`mPOS SDK for Android and Java`). Integrator team implements Sale and/or Preauth transaction flows and MobileApp-to-mPOS communication tailoring their needs. .. _mpos_api_sale: Sale Flow --------- .. uml:: :align: center skinparam roundcorner 20 skinparam sequenceArrowThickness 1 skinparam maxmessagesize 1200 skinparam sequenceParticipant underline actor Payer participant "Connecting Party" as A participant Payneteasy as B autonumber Payer -> A: Checkout activate A A -> B: /mapi/v1/sale/ activate B B --> A: Order ID B -> B: Process\nSale group Get Final Status == Receive Connecting Party Callback == A <- B: Callback with Final Status A --> B: HTTP 200 deactivate B == Order Status Request == A -> B: Get Status by Order ID activate B B --> A: Final Status deactivate B end A --> Payer: Show result deactivate Payer deactivate A | (2) To implement sale request see :ref:`/mapi/v1/sale/`. | (5) To implement callback with final status handling see :ref:`Connecting Party Callback`. | (7) To implement order status request see :ref:`/api/v2/status/`. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response. .. _mpos_api_preauth: Preauth Flow ------------ .. uml:: :align: center skinparam roundcorner 20 skinparam sequenceArrowThickness 1 skinparam maxmessagesize 1200 skinparam sequenceParticipant underline actor Payer participant "Connecting Party" as A participant Payneteasy as B autonumber Payer -> A: Checkout activate A A -> B: /mapi/v1/preauth/ activate B B --> A: Order ID B -> B: Process\nPreauth group Get Final Status == Receive Connecting Party Callback == A <- B: Callback with Final Status A --> B: HTTP 200 deactivate B == Order Status Request == A -> B: Get Status by Order ID activate B B --> A: Final Status deactivate B end A --> Payer: Show result deactivate Payer deactivate A | (2) To implement preauth request see :ref:`/mapi/v1/preauth/`. | (5) To implement callback with final status handling see :ref:`Connecting Party Callback`. | (7) To implement order status request see :ref:`/api/v2/status/`. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response. .. Request authorization through OAuth signature .. ============================================= .. .. To make sure that it’s the Connecting Party (and not somebody else) is who really authors requests, requests must be signed. OAuth 1.0a signature is used as a well-established and supported in the client libraries for this purpose on MAPI requests. Please note that it’s the only part of OAuth that we use in our API: signatures; our API does not actually support a full-blown OAuth. :ex:`HMAC-SHA1` method may be used to generate signatures. .. .. _mpos_rsa-sha1: .. .. Request signing with RSA-SHA1 signature method .. ---------------------------------------------- .. .. To use RSA-SHA1 signature method mPOS should be registered with RSA public key. Private key is used for sign requests Connecting Party. Reader serial number is used as an API token. To make a signed request in Java using scribe library please see example below: .. .. .. highlight:: java .. :: .. .. import com.payneteasy.tlv.HexUtil; .. import org.scribe.builder.api.DefaultApi10a; .. import org.scribe.model.*; .. import org.scribe.oauth.OAuth10aServiceImpl; .. import org.scribe.oauth.OAuthService; .. import org.scribe.services.HMACSha1SignatureService; .. import org.scribe.services.SignatureService; .. .. import java.nio.charset.StandardCharsets; .. import java.util.HashMap; .. import java.util.Map; .. .. public class App .. { .. public String doPost(String url, Map parameters) throws ConnectionIOException, ConnectionTimeoutException .. { .. OAuthConfig config = new OAuthConfig(apiToken, merchantControlKey, OAuthConstants.OUT_OF_BAND, SignatureType.Header, null,null); .. OAuthService service = new OAuth10aServiceImpl(new HmacSha1Mapi(), config); .. OAuthRequest request = new OAuthRequest(Verb.POST, url); .. for (Map.Entry entry : parameters.entrySet()) { .. request.addBodyParameter(entry.getKey(), entry.getValue()); .. } .. // empty token for 'two-legged' .. Token token = new Token("", ""); .. service.signRequest(token, request); .. Response response = request.send(); .. return response.getBody(); .. //System.out.println(response.getBody()); .. } .. .. private static class HmacSha1Mapi extends DefaultApi10a { .. @Override .. public String getRequestTokenEndpoint() { .. return null; // not used .. } .. .. @Override .. public String getAccessTokenEndpoint() { .. return null; //not used .. } .. .. @Override .. public String getAuthorizationUrl(Token requestToken) { .. return null; // not used .. } .. .. @Override .. public SignatureService getSignatureService() { .. return new HMACSha1SignatureService(); .. } .. } .. .. Add Signature .. ============= .. .. Signature request is initiated with :ex:`oauth1.0a` by using :ref:`HMAC-SHA1`. Secret key (HMAC) for signature is made of Connecting Party login and control key. Picture data is sent via raw :code:`POST` body. The :ex:`{shaHex}` is :ex:`SHA-1` digest from the picture data encoded as :ex:`HEX`. .. .. .. _api_v2_mpos_add_signature_url: .. .. API URLs .. -------- .. .. list-table:: .. :widths: 50, 50 .. :header-rows: 1 .. :class: longtable .. .. * - Integration .. - Production .. * - :ex:`https://sandbox.payneteasy.com/paynet/mapi/v1/add-signature/{endPointId}/{orderId}/{shaHex}` .. - :ex:`https://gate.payneteasy.com/paynet/mapi/v1/add-signature/{endPointId}/{orderId}/{shaHex}` .. .. Add Signature JSON Example .. -------------------------- .. .. Picture is being sent as a JSON object (as presented below): .. .. .. highlight:: java .. .. :: .. .. {"width": 580, "height": 601, "glyphs": [ .. [ .. [19, 135, 0], .. [20, 139, 83], .. [20, 143, 92], .. [22, 150, 102], .. [24, 159, 110], .. [26, 172, 120] .. ], .. [ .. [27, 157, 0], .. [29, 156, 526] .. ] .. ]} .. .. Each point contains :ex:`X`, :ex:`Y` coordinates of signature line and the time spent from the starting point (to reproduce animation).