Getting started with Cloud Integration

This page will help you get started with Payments Platform. You'll be up and running in a jiffy!

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

763

Processing a transaction

699

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.

467

Terminal in Cloud Integrated Mode

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

Figure 2. Terminal loading its configuration

467

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:

Figure 1. Terminal connected and polling.

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

469

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.

Figure 3. Terminal is offline

468

Figure 4. Terminal failing to retrieve configuration

470

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.

751

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

595

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"
  }

Example JSON Response to a request for a new APIKey

{
  "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.

507

Example JSON Response to a request for an overview of APIKeys

[
  {
    "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"
    }
  }
]
496

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)

467

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.

467

Example of data encoded in the QR code

{
  "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.

Example

{
    "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.

Example

{
    "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.

Example of a referenced refund

{
    "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.

Example of an unreferenced refund

{
    "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.

Example

{
    "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.

Example

{
    "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:

CREATEDTransaction is created and waiting authorization.
AUTHORIZEDTransaction is authorized by the Acquirer and awaiting clearance.
CLEAREDTransaction is cleared and is completed successfully. This status indicates that the transaction will be settled by the Acquirer to the merchant.
CANCELLEDTransaction is cancelled and is completed unsuccessfully

A transaction can have the following result values:

APPROVEDIndicates that the bank of the consumer authorized the payment.
DECLINEDIndicates that the bank of the consumer does NOT approve the payment.

Flow for a Successful transaction through the statuses

807

Flow for a declined transaction through the statusses

741

Flow for a transaction where the Consumer cancels

719

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.

Parameter nameDescriptionDefault value
pageIdentifies the requested page. *First page has number 1*1
sizeDefines the number of entries to show on each page. *Maximum value is 100*10
FormatGET <url>?page=$pageNumber&size=$pageSize
ExampleGET /stores?page=2&size=25
ExplanationWould return the 26th until the 50th store entries.

Pagination information in response

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

HeaderDescription

X-Total-Count

Total number of entries available

Link

Multiple links providing information about how to navigate through the entries. Links are separated by a comma ',' Format is compliant with RFC 8288 Web Linking

If the page size is larger than the total number of entries, then this header will be empty.

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.

Example of a Problem JSON response

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

Failure during authentication

Error CodeDescriptionSolution
401The Consumer System failed to include the API-Key-Header in the request.Add an API-Key Header to the request with a valid APIKey.
403The Consumer System included an invalid API-Key in the Header in the request.Replace the APIKey with a valid APIKey. Contact CM.com POS Payment’s Customer Care Center for getting a new valid APIKey if necessary.

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.