4.1. mPOS API

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 Sale and 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 /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 ENDPOINTID, 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 mPOS SDK for iOS and mPOS SDK for Android and Java). Integrator team implements Sale and/or Preauth transaction flows and MobileApp-to-mPOS communication tailoring their needs.

Sale Flow

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 /mapi/v1/sale/.
(5) To implement callback with final status handling see Connecting Party Callback.
(7) To implement order status request see /api/v2/status/. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.

Preauth Flow

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 /mapi/v1/preauth/.
(5) To implement callback with final status handling see Connecting Party Callback.
(7) To implement order status request see /api/v2/status/. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.