Mobile Payment Integration (POS) Guide v1.3.3

1. Change Log

1.1 V1.3.0

1.2 V1.3.1

1.3 V1.3.2

1.4 V1.3.3

2. Introduction

This document describes the interface specifications required for POS integration with FOMO Pay.

3. Sequence Diagram

4. POS Gateway Interface

4.1 URL

SIT/UAT https://pos.fomopay.io/rpc

Production https://pos.fomopay.net/rpc

4.2 Request Content Type

Content-Type: application/json; charset=utf-8
Content-Type: application/json

4.3 Request Method

POST

4.4 Response Content Type

Content-Type: application/json; charset=utf-8
Content-Type: application/json

4.5 Request and Response Body (Sample)

{
  "0": "0200",
  "1": "a238408000c080000000010001000000",
  "3": "000000",
  "7": "1231235959",
  "11": "000135",
  "12": "235959",
  "13": "1231",
  "18": "0005",
  "25": "20",
  "41": "22222222",
  "42": "111111111111111",
  "49": "SGD",
  "88": "000000001000",
  "104": "Payment Description"
}

5. Security and Encryption

5.1 Transport Security

Transport Layer Security (TLS) 1.2.

5.2 Message Authentication

Following algorithm is used to authenticate both client (POS terminal) and server (POS gateway) in addition to TLS.

Prerequisite

The following keys are required:

1. RSA key pair (key pair 1) generated by POS vendor (See Appendix – Generating an RSA Key Pair).
2. RSA key pair (key pair 2) generated by FOMO Pay.

POS vendor shall share public key of key pair 1 with FOMO Pay. FOMO Pay will register the two key pairs in POS gateway system and share public key of key pair 2 with POS vendor. A key id representing the two key pairs will also be shared with POS vendor.

POS vendor shall have the following after key exchange.

• Private key of key pair 1
• Public key of key pair 2
• Key id representing the two key pairs.

Algorithm

Before sending a message to POS gateway, the message shall be signed. Any message not properly signed or not properly formatted will be rejected by POS gateway.

The signing algorithm is as follows:

1. POS terminal serialize JSON to an UTF-8 encoded string buffer [payload].
2. POS terminal generates UNIX timestamp [timestamp] and a nonce [nonce] on device. [timestamp] should be in 10 digits and [nonce] should have a length of 16 – 256.
3. POS terminal concatenate the payload, timestamp and nonce and get byte array to be digested.
4. POS terminal calculate the signature of the byte array using SHA256WithRSA with private key of key pair 1 and get the raw sign.
5. POS terminal then convert the raw sign to lowercase hexadecimal [sign].
6. POS terminal prepare HTTP request in following format.

Upon receiving message from POS gateway, the POS terminal shall verify the signature in the response HTTP header.

The verification algorithm is as follows:

1. POS terminal extracts the following HTTP headers from HTTP response.

X-Authentication-Version: [version]
X-Authentication-Method: [method]
X-Authentication-Nonce: [nonce]
X-Authentication-Timestamp: [timestamp]
X-Authentication-Sign: [sign]
Content-Type: [content-type]

2. If one or more of the following conditions does not satisfy, reject the response.

• version is 1.1
• method is SHA256WithRSA
• nonce exists and was not used by POS gateway within 300 seconds
• timestamp is within ± 300 seconds of current time

3. POS terminal reads response body [payload] from HTTP response.
4. POS terminal concatenates [payload], [timestamp] and [nonce] and gets the byte array to be digested.
5. POS terminal verifies the digest against received signature [sign] using SHA256WithRSA with public key of key pair 2.
6. If the signature cannot be verified, reject the response.

6. Symbols and Abbreviated Terms

6.1 Field Types

6.2 Required Flag

7. Message Types and Specification

7.1 Sale Request

7.2 Sale Response

7.3 Query Request

7.4 Query Response

7.5 Reversal Request

7.6 Reversal Response

7.7 Void Request

Void can be initiated for any transaction, but the transaction batch must have not been submitted.

Note: Void can be called for any transaction when the payment status is not SUCCESS. Or Void can be called for WeChat Pay, Alipay Singtel Dash and GrabPay transaction when payment status is SUCCESS. Others will be supported in the future.

7.8 Void Response

7.9 Cancel Request

Cancel can be initiated only when the original transaction is not finished, and transaction batch is not yet submitted. E.g. The QR code has been generated but payment is not yet made.

7.10 Cancel Response

7.11 Refund Request

Refund can be initiated only when original transaction is successful regardless of the status of the transaction batch. E.g. Transaction can be refunded after settlement.

Note: Refund is currently only supported at merchant portal. Refund through direct API call will be supported in the future.

7.12 Refund Response

7.13 Batch Pre-submit Request

Batch submit is to group a set of transactions into a batch. Only batch submitted transactions will be settled to merchant.

Batch pre-submit is an optional step for merchant to check current batch summary before making batch submit request.

7.14 Batch Pre-submit Response

7.15 Batch Submit Request

Batch submit is to group a set of transactions into a batch. Only batch submitted transactions will be settled to merchant.

7.16 Batch Submit Response

7.17 Retrieve Supported Sources of Fund Request

Retrieve supported sources of fund is an optional step for merchant to get the list of supported sources of fund (presented as condition codes in Appendix - Table 1) for a terminal.

7.18 Retrieve Source of Fund Response

7.19 Static QR Notification Request

Note: See Appendix – Static QR Notification

7.20 Static QR Notification Response

7.21 Static Query Request

7.22 Static Query Response

8. Resource API

8.1 Query Source of Fund (SOF)

Replace {conditionCode} in the request path with the condition code from Appendix - Table 1, for example 20 for WeChat Pay QR Code.

Response

When HTTP status code is 2xx

curl -X GET "https://pos.fomopay.net/resource/sof/20"

{
  "name": "WeChat Pay",
  "country": "SG",
  "presentation": "QR",
  "mode": "CPM",
  "type": "DYNAMIC",
  "images": {
    "light": "https://cdn.example.com/wechat-pay-light.png",
    "dark": "https://cdn.example.com/wechat-pay-dark.png"
  }
}

9. Appendix

9.1 Table 1 – Condition Code for Sale Request

9.2 Table 2 – Response Code for Sale Response

Table 3 – Response Code for Query/Static Query Response

Table 4 – Response Code for Reversal Response

Table 5 – Response Code for Void Response

Table 6 – Response Code for Cancel Response

Table 7 – Response Code for Refund Response

Table 8 – Response Code for Batch Submit/Pre-submit Response

Table 9 – Additional Amounts (54) for Sale Request

Example:

For base amount 1000 cents and tip amount 200 cents, use B000000001000T000000000200

Table 10 – STAN for Static QR Notification Request/Response

Table 11 – Response Code for Static QR Notification Response

Table 12 – Response Code for Retrieve Supported SOF Response

Table 13 – List of SOF Presentation

Table 14 – List of SOF Mode

Table 15 – List of SOF Type

Table 16 – List of SOF Images

The images object contains the following:

Table 17 – Extension Data for Sale Request

Extension Data is a serialized JSON object which has the following content:

{
  "isEncryptedAuthCode": boolean // Applicable values: {true, false}
}

<isEncryptedAuthCode>: Indicator of the type of authentication code (For WeChat Palm Pay solution)

Table 18 - Reserved (private)

For QR payments, this field contains code information.

For card payments, please check with FOMO to confirm the technical requirements and eligibility for processing card transactions.

Response 1 – Batch Summary

Batch Summary is a serialized JSON object which has the following content:

{
  "batch": string,
  "sale": TStats,
  "refund": TStats
}

<batch>: Current batch number.

<sale>: Summary for sale transactions.

<refund>: Summary for refund transactions.

TStats is defined as:

{
  "success": TAmountAndCount,
  "fail": TAmountAndCount,
  "void": TAmountAndCount,
  "cancelled": TAmountAndCount,
  "closed": TAmountAndCount
}

• <success>: Summary for sale or refund transactions which are completed successfully.
• <fail>: Summary for sale or refund transactions which are failed.
• <void>: Summary for sale transactions which are voided, not applicable to refund transactions.
• <cancelled>: Summary for sale transactions which are cancelled, not applicable to refund transactions.
• <closed>: Summary for sale transactions which are closed (sale transactions will be closed if payment not completed after timeout), not applicable to refund transactions.

TAmountAndCount is defined as:

{
  "amount": string,
  "count": number
}

<amount>: total amount of sale or refund transactions in current status category.

<count>: total number of sale or refund transactions in current status category.

Response 2 – Supported Sources of Fund

Supported sources of fund is a serialized JSON string array. Each element of the serialized array corresponds to a condition code listed in Appendix – Table 1.

When there is no source of fund supported for a terminal, the response is an empty array:

[]

When there is source of fund supported for a terminal, the response includes a list of condition codes supported by the terminal:

["20", "30"]

Static QR Notification

Push notification is achieved via long polling. There are two states involved in the polling.

Polling phase

Terminal sends 0120 message without field 11 (STAN) to initialize polling. Server may hold the

HTTP connection up to 30 seconds. Server will respond with 0130 message with field 39 (response code) set to 00, 12 or other values (see Table 11 – Response code for Static QR Query Response).

Response code 12 means there is no new transaction found and terminal shall immediately perform polling again.

Response code 00 means there is a new transaction found and state machine of terminal shall immediately turn into fetching phase.

If other response code found or connection timeout/disconnected unexpectedly, server shall perform polling again after 5 seconds.

Fetching phase

Terminal sends 0120 message with field 11 (STAN) to initialize fetching. Server will respond with 0130 message with field 39 (response code) set to 00, 12 or other values (see Table 11 – Response code for Static QR Query Response). Terminal can optionally send field 104 which is the description of the current transaction.

Response code 00 means the transaction is accepted by the server with the STAN provided by the terminal. Terminal shall immediately initiate 0140 message (static query) to query the final status of the transaction. Use the response code of static query response (see Table 3 – Response Code for Query/Static Query Response) for status and other information of the transaction. After determining the status of the transaction, state machine of terminal shall turn into polling phase.

Response code 12 means the previous transaction was aborted or cancelled. Server may hold the HTTP connection up to 30 seconds. State machine of terminal shall turn into polling phase.

If other response code found or connection timeout/disconnected unexpectedly, state machine of terminal shall turn into polling phase and perform polling after 5 seconds.

Calculating Bitmap

Bitmap is used to indicate whether data fields are present in the message.

Bitmap consists of a primary bitmap and a secondary bitmap. Secondary bitmap is optional when all keys are smaller than or equal to 64.

Field 0 and field 1 are ignored while calculating bitmap. If a secondary bitmap is used, first bit of primary bitmap must be set to 1.

Example 1:

Given fields 0, 1, 3, 7, 11, 41 and 42 present in a message. As no key larger than 64, only primary bitmap is required.

Final bitmap is 2220000000c00000.

Example 2:

Given fields 0, 1, 3, 7, 11, 12, 13, 18, 25, 41, 42, 49, 88 and 104 present in a message. As key 88 and 104 will not fit in primary bitmap, both primary and secondary bitmap must be used.

Final bitmap is a238408000c080000000010001000000.

Generating an RSA Key Pair

Use the follow commands (in bold) to generate an RSA key pair. You will need to have openssl installed prior to running the commands.

Please share the file containing only public key (posvendor.pub.pem) with FOMO Pay for configuration. The file containing secret key (posvendor.key.pem) shall always be kept secure.

Example

posvendor.pub.pem

posvendor.key.pem