Introduction

Target Audience

This document is relevant for you as a customer if:

• You are a merchant.

• You are a reseller/integrator serving multiple merchants.

The Cloud Integration is a solution meant to help customers looking to
connect their electronic cash register solution via the cloud with a
complete payment solution. When deciding for the cloud integration
option available via CM.com POS Payments, customers get easy and secure
access to the whole payment network involved in processing card present
transactions.

The Cloud Integration is currently in Beta phase, hence is not fully
available to the entire customer base. If you are interested in becoming
a Beta customer, please contact your Sales Representative.

Cloud Integration explained

Using Cloud Integration is an option for customers to start using
Sunmi Terminals, where the initiation of the transaction is being done
via the cloud, usually by the backend of the customer selling platform.
That backend will connect to the MerchantAPI of the CM.com POS Payment
Platform.

Another possibility for the initiation of the transaction is available
via the on-device app-to-app integration from a custom-made Android ECR
application. Please contact your CM.com POS Payments Sales
representative in case you require access to the app-to-app integration
guide.

Via the MerchantAPI customers are able to notify the CM.com Payments
Platform that a transaction is requested on a specific terminal for a
specific amount and ask for the status of their initiated transaction

The Sunmi Terminals involved will be configured upon onboarding with a
Cloud Integration Enabled option, which will result in the terminal to
poll the CM.com Payments Platform regularly to inquire if there is a new
transaction to be handled. Concretely polling means a terminal will
proactively look for and inquire the CM Payment Platform every X period
(a configured interval, usually less than 10 seconds) for a transaction
to be processed.

System Overview

Processing a transaction

The diagram above describes a cardholder tapping a card to a terminal.
Possible ways to authorise a payment are tapping, swiping or inserting a
card into the terminal.

Retrieving the status of a transaction

After the creation of a transaction by a Customer System, that system
will need to be able to determine the status of the transaction. The
MerchantAPI allows a Customer System to retrieve information about any
transaction.

Terminal in Cloud Integrated Mode

Upon startup the terminals will be retrieving/updating their
configuration.

Within the configuration there are settings to inform a terminal that it
should operate in 'Cloud Integration'-mode. If the terminal is in 'Cloud
Integration'-mode and connected to the internet it will be polling by
default. This is how a terminal user can check that a terminal polls:

If the bar is blue,
then the terminal is connected and polling.

Some error scenarios

Terminals do not poll if they are turned off, in standby, or while
retrieving/updating their configuration. Errors in polling are signaled
by the terminal and will result in an error message being shown.

Getting started

Prerequisites

In order to interact with the MerchantAPI a customer has to be
configured within the CM.com POS Payments system and an APIKey has to be
assigned and securely provided to the customer. The configuration within
the CM.com POS Payments system is executed by CM.com POS Payments
Customer Care Center during onboarding based on a valid contract
presented by CM.com POS Payments Sales team.

Connectivity

• The MerchantAPI is hosted on payplaza.com.

• All the messages will be formatted as JSON.

• The messages are communicated using the format of the
  HTTP/1.1-protocol as described in RFC 2616
  HTTP/1.1

• All communication between Customer systems and the CM.com POS Payment
  Platform will be encrypted using TLS. This results in the
  MerchantAPI being offered as HTTPS.

• All available operations are documented using the OpenAPI
  Specification

• The MerchantAPI does not have a Rate Limit.

Start using the MerchantAPI

1. Download the OpenAPI specification of the MerchantAPI

2. Create a client compatible with the retrieved specification in the
   programming language you are using.

   1. For various programming languages OpenAPI Client
      Generators
      are available, which can help with this.

3. Include the generated client into your system

4. Include the provided APIKey into your system configuration

5. Adjust your system to invoke MerchantAPI operations when needed

Environments

Authentication

The MerchantAPI is protected from unauthorized access. In order for a
customer to identify itself when invoking any operation of the
MerchantAPI, the HTTP request MUST contain a header with the name
API-Key. Make sure the case and all the characters match this exactly.
The value of that header MUST be the API key, which CM.com POS Payments
provided during the onboarding.

Failure to Authenticate

• Any request sent to the MerchantAPI without the API-Key header will
  get an HTTP 401 Unauthorized response.

• Any request sent to the MerchantAPI with an invalid API-Key header
  will get an HTTP 403 Forbidden response.

APIKey Rotation

In order to mitigate security concerns customers are enabled and
encouraged to frequently change their APIKey. After a customer has
received their initial APIKey securely from CM.com POS Payments they are
able to handle APIKey rotation themselves via a dedicated endpoint in
the MerchantAPI.

This /apikeys endpoint supports:

• Getting an overview of current APIKeys issued to the organization

• Requesting a new APIKey for the organization

• Revoke access for a specific APIKey

Getting started

Interaction with the APIKey-endpoint is protected with an APIKey itself.
In order to get access initially CM.com POS Payments will generate a
first APIKey and transfer that securely to the Customer.

Customers will be able to see an overview of their current APIKeys.

Starting APIKey Rotation

The process can be done completely by the Customer themselves without
assistance of CM.com POS Payments employees and this can be done as
follows:

1. Customer generates a new APIKey

2. Customer updates their MerchantSystem to use the new APIKey

3. Customer revokes access on the old APIKey
   [block:image]
   {
   "images": [
   {
   "image": [
   "https://files.readme.io/9c76826-diag-dd25d37c9ae4605c2a2bba5a5977dce8.png",
   "diag-dd25d37c9ae4605c2a2bba5a5977dce8.png",
   885,
   545,
   "#f2f3f2"
   ]
   }
   ]
   }
   [/block]

Example JSON Body for a request for a new APIKey

{
  "label": "2022 2nd half"                  // REQUIRED
  "validity" : {                            // OPTIONAL
    "from" : "2022-07-01T00:00:00+00:00",
    "until": "2023-01-01T00:00:00+00:00"
  }

{
  "id": 854844465,
  "label":"Our 2nd APIKey",
  "apikey": "tioreutopert443543uiyffudh.jfyiuf.453"
}

Rules

• Customers MUST provide a Label for the new APIKey.

• APIKeys MAY be used indefinitely.

• APIKeys CAN be created with a validity period, which will cause an
  APIKey to expire after certain period.

• The actual APIKey will be shown only ONCE in the reply. The overview
  will not contain the actual key.

After an additional key has been generated, the overview will show all
valid keys.

[
  {
    "id": 767854635839,                         // REQUIRED
    "label": "Initial API Key",                 // REQUIRED
    "lastUsage": "2022-05-06T11:53:46+02:00"    // OPTIONAL
  },
  {
    "id": 854844465,                            // REQUIRED
    "label": "2022 2nd half",                   // REQUIRED
    "validity" : {                              // OPTIONAL
      "from": "2022-07-01T00:00:00+00:00",
      "until": "2023-01-01T00:00:00+00:00"
    }
  }
]

Rules

• A customer can NOT revoke access to their last APIkey

• A customer can NOT revoke access on the APIKey they are using for
  the request to revoke a key
  [block:image]
  {
  "images": [
  {
  "image": [
  "https://files.readme.io/5cc9f16-diag-e2704e8135dcff00f11927b7eddddc63.png",
  "diag-e2704e8135dcff00f11927b7eddddc63.png",
  494,
  347,
  "#edefed"
  ]
  }
  ]
  }
  [/block]

Resources

The MerchantAPI provides various resource for the customer to use.

Listing Stores

The MerchantAPI allows customers to retrieve a listing of their
registered stores. Should the customer have registered stores across
different merchants, all the stores of all their merchants will be shown
via this request.

Format
GET /stores

Supports Pagination

Listing Terminals

The MerchantAPI allows customers to retrieve a listing of their
registered terminals. Should the customer have registered terminals
across multiple stores, all their terminals, across all stores will be
shown via this request.

Format
GET /terminals

Supports Pagination

Receipt note

The Merchant API returns a plain text EFT receipt for any transaction
for which a receipt is applicable. Per the card schemes regulations, a
receipt should always be available for cardholders/customers.
All the mandatory information required on the receipt from a transaction
point of view will be included in the plain text receipt.
In addition to this information, integrators are required to make
available to their cardholders/customers a description and the price of
each product and service purchased or returned, including applicable
taxes, in detail sufficient to identify the transaction.

Transaction related endpoints

All transactions within the CM.com POS Payment Solution are related to a
terminal. Therefor within the MerchantAPI all requests related to
transactions require some identifiers of the target terminal. Within the
CM.com POS Payment Solution terminals are identified by their
manufacturer, model and serial number. The customer is responsible for
selecting the proper values for manufacturer, model and serial to target
the proper terminal from the Customer System.

Finding the identifiers.

There are various ways to obtain the manufacturer, model and serial for
a device.

Read from the menu of the Terminal App

The easiest ways being getting the information from the hamburger menu
of the terminal app: System report → Device serial number (or using the
Sunmi device: Settings→About device→Serial number)

A Sales representative could enter these values in their Customer System
for a sale to delegate the transaction to that terminal.

Read from the QR Code of the Terminal App

If the Customer System has the capability to scan QR code, the manual
entry of the identifiers could be circumvented, since the Terminal App
has the ability to display a QR-code, which contains the serial
information.

{
  "manufacturer":"SUNMI",
  "model":"P2lite",
  "serial":"PL09214300501"
}

Read from the Serialnumber from the device.

The info can be derived from the device itself as well, but that will
require taking out the battery (which we do not recommend).

Listing Transactions per terminal

The MerchantAPI allows customers to retrieve a listing of their
registered transactions per terminal.

Format
GET /terminals/{manufacturer}-{model}-{serial}/transactions

Example
GET /terminals/SUNMI-P2lite-PL0919CQ00305/transactions

Supports pagination

Initiating a payment

After identifying the target terminal for a transaction the Customer
System will need to POST a message to the MerchantAPI of the CM.com POS
Payment Solution.

Format
POST /terminals/{manufacturer}-{model}-{serial}/transactions

The message needs to contain the following: the amount, currency and
merchantReferenceCode

The MerchantAPI will make sure only one payment is available for a
terminal to processed. The Customer System may send two consecutive
messages for payment A and payment B for the same terminal. If payment A
has not been retrieved by the terminal when sending payment B the
MerchantAPI will abort payment A, and the terminal will receive payment
B.

Transaction Request

The actual message needs to be sent as JSON. Detailed information about
the fields can be found in the OpenAPI specification.

{
    "type": "PURCHASE",
    "merchant_order_reference": "inv2112280004",
    "amount": {
        "value": 98.75,
        "currency": "EUR"
    }
}

Transaction Response

In response to the initiated transaction the CM.com POS Payment Solution
will generate an identifier and will send the information back including
the status on the transaction. Initially the transaction will only
contain a small set of relevant fields.

{
    "type": "PURCHASE",
    "id": "5456485215432746823746654987115",
    "merchant_order_reference": "inv2112280004",
    "creation_datetime": "2022-01-18T14:30:05.619Z",
    "amount": {
        "value": 98.75,
        "currency": "EUR"
    },
    "status": "CREATED"
}

The important value is available in the field id, since the Customer
System needs that identifier further on to retrieve updates in the
status.

Initiate a referenced refund

A customer can initiate a refund in a similar manner as a purchase. In
the message the customer must supply the id of the original purchase
which is being refunded as a reference.

{
    "type": "REFUND",
    "merchant_order_reference": "invoice-202112280004-r",
    "amount": {
        "value": 98.75,
        "currency": "EUR"
    },
    "reference": {
        "id": "5456485215432746823746654987115"
    }
}

Initiate an unreferenced refund

A customer can initiate a refund in a similar manner as a purchase. In
the message the customer does not supply an id of the original purchase.

{
    "type": "REFUND",
    "merchant_order_reference": "invoice-202112280004-r",
    "amount": {
        "value": 98.75,
        "currency": "EUR"
    }
}

Getting the status of a transaction

If the Customer System wants to get information about the status of a
transaction, it can ask the MerchantAPI for that. In order to do so it
needs to send an HTTP GET to a specific endpoint.

Format
GET /terminals/{manufacturer}-{model}-{serial}/transactions/{id}

Example
GET /terminals/SUNMI-P2Lite-PL0919CQ00305/transactions/5456485215432746823746

Initially the data will be the same as the response to the POST, which
created the transaction.

{
    "type": "PURCHASE",
    "id": "5456485215432746823746654987115",
    "merchant_order_reference": "inv2112280004",
    "creation_datetime": "2022-01-18T14:30:05.619Z",
    "amount": {
        "value": 98.75,
        "currency": "EUR"
    },
    "status": "CREATED"
}

After the consumer has provided their bankcard and the transaction has
been processed, the response will contain more data.

{
    "merchant_order_reference": "inv2112280004",
    "amount": {
        "value": 98.75,
        "currency": "EUR"
    },
    "id": "5456485215432746823746654987115",
    "creation_datetime": "2022-01-18T14:30:05.619Z",
    "transaction_datetime": "2022-01-18T14:31:02Z",
    "system_trace_audit_number": "155890",
    "brand": "V_PAY",
    "receipt": "     CARDHOLDER NAME      \n....\nPAYMENT ACCEPTED    \n\n..... ",
    "merchant_receipt": "     MERCHANT NAME      \n....\nPAYMENT ACCEPTED    \n\n..... ",
    "result": "APPROVED",
    "status": "CLEARED",
    "type": "PURCHASE",
    "store": {
        "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "The configured Shopname"
    }
}

Statuses and result of a Transaction

A transaction can have the following statuses:

A transaction can have the following result values:

Flow for a Successful transaction through the statuses

Flow for a declined transaction through the statusses

Flow for a transaction where the Consumer cancels

Cancel a transaction

If the Customer System wants to cancel a transaction, before it is
handled by a terminal (it has the CREATED status), it can instruct the
MerchantAPI to do so. In order to do so it needs to send an HTTP DELETE
to a specific endpoint, identifying the transaction.

Format
DELETE /terminals/{manufacturer}-{model}-{serial}/transactions/{id}

Example
DELETE /terminals/SUNMI-P2Lite-PL0919CQ00305/transactions/5456485215432746823746

When the transaction is still in a state to be cancelled a response with
HTTP status 204 will be the result. If the transaction is already in a
state, where it can not be cancelled anymore (because a card has been
presented on the terminal), then a HTTP status 409 Conflict will be
the result.

Retrieve day totals per terminal

The MerchantAPI allows customers to retrieve the day totals of their
registered transactions per terminal. The day totals will be presented
as a formatted receipt.

Format
GET /terminals/{manufacturer}-{model}-{serial}/daytotals/today

Example
GET /terminals/SUNMI-P2lite-PL0919CQ00305/daytotals/today

Pagination

All endpoints, which return a listing, allow pagination by supporting
two query parameters on the requests.

Pagination information in response

On all responses to any requests for a listing there will be two
headers, which provide information about the pagination.

Example

Given there is a merchant with 67 stores, when the merchant sends the
following request: /stores?page=3&size=10 then the response will
contain the following headers:

X-Total-Count: 67
Link: <baseUrl/stores?size=10&page=2>; rel="prev",<baseUrl/stores?size=1&page=4>; rel="next",<baseUrl/stores?size=1&page=1>; rel="first",<baseUrl/stores?size=1&page=7>; rel="last"

Troubleshooting error situations

Standardized way of describing problems

When an error or exception occurs while processing a request and the
result will be a HTTP Status 4xx of 5xx, then the body of the
response will contain more information about what caused the problem.
Those responses will have the content-type application/problem+json.
Problem Details for HTTP
APIs is a standardized
way of describing any kind of error thrown by an API.

{
  "status": 403,
  "title": "Forbidden",
  "detail": "Invalid API Key.",
  "instance": "/stores"
}

Failure during authentication

Disconnects during communication

When a Consumer System sends a request to the MerchantAPI but fails to
receive a HTTP response due to some network issue, the request still
might have been received and handled correctly by the CM POS Payment
Platform.

• All GET operations can be retried by the Consumer System.

• For other operations the Consumer System might want to retrieve the
  current status before a retry since a new transaction might have
  been created or an aborted transaction might actually have been
  aborted.

• The id of a transaction can be found by requesting a list of
  transactions per terminal and find the transaction by the
  merchant_order_reference.

Failure to abort a transaction

When a Consumer System attempts to abort a transaction and gets a
409 Conflict response, then the abort did not succeed since the
terminal has already started to process that transactions.

The Consumer System should then get the status of the transaction and if
the result for that transaction is APPROVED, then the consumer
probably will want to initiate a refund for that transaction.

How to continue

Congratulations! Reviewing the Cloud Integration Guide is the
first step towards understanding how the solution works. Please be
reminded that before being able to use this solution, a potential
customer needs to:

• Agree on commercial conditions and the setup needed for each
  customer’s case (number of terminals, type of terminals, configuration
  needed, etc)

• Get onboarded. During this step, customers will be setup throughout
  CM.com POS Payments systems to be able to start their integration

• Integration time. During this step, customers will use the existing
  documentation to integrate the API and test it accordingly

• Testing time. During this step, based on a common strategy, CM.com POS
  Payments and the customer will execute the necessary testing that make
  both parties comfortable to launch

• Launching preparations. During this step, both parties perform all
  necessary configurations allowing live transaction processing and
  defining the success criteria for launch.

• Launch day and initial period monitoring. During this step, both
  parties monitor the initial phase of live transaction processing
  making sure the success criteria is met.

• Normal operations. Once the initial period has concluded successfully,
  the customer enters the stage of normal operations.

Glossary of Terms

Cardholder

A person who has been given permission to use a card which allows them
to do payments, for example a credit card or debit card.

CM.com POS Payment Platform

CM.com POS Payments’s proprietary payment gateway/host that connects
payment terminals with payment processors.

Customer

A party – reseller/partner or merchants – entering a contractual
relationship with CM.com POS Payments.

Merchant

A party selling goods and owning stores that are using CM.com POS
Payments’s terminals for accepting card present transactions. The
merchant can be a direct customer of CM.com POS Payments or a direct
customer of one of CM.com POS Payments partners/resellers.

Terminal

A terminal is a device that has the ability to read credit/debit cards
in at least one of the common methods (Swipe for magnetic stripe, insert
for ICC or tap for NFC). A terminal runs a software application created
by CM.com POS Payments to securely perform payment transactions.

Transaction types

The different flows the merchant supports. Purchase, refund and
pre-authorization are the tree types commonly used in CM.com POS
Payments ecosystem.