Web Integration Guide v1.1.2

1. Change Log

1.1 V1.0.0

Initial release.

1.2 V1.0.1-V1.0.7

(Removed)

1.3 V1.0.9

Specify transaction options for DPT DIRECT and DPT HOSTED mode.

1.4 V1.0.10

Update transaction options for WECHATPAY DIRECT (JSAPI) mode.

1.5 V1.0.11

Update transaction options for ALIPAY DIRECT (WAP) mode.

1.6 V1.0.12

Update transaction options for ALIPAY DIRECT (APP, MINI_APP) mode.

1.7 V1.1.0

Introduce card tokenization supportability for Customer-Initiated Transactions (CIT) and Merchant-Initiated Transactions (MIT) for DIRECT mode.

New APIs to support card token creation, retrieval, and deletion.
Update transaction options for DIRECT mode.

1.8 V1.1.1

Specify transaction options for DPT DIRECT and DPT HOSTED mode to support fraud detection.
Adjusted formatting

1.9 V1.1.2

Updated parameter descriptions for WECHATPAY DIRECT (JSAPI) mode and added parameter descriptions for WECHATPAY DIRECT (MWEB) mode
Added detailed explanation of the returnUrl parameter in Appendix 9.8 to clarify its usage and integration process.

2. PCI Compliance

To accept card payment in Direct Mode, you must submit a copy of your PCI-DSS certificate (for all relevant SAQs) to FOMO Pay to clear relevant compliance requirements.

For more information for SAQs, please visit:
https://www.pcisecuritystandards.org/documents/Understanding_SAQs_PCI_DSS_v3.pdf

3. Sequence Diagram

3.1 Hosted Mode

3.2 Direct Mode

4. Security and Encryption

4.1 Transport Security

Transport Layer Security (TLS) 1.2

4.2 Message Authentication

RFC 7617 HTTP Basic Authentication (https://tools.ietf.org/html/rfc7617)

The following key is required:

MID (<MID>) generated by FOMO Pay.
Pre-Shared Key (<PSK>) generated by FOMO Pay.

Please ensure <PSK>never leaves your server and managed by trusted parties only. Failing to do so will result in unauthorized access to your account. If you believe your <PSK>is lost, contact FOMO Pay immediately.

HTTP Authorization header is required in all requests. The Authorization header is constructed as follow.

Authorization: <AuthorizationType> <BasicCredentials>

<AuthorizationType>: fixed value Basic (without quote).

<BasicCredentials>: generated as follow.

"Base64(<MID>:<PSK>)"

Example:

Merchant setup:

Key	Value
<MID>	100000000000001
<PSK>	E00F270DE323E2B187532D8E4B306EB2841AF0BFF08132BAB7F0E62BED6419BB

Calculation:

Calculate <BasicCredentials> from:

Base64("100000000000001:E00F270DE323E2B187532D8E4B306EB2841AF0BFF08132BAB7F0E62BED6419BB")

Which yields:

MTAwMDAwMDAwMDAwMDAxOkUwMEYyNzBERTMyM0UyQjE4NzUzMkQ4RTRCMzA2RUIyODQxQUYwQkZGMDgxMzJCQUI3RjBFNjJCRUQ2NDE5QkI=

Authorization header:

Authorization: Basic MTAwMDAwMDAwMDAwMDAxOkUwMEYyNzBERTMyM0UyQjE4NzUzMkQ4RTRCMzA2RUIyODQxQUYwQkZGMDgxMzJCQUI3RjBFNjJCRUQ2NDE5QkI=

Include Authorization header in every request you send to FOMO Pay. Never include this header when you send request to other non-FOMO Pay servers.

5. Symbols and Abbreviated Terms

5.1 Required Flag

Abbreviation	Description
M	Mandatory
O	Optional
C	Conditional
X	Not supported

6. Message Types and Specification

6.1 Create an Order (Hosted Mode)

Request

Request Metadata

Name	Value
URL	`https://ipg.fomopay.net/api/orders`
Method	POST/PUT
Content-Type	application/json

⚠️	Connection error might occur during transaction creation. Do NOT create another transaction yet. Instead, retry using PUT method with the same requesting JSON. Multiple POST requests with the same orderNo will result in HTTP 409 error.

Authorization

Authorization

Authorization<token>

Set to Basic <Base64(MID:PSK)>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

mode*string

Must be HOSTED

orderNo*string

(1-64 UTF-8 characters) Unique order number generated by merchant

subMid?string

(PSP merchants only) Sub-Merchant ID assigned by FOMO Pay. Please DO NOT include this field if not instructed

subject*string

(1-64 UTF-8 characters) Short description of your order so your customers know what they are paying for. This may also be reflected on customer bank/wallet statements

description?string

(1-512 UTF-8 characters) Long description of your order

amount*string

To lowest currency unit e.g. 10.00 for SGD, 10 for JPY

currencyCode*string

ISO 4217 currency code e.g. SGD

notifyUrl*string

Must be a valid HTTP or HTTPS link. Must not contain userinfo, query or fragment. If using HTTPS, server must be configured with a valid certificate. See Transaction Status Update Notification

Formaturi

returnUrl*string

Link to redirect customer to after payment, may carry query or fragment

Formaturi

backUrl?string

Link to redirect customer to when user cancel the payment, may carry query or fragment. If not provided, customer will not be presented with a back-to-merchant button

Formaturi

sourceOfFunds?array<>

If provided, customer will be presented with requested payment methods only. See Appendix 1

transactionOptions?

See Appendix 4. Mandatory for payment methods in Appendix 4. Optional otherwise

mode*string

Must be DIRECT

orderNo*string

(1-64 UTF-8 characters) Unique order number generated by merchant

subMid?string

(PSP merchants only) Sub-Merchant ID assigned by FOMO Pay. Please DO NOT include this field if not instructed

subject*string

(1-64 UTF-8 characters) Short description of your order so your customers know what they are paying for. This may also be reflected on customer bank/wallet statements

description?string

(1-512 UTF-8 characters) Long description of your order

amount*string

To lowest currency unit e.g. 10.00 for SGD, 10 for JPY

currencyCode*string

ISO 4217 currency code e.g. SGD

notifyUrl*string

Must be a valid HTTP or HTTPS link. Must not contain userinfo, query or fragment. If using HTTPS, server must be configured with a valid certificate. See Transaction Status Update Notification

Formaturi

returnUrl?string

Link to redirect customer to after payment, may carry query or fragment. See Appendix 8

Formaturi

backUrl?string

Link to redirect customer to when user cancel the payment, may carry query or fragment

Formaturi

sourceOfFund*string

Specify a payment method. See Appendix 1

Value in

"ALIPAY" | "CARD" | "BROWSER" | "NETSPAY" | "WECHATPAY" | "UNIONPAY" | "GRABPAY" | "PAYNOW" | "SHOPEEPAY" | "ATOME" | "DPT" | "PAYPAL"

transactionOptions*

See Appendix 5

Response Body

`application/json`

Example:

curl -X POST "https://ipg.fomopay.net/api/orders" \  -H "Content-Type: application/json" \  -d '{    "mode": "HOSTED",    "orderNo": "WEB-ORDER-10001",    "subject": "FOMO Pay Demo Order",    "description": "Hosted checkout example",    "amount": "10.00",    "currencyCode": "SGD",    "notifyUrl": "https://merchant.example.com/payments/notify",    "returnUrl": "https://merchant.example.com/payments/return",    "backUrl": "https://merchant.example.com/payments/cancel",    "sourceOfFunds": [      "CARD",      "PAYNOW"    ]  }'

{
  "id": "ord_01HQZ6Q3F1WB4G3WQ7D6A0S9R9",
  "subMid": "100000000000002",
  "orderNo": "WEB-ORDER-10001",
  "mode": "HOSTED",
  "subject": "FOMO Pay Demo Order",
  "description": "Hosted checkout example",
  "amount": "10.00",
  "currencyCode": "SGD",
  "status": "CREATED",
  "createdAt": 1711977000,
  "notifyUrl": "https://merchant.example.com/payments/notify",
  "returnUrl": "https://merchant.example.com/payments/return",
  "backUrl": "https://merchant.example.com/payments/cancel",
  "primaryTransactionId": "txn_01HQZ6T50Y7Y8FQ40R8Q9MZ7XM",
  "url": "https://pay.fomopay.net/redirect/ord_01HQZ6Q3F1WB4G3WQ7D6A0S9R9"
}

{
  "id": "ord_01HQZ6Q3F1WB4G3WQ7D6A0S9R9",
  "subMid": "100000000000002",
  "orderNo": "WEB-ORDER-10001",
  "mode": "HOSTED",
  "subject": "FOMO Pay Demo Order",
  "description": "Hosted checkout example",
  "amount": "10.00",
  "currencyCode": "SGD",
  "status": "CREATED",
  "createdAt": 1711977000,
  "notifyUrl": "https://merchant.example.com/payments/notify",
  "returnUrl": "https://merchant.example.com/payments/return",
  "backUrl": "https://merchant.example.com/payments/cancel",
  "primaryTransactionId": "txn_01HQZ6T50Y7Y8FQ40R8Q9MZ7XM",
  "url": "https://pay.fomopay.net/redirect/ord_01HQZ6Q3F1WB4G3WQ7D6A0S9R9"
}

{
  "hint": "req_01HQZ6PXG1PF1R2S1P33H0M2KJ",
  "code": "INVALID_REQUEST",
  "message": "orderNo already exists"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

6.2 Create an Order - (Direct Mode)

Request

Request Metadata

Name	Value
URL	`https://ipg.fomopay.net/api/orders`
Method	POST/PUT
Content-Type	application/json

⚠️	Connection error might occur during transaction creation. Do NOT create another transaction yet. Instead, retry using PUT method with the same requesting JSON to avoid duplicate charge. Multiple POST requests with the same orderNo will result in HTTP 409 error.

Authorization

Authorization

Authorization<token>

Set to Basic <Base64(MID:PSK)>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

mode*string

Must be HOSTED

orderNo*string

(1-64 UTF-8 characters) Unique order number generated by merchant

subMid?string

(PSP merchants only) Sub-Merchant ID assigned by FOMO Pay. Please DO NOT include this field if not instructed

subject*string

(1-64 UTF-8 characters) Short description of your order so your customers know what they are paying for. This may also be reflected on customer bank/wallet statements

description?string

(1-512 UTF-8 characters) Long description of your order

amount*string

To lowest currency unit e.g. 10.00 for SGD, 10 for JPY

currencyCode*string

ISO 4217 currency code e.g. SGD

notifyUrl*string

Must be a valid HTTP or HTTPS link. Must not contain userinfo, query or fragment. If using HTTPS, server must be configured with a valid certificate. See Transaction Status Update Notification

Formaturi

returnUrl*string

Link to redirect customer to after payment, may carry query or fragment

Formaturi

backUrl?string

Link to redirect customer to when user cancel the payment, may carry query or fragment. If not provided, customer will not be presented with a back-to-merchant button

Formaturi

sourceOfFunds?array<>

If provided, customer will be presented with requested payment methods only. See Appendix 1

transactionOptions?

See Appendix 4. Mandatory for payment methods in Appendix 4. Optional otherwise

mode*string

Must be DIRECT

orderNo*string

(1-64 UTF-8 characters) Unique order number generated by merchant

subMid?string

(PSP merchants only) Sub-Merchant ID assigned by FOMO Pay. Please DO NOT include this field if not instructed

subject*string

(1-64 UTF-8 characters) Short description of your order so your customers know what they are paying for. This may also be reflected on customer bank/wallet statements

description?string

(1-512 UTF-8 characters) Long description of your order

amount*string

To lowest currency unit e.g. 10.00 for SGD, 10 for JPY

currencyCode*string

ISO 4217 currency code e.g. SGD

notifyUrl*string

Must be a valid HTTP or HTTPS link. Must not contain userinfo, query or fragment. If using HTTPS, server must be configured with a valid certificate. See Transaction Status Update Notification

Formaturi

returnUrl?string

Link to redirect customer to after payment, may carry query or fragment. See Appendix 8

Formaturi

backUrl?string

Link to redirect customer to when user cancel the payment, may carry query or fragment

Formaturi

sourceOfFund*string

Specify a payment method. See Appendix 1

Value in

"ALIPAY" | "CARD" | "BROWSER" | "NETSPAY" | "WECHATPAY" | "UNIONPAY" | "GRABPAY" | "PAYNOW" | "SHOPEEPAY" | "ATOME" | "DPT" | "PAYPAL"

transactionOptions*

See Appendix 5

Response Body

`application/json`

Example:

curl -X POST "https://ipg.fomopay.net/api/orders" \  -H "Content-Type: application/json" \  -d '{    "mode": "HOSTED",    "orderNo": "WEB-ORDER-10001",    "subject": "FOMO Pay Demo Order",    "description": "Hosted checkout example",    "amount": "10.00",    "currencyCode": "SGD",    "notifyUrl": "https://merchant.example.com/payments/notify",    "returnUrl": "https://merchant.example.com/payments/return",    "backUrl": "https://merchant.example.com/payments/cancel",    "sourceOfFunds": [      "CARD",      "PAYNOW"    ]  }'

{
  "id": "ord_01HQZ6Q3F1WB4G3WQ7D6A0S9R9",
  "subMid": "100000000000002",
  "orderNo": "WEB-ORDER-10001",
  "mode": "HOSTED",
  "subject": "FOMO Pay Demo Order",
  "description": "Hosted checkout example",
  "amount": "10.00",
  "currencyCode": "SGD",
  "status": "CREATED",
  "createdAt": 1711977000,
  "notifyUrl": "https://merchant.example.com/payments/notify",
  "returnUrl": "https://merchant.example.com/payments/return",
  "backUrl": "https://merchant.example.com/payments/cancel",
  "primaryTransactionId": "txn_01HQZ6T50Y7Y8FQ40R8Q9MZ7XM",
  "url": "https://pay.fomopay.net/redirect/ord_01HQZ6Q3F1WB4G3WQ7D6A0S9R9"
}

{
  "id": "ord_01HQZ6Q3F1WB4G3WQ7D6A0S9R9",
  "subMid": "100000000000002",
  "orderNo": "WEB-ORDER-10001",
  "mode": "HOSTED",
  "subject": "FOMO Pay Demo Order",
  "description": "Hosted checkout example",
  "amount": "10.00",
  "currencyCode": "SGD",
  "status": "CREATED",
  "createdAt": 1711977000,
  "notifyUrl": "https://merchant.example.com/payments/notify",
  "returnUrl": "https://merchant.example.com/payments/return",
  "backUrl": "https://merchant.example.com/payments/cancel",
  "primaryTransactionId": "txn_01HQZ6T50Y7Y8FQ40R8Q9MZ7XM",
  "url": "https://pay.fomopay.net/redirect/ord_01HQZ6Q3F1WB4G3WQ7D6A0S9R9"
}

{
  "hint": "req_01HQZ6PXG1PF1R2S1P33H0M2KJ",
  "code": "INVALID_REQUEST",
  "message": "orderNo already exists"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

6.3 Query an Order

Request

Request Metadata

Name	Value
URL	`https://ipg.fomopay.net/api/orders/[orderId]` (Please replace [orderId] with id obtained in order creation response. Please note orderNo is different from orderId.)
Method	GET

Authorization

Authorization

Authorization<token>

Set to Basic <Base64(MID:PSK)>.

In: header

Path Parameters

orderId*string

Please replace [orderId] with id obtained in order creation response. Please note orderNo is different from orderId.

Response Body

`application/json`

Example:

{
  "id": "ord_01HQZ8BMN9KQXFM5T7RM0Q45Q0",
  "subMid": "100000000000002",
  "orderNo": "WEB-ORDER-10002",
  "mode": "DIRECT",
  "subject": "Direct payment example",
  "description": "Direct mode payment",
  "amount": "10.00",
  "currencyCode": "SGD",
  "status": "SUCCESS",
  "createdAt": 1711977300,
  "notifyUrl": "https://merchant.example.com/payments/notify",
  "returnUrl": "https://merchant.example.com/payments/return",
  "primaryTransactionId": "txn_01HQZ8CVAJX0B1AAYTRM4Q2FRJ",
  "url": "https://pay.fomopay.net/card/3ds/ord_01HQZ8BMN9KQXFM5T7RM0Q45Q0",
  "threeDSecure": true
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "req_01HQZ8M7SC7V7SCMNH3DG7J8WW",
  "code": "ORDER_NOT_FOUND",
  "message": "orderId does not exist"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

6.4 Create a Refund Transaction

Request

Request Metadata

Name	Value
URL	`https://ipg.fomopay.net/api/orders/[orderId]/transactions` (Please replace [orderId] with id obtained in order creation response. Please note orderNo is different from orderId.)
Method	POST/PUT
Content-Type	application/json

⚠️	Connection error might occur during transaction creation. Do NOT create another transaction yet. Instead, retry using PUT method with the same requesting JSON to avoid duplicate refund. Multiple POST requests with the same transactionNo will result in HTTP 409 error.

Authorization

Authorization

Authorization<token>

Set to Basic <Base64(MID:PSK)>.

In: header

Path Parameters

orderId*string

Please replace [orderId] with id obtained in order creation response. Please note orderNo is different from orderId.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

type*string

Must be REFUND

originalId?string

Original SALE transaction ID (field transactionsIds) obtained in order. If not provided, primaryTransactionId will be used

transactionNo*string

content/FOMO Pay API - Mobile Payment Integration (POS) v1.3.3 (en-US) .md, must be unique within the same order

amount*string

To lowest currency unit e.g. 10.00 for SGD, 10 for JPY. Must greater than 0 and not exceed the remaining amount of the original transaction

currencyCode*string

Must be the same as original transaction

subject*string

(1-64 UTF-8 characters) Short description describing this refund. This may also be reflected on customer bank/wallet statements

Response Body

`application/json`

Example:

curl -X POST "https://ipg.fomopay.net/api/orders/string/transactions" \  -H "Content-Type: application/json" \  -d '{    "type": "REFUND",    "originalId": "txn_01HQZ8CVAJX0B1AAYTRM4Q2FRJ",    "transactionNo": "REFUND-10001",    "amount": "10.00",    "currencyCode": "SGD",    "subject": "Refund for order WEB-ORDER-10001"  }'

{
  "id": "txn_01HQZ9M3DHK9C6SJQ5RHB94W8M",
  "type": "REFUND",
  "originalId": "txn_01HQZ8CVAJX0B1AAYTRM4Q2FRJ",
  "transactionNo": "REFUND-10001",
  "subject": "Refund for order WEB-ORDER-10001",
  "status": "CREATED",
  "createdAt": 1711977600,
  "amount": "10.00",
  "currencyCode": "SGD"
}

{
  "id": "txn_01HQZ9M3DHK9C6SJQ5RHB94W8M",
  "type": "REFUND",
  "originalId": "txn_01HQZ8CVAJX0B1AAYTRM4Q2FRJ",
  "transactionNo": "REFUND-10001",
  "subject": "Refund for order WEB-ORDER-10001",
  "status": "CREATED",
  "createdAt": 1711977600,
  "amount": "10.00",
  "currencyCode": "SGD"
}

{
  "hint": "req_01HQZ9H3A0N4X5P5A3D5SPX29V",
  "code": "REFUND_AMOUNT_EXCEEDED",
  "message": "refund amount exceeds remaining refundable amount"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

6.5 Query a Transaction

Request (For SALE/REFUND/DISPUTE transactions)

Request Metadata

Name	Value
URL	`https://ipg.fomopay.net/api/orders/[orderId]/transactions/[transactionId]` (Please replace [orderId] with id obtained in order creation response, [transactionId] with id obtained in transaction creation response. Please note orderNo is different from orderId and transactionNo is different from transactionId.)
Method	GET

Authorization

Authorization

Authorization<token>

Set to Basic <Base64(MID:PSK)>.

In: header

Path Parameters

orderId*string

Please replace [orderId] with id obtained in order creation response. Please note orderNo is different from orderId.

transactionId*string

Please replace [transactionId] with id obtained in transaction creation response. Please note transactionNo is different from transactionId.

Response Body

`application/json`

Example:

{
  "id": "txn_01HQZ9M3DHK9C6SJQ5RHB94W8M",
  "type": "REFUND",
  "originalId": "txn_01HQZ8CVAJX0B1AAYTRM4Q2FRJ",
  "transactionNo": "REFUND-10001",
  "subject": "Refund for order WEB-ORDER-10001",
  "status": "SUCCESS",
  "createdAt": 1711977600,
  "amount": "10.00",
  "currencyCode": "SGD",
  "sourceOfFund": "CARD"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "req_01HQZAGD7B2PQJ4GH9T2NEV5CS",
  "code": "TRANSACTION_NOT_FOUND",
  "message": "transactionId does not exist"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

6.6 Retrieve Orders

Request

Request Metadata

Name	Value
URL	`https://ipg.fomopay.net/api/orders?filter=[filter]&range=[range]&sort=[sort]`
Method	GET

Parameter	Format	Important Notes
`filter`	JSON object converted to string	Supported keys are `since`, `till`, `id`, `orderNo`, `mode`, and `status`. `till` must be greater than `since` and no more than 180 days later.
`range`	JSON list converted to string	Format is `[begin,end]`. `end` must be greater than `begin` and no more than `begin + 100`.
`sort`	JSON list converted to string	Must be `["createdAt","ASC"]` or `["createdAt","DESC"]`.

Query Encoding Example

Raw filter	`{"since":1577808000,"till":1577894400,"status":"SUCCESS"}`
Raw range	`[20,30]`
Raw sort	`["createdAt","ASC"]`
URL-encoded filter	`%7B%22since%22%3A1577808000%2C%22till%22%3A1577894400%2C%22status%22%3A%22SUCCESS%22%7D`
URL-encoded range	`%5B20%2C30%5D`
URL-encoded sort	`%5B%22createdAt%22%2C%22ASC%22%5D`
Final URL	`https://ipg.fomopay.net/api/orders?filter=%7B%22since%22%3A1577808000%2C%22till%22%3A1577894400%2C%22status%22%3A%22SUCCESS%22%7D&range=%5B20%2C30%5D&sort=%5B%22createdAt%22%2C%22ASC%22%5D`

Authorization

Authorization

Authorization<token>

Set to Basic <Base64(MID:PSK)>.

In: header

Query Parameters

filter*string

JSON object converted to string. Supported keys are:

since: Only take orders created after this time (inclusive)
till: Only take orders created before this time (exclusive). Must be greater than since and no more than since plus 180 days
id: Unique order ID generated by FOMO Pay, can be used for query
orderNo: Order number generated by merchant
mode: One of HOSTED and DIRECT
status: See Appendix 2

range*string

JSON list converted to string.

0: Number of orders to skip
1: Number of orders to skip plus number of orders to take. Must be greater than begin value and no more than begin value plus 100

sort*string

JSON list converted to string.

0: Must be createdAt
1: One of ASC and DESC

Response Body

`application/json`

Example:

curl -X GET "https://ipg.fomopay.net/api/orders?filter=%7B%22since%22%3A1577808000%2C%22till%22%3A1577894400%2C%22status%22%3A%22SUCCESS%22%7D&range=%5B20%2C30%5D&sort=%5B%22createdAt%22%2C%22ASC%22%5D"

[
  {
    "id": "ord_01HQZ8BMN9KQXFM5T7RM0Q45Q0",
    "subMid": "100000000000002",
    "orderNo": "WEB-ORDER-10002",
    "mode": "DIRECT",
    "subject": "Direct payment example",
    "description": "Direct mode payment",
    "amount": "10.00",
    "currencyCode": "SGD",
    "status": "SUCCESS",
    "createdAt": 1711977300,
    "notifyUrl": "https://merchant.example.com/payments/notify",
    "returnUrl": "https://merchant.example.com/payments/return",
    "primaryTransactionId": "txn_01HQZ8CVAJX0B1AAYTRM4Q2FRJ",
    "url": "https://pay.fomopay.net/card/3ds/ord_01HQZ8BMN9KQXFM5T7RM0Q45Q0",
    "threeDSecure": true
  }
]

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

Response Header	Value
Content-Type	application/json
Content-Range	`orders [begin]-[end]/[total]`

6.7 Retrieve Transactions in an Order

Request

Request Metadata

Name	Value
URL	`https://ipg.fomopay.net/api/orders/[orderId]/transactions?filter=[filter]&range=[range]&sort=[sort]`
Method	GET

Parameter	Format	Important Notes
`filter`	JSON object converted to string	Supported keys are `id`, `transactionNo`, `type`, and `status`.
`range`	JSON list converted to string	Format is `[begin,end]`. `end` must be greater than `begin` and no more than `begin + 100`.
`sort`	JSON list converted to string	Must be `["createdAt","ASC"]` or `["createdAt","DESC"]`.

Query Encoding Example

Raw filter	`{"type":"REFUND","status":"SUCCESS"}`
Raw range	`[5,10]`
Raw sort	`["createdAt","ASC"]`
URL-encoded filter	`%7B%22type%22%3A%22REFUND%22%2C%22status%22%3A%22SUCCESS%22%7D`
URL-encoded range	`%5B5%2C10%5D`
URL-encoded sort	`%5B%22createdAt%22%2C%22ASC%22%5D`
Final URL	`https://ipg.fomopay.net/api/orders/100500020200101000000000/transactions?filter=%7B%22type%22%3A%22REFUND%22%2C%22status%22%3A%22SUCCESS%22%7D&range=%5B5%2C10%5D&sort=%5B%22createdAt%22%2C%22ASC%22%5D`

Authorization

Authorization

Authorization<token>

Set to Basic <Base64(MID:PSK)>.

In: header

Path Parameters

orderId*string

Please replace [orderId] with id obtained in order creation response. Please note orderNo is different from orderId.

Query Parameters

filter*string

JSON object converted to string. Supported keys are:

id: Unique transaction ID generated by FOMO Pay, can be used for query
transactionNo: Transaction number generated by merchant
type: One of SALE, REFUND and DISPUTE
status: See Appendix 3

range*string

JSON list converted to string.

0: Number of transactions to skip
1: Number of transactions to skip plus number of transactions to take. Must be greater than begin value and no more than begin value plus 100

sort*string

JSON list converted to string.

0: Must be createdAt
1: One of ASC and DESC

Response Body

`application/json`

Example:

curl -X GET "https://ipg.fomopay.net/api/orders/string/transactions?filter=%7B%22type%22%3A%22REFUND%22%2C%22status%22%3A%22SUCCESS%22%7D&range=%5B5%2C10%5D&sort=%5B%22createdAt%22%2C%22ASC%22%5D"

[
  {
    "id": "txn_01HQZ9M3DHK9C6SJQ5RHB94W8M",
    "type": "REFUND",
    "originalId": "txn_01HQZ8CVAJX0B1AAYTRM4Q2FRJ",
    "transactionNo": "REFUND-10001",
    "subject": "Refund for order WEB-ORDER-10001",
    "status": "SUCCESS",
    "createdAt": 1711977600,
    "amount": "10.00",
    "currencyCode": "SGD",
    "sourceOfFund": "CARD"
  }
]

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

{
  "hint": "string",
  "code": "string",
  "message": "string"
}

Response Header	Value
Content-Type	application/json
Content-Range	`transactions [begin]-[end]/[total]`

6.8 Create Token for Credit Card

Request

Name	Value
URL	`https://ipg.fomopay.net/api/tokens?channel=CARD&subMid=[subMID]` [subMID] is an optional field.
Method	POST
Content-Type	application/json

Request Body

Key	Field Name	Field Type	Required	Comments
type	Tokenization Type	string	M	Must be CARD
card	Card Details	string	M	[See Appendix 5 Note 13]

Example Request Body

{
  "type": "card",
  "card": {
    "number": "4417123456789113",
    "expiryYear": "28",
    "expiryMonth": "08",
    "nameOnCard": "First Last Name"
  }
}

Response

Response Body

Key	Field Name	Field Type	Required	Comments
id	Token ID	string	M
type	Tokenization Type	string	M	Must be CARD
card	Card Details	string	M	[See Appendix 5 Note 13]

Response Status Code

HTTP status code	Comments
200	Successful
201	Created
400	Bad Request
401	Unauthorized Access
429	Too Many Requests
500	Server Error

Example Response Body

{
  "id": "c19JQHRQyWvgVNKPevtt25fR1p",
  "type": "card",
  "card": {
    "number": "441712xxxxxx9113",
    "expiryYear": "28",
    "expiryMonth": "08",
    "nameOnCard": "First Last Name"
  }
}

6.9 Get Token

Request

Name	Value
URL	`https://ipg.fomopay.net/api/tokens/[tokenId]?channel=CARD&subMid=[subMID]` [subMID] is an optional field.
Method	POST
Content-Type	application/json

Request Body

N/A

Response

Response Body

Key	Field Name	Field Type	Required	Comments
id	Token ID	string	M
type	Tokenization Type	string	M	Must be card
card	Card Details	string	M	[See Appendix 5 Note 13]

Response Status Code

HTTP status code	Comments
200	Successful
201	Created
400	Bad Request
401	Unauthorized Access
429	Too Many Requests
500	Server Error

6.10 Delete Token

Request

Name	Value
URL	`https://ipg.fomopay.net/api/tokens/[tokenId]?channel=CARD&subMid=[subMID]` [subMID] is an optional field.
Method	DELETE
Content-Type	application/json

Request Body

N/A

Response

Response Body

N/A

Response Status Code

HTTP status code	Comments
204	No Content
400	Bad Request
401	Unauthorized Access
429	Too Many Requests
500	Server Error

7. Transaction Status Update Notification

A transaction status update will be sent to client server when any transaction status has changed.

7.1 Security

⚠️	HTTP header field (aka header key) is case-insensitive (https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2). While FOMO Pay will try to ensure header fields (not header value) in lower case, please make sure your code will also work when you see header fields in upper case.

FOMO Pay will send notification to webhook URL using HTTP POST method in the following format:

Headers
Field	Value
Content-Type X-FOMOPay-Authorization	application/json FOMOPAY1-HMAC-SHA256 <HMACCredentials>
Body
`<payload>`

The <HMACCredentials> is in following format (field order might change):

Version=1.1,Credential=<MID>,Nonce=<Nonce>,Timestamp=<Timestamp>,Signature=<Signature>

The verification algorithm is as follows:

Client extracts the following HTTP headers from HTTP request.

Version	[version]
Credential	[credential]
Nonce	[nonce]
Timestamp	[timestamp]
Signature	[signature]

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

[version] is 1.1
[credential] is your <MID>
[nonce] has a length between 16-64 and was not used by gateway notification within 300 seconds
[timestamp] (UNIX timestamp in seconds) within ±300 seconds of current time

Client reads request body [payload] from HTTP request.
Client concatenates [payload], [timestamp] and [nonce] to get string [message] to be verified.
Client calculate signature (in lowercase hexadecimal) with HMAC-SHA256 using <PSK> as key and [message] as message.
Reject if the calculated signature does not match [signature].

Example:

Merchant setup:

Key	Value
<MID>	100000000000001
<PSK>	E00F270DE323E2B187532D8E4B306EB2841AF0BFF08132BAB7F0E62BED6419BB

Notification received at notifyUrl:

Assume current time is 1/Jan/2020 00:02 (GMT+8)

Headers (irrelevant headers omitted)
Field	Value
content-type x-fomopay-authorization	application/json FOMOPAY1-HMAC-SHA256 Version=1.1,Credential=100000000000001,Nonce=b39c7ec8fa58be1041eb3921c9ceb98b,Timestamp=1577808000,Signature=596ecb8f2636ff88eea7b4d4b4841ae822eaa4f1eea9cb1ce1da2953c9db0b05
Body
`{"orderId":"100500020200101000000000","orderNo":"order-20200101-000005","transactionId":"100510120200101000000000","transactionNo":"partialrefund-02"}`

Verification:

Client extracts the following data from HTTP request.

[version] = 1.1
[credential] = 100000000000001
[nonce] = b39c7ec8fa58be1041eb3921c9ceb98b
[timestamp] = 1577808000
[signature] = 596ecb8f2636ff88eea7b4d4b4841ae822eaa4f1eea9cb1ce1da2953c9db0b05

Verify the following conditions.

[version] is 1.1 (true)
[credential] is your <MID> (true)
[nonce] has a length between 16-64 and was not used by gateway notification within 300 seconds (true)
[timestamp] (UNIX timestamp in seconds) within ±300 seconds of current time (true)

Client reads request body [payload] from HTTP request (please DO NOT parse the JSON).

{"orderId":"100500020200101000000000","orderNo":"order-20200101-000005","transactionId":"100510120200101000000000","transactionNo":"partialrefund-02"}

Client concatenates [payload], [timestamp] and [nonce] to get string [message] to be verified.

{"orderId":"100500020200101000000000","orderNo":"order-20200101-000005","transactionId":"100510120200101000000000","transactionNo":"partialrefund-02"}1577808000b39c7ec8fa58be1041eb3921c9ceb98b

Client calculates signature (in lowercase hexadecimal) with HMAC-SHA256 using <PSK> as key and [message] as message.

Calculated signature = 596ecb8f2636ff88eea7b4d4b4841ae822eaa4f1eea9cb1ce1da2953c9db0b05

Reject if the calculated signature does not match [signature].

Calculated signature matches the [signature] received. Merchant server shall reply with HTTP 200 OK immediately at this point. Please continue your business logic after the reply is sent.

7.2 Notification Request

POST notifyUrl
Content-Type: application/json

notifyUrl is in order creation request.

Key	Field Name	Field Type	Required	Comments
orderId	FOMO Pay order ID	string	M	FOMO Pay ID of the order containing the transaction
orderNo	Merchant order number	string	M	Merchant order number of the order containing the transaction
transactionId	FOMO Pay transaction ID	string	M	Transaction ID that triggered the notification
transactionNo	Merchant transaction number	string	O	Merchant transaction number for merchant created transactions. Not applicable otherwise

7.3 Notification Response

HTTP Status Code

200

⚠️

Client must respond with HTTP status code 200 as early as possible before any other processing logic. Gateway will retry immediately for up to 3 times when HTTP status code is not 200, response not received in 20 seconds, connection dropped or response body too large. Gateway will suspend (for 5 minutes) sending notification to client if more than 3 notifications fail (notifications for same transaction is counted only once) in 1 minute. All notifications during suspension will be discarded.

HTTP redirection will NOT be followed. HTTP status code 301 (Moved Permanently) or 302 (Found) will be considered as notification failure.

HTTP status code 204 (No Content) will also be considered as notification failure.

Response HTTP body shall not exceed 5 KiB in size, its content will be ignored.

Merchant server shall query latest order status / transaction status using orderId and transactionId received depending on needs.

8. Fraud Detection

⚠️	Fraud detection is only enabled for merchants who are classified as high-risk by FOMO Pay. Merchants who are not classified as high-risk can skip this section.

High-risk merchants who need to process card payments and perform fraud detection might be required to provide the following fields, and we will handle the fraud detection process.

This section is intended to provide specific clarification on the fraud detection process. These fields are specifically highlighted here as they are required for enabling fraud detection. For detailed parameter integration, please refer to Appendices 9.4 and 9.5.

8.1 Direct Mode

Transaction Options
Key	Field Type	Required	Comments
payerEmail	string	M	Payer's email.
payerUserAgent	string	M	Payer's browser information. See appendix 9.7 - PayerUserAgent
shippingAddress	object	O	Required for physical goods; provides shipping details. See appendix 9.6 - TPaymentAddress
payerIP	string	M

8.2 Hosted Mode

Transaction Options
Key	Field Type	Required	Comments
payerEmail	string	M	Payer's email.

9. Appendix

9.1 List of Source of Fund

⚠️	Depending on your arrangement with FOMO Pay, your account might not have all the following source of funds.

Source of Fund	Comment
ALIPAY	Alipay. Supported types: WEB (Web payment) WAP (Wap payment) APP (In-App payment) MINI_APP (Mini-program payment)
CARD	Card payment. Supported card brands: Visa Mastercard American Express Discover Diners Club International
BROWSER	Browser payment. Supported types: Apple Pay Google Pay Microsoft Pay Other browser payments conforming to Payment Request API
NETSPAY	NETS QR code payment
WECHATPAY	WeChat Pay. Supported types: NATIVE (QR code payment) JSAPI (Web payment *in WeChat App) APP (In-App payment)* WXA (Mini-program payment) MWEB (H5 payment)
UNIONPAY	UnionPay online payment (UPOP)
GRABPAY	GrabPay web payment
PAYNOW	PayNow QR code payment
SHOPEEPAY	ShopeePay. Supported types: MPM (Merchant presented QR code payment) APP (In-App payment or mobile web payment)
ATOME	Atome (3 interest-free installments)
DPT	Digital Payment Token payment. Supported types: BTC (Bitcoin) ETH (Ethereum) USDT (Tether, via Ethereum/ERC20 or Tron/TRC20) USDC (USD Coin, via Ethereum/ERC20 or Tron/TRC20)
PAYPAL	Checkout with PayPal

9.2 Order Status

Status	Comment
CREATED	Order has been created and is ready for payment or payment is being processed
FAIL	Order has failed due to linked primary SALE transaction (as indicated in primaryTransactionId) failed
ERROR	The order is in a status that cannot be recovered automatically, please contact FOMO Pay
SUCCESS	Order has been paid successfully and no refund has been created (for primary transaction). Related SALE transaction is indicated in primaryTransactionId
REFUND	Order has been previously paid successfully and its primary transaction (as indicated in primaryTransactionId) has now been (partially) refunded
CLOSED	Order is closed, no new SALE transaction can be created

9.3 Transaction Status

Status	Comment
CREATED	For type SALE: Transaction has been created and waiting for payment or payment is being processed. Please DO NOT create another payment yet to avoid duplicate charge For type REFUND: Refund has been submitted and is being processed. Please DO NOT create another refund yet to avoid duplicate refund
FAIL	For type SALE: Payment failed. Any charges will be automatically reversed or refunded if already captured For type REFUND: Refund failed
ERROR	The transaction is in a status that cannot be recovered automatically, please contact FOMO Pay
SUCCESS	For type SALE: Transaction has been captured successfully For type REFUND: Transaction has been refunded successfully
REFUND	For type SALE: Transaction was previously paid successfully and there are refund transactions created for this sale transactions (does not indicate if the refund transactions are successful) For type REFUND: Not applicable
CLOSED	For type SALE: Transaction is closed (e.g. transaction not paid within timeout) For type REFUND: Not applicable
VOID	For type SALE: Transaction has been voided For type REFUND: Not applicable

9.4 Transaction Options (HOSTED mode)

⚠️

Missing transactionOptions while creating a HOSTED mode order will not fail order creation. However, when a customer selects a payment method which requires corresponding transactionOptions, the payment will fail. Other payment methods (if any) will not be affected if they don’t require any transactionOptions.

SourceOfFund	Transaction Options
	Key	Field Type	Required	Comment
ATOME	payerName	string	M	Payer full name
	payerEmail	string	O	Payer email address
	payerPhone	string	M	Payer phone number
	shippingAddress	object	M	[Note 1]
	billingAddress	object	M	[Note 1]
	paymentItems	object[]	M	[Note 1]
DPT	[Note 2]	-	-	-
PAYPAL	shippingAddress	object	O	[Note 1]
PAYPAL	paymentItems	object[]	O	[Note 1]
CARD(Fraud Detection)	payerEmail	string	M	Payer email address

[1] Please find below for data types for each key.

Key	Field Type
shippingAddress	See Appendix 6 - TPaymentAddress
billingAddress	See Appendix 6 - TPaymentAddress
paymentItems	See Appendix 6 - TPaymentItem

[2] Please approach FOMO Pay for detailed KYC requirements.

9.5 Transaction Options (DIRECT mode)

SourceOfFund	Transaction Options				Response Fields
SourceOfFund	Key	Field Type	Required	Comment	threeDSecure	url	codeUrl
ALIPAY (WEB)	txnType	string	M	WEB	X	M	X
ALIPAY (WEB)	timeout	number	M	60-7200	X	M	X
ALIPAY (WAP)	txnType	string	M	WAP	X	M	X
	osType	string	M	One of IOS ANDROID
	timeout	number	M	60-7200
ALIPAY (APP)	txnType	string	M	APP	[Note 10]
	osType	string	M	One of IOS ANDROID
	timeout	number	M	60-7200
ALIPAY (MINI_APP)	txnType	string	M	MINI_APP	[Note 11]
	paymentMethodType	string	M	[Note 9]
	timeout	number	M	60-7200
CARD	timeout	number	M	60-7200	M	C	X
	expiryYear	string	M	00-99
	expiryMonth	string	M	1-12 [Note 1]
	nameOnCard	string	M
	number	string	M
	securityCode	string	M
	ip	string	M	Customer IP
	threeDSecure	string	O	One of enforced auto disabled [Note 2]
CARD (Fraud Detection)	timeout	number	M	60-7200
	expiryYear	string	M	00-99
	expiryMonth	string	M	1-12 [Note 1]
	nameOnCard	string	M
	number	string	M
	securityCode	string	M
	ip	string	M	Customer IP
	threeDSecure	string	O	One of enforced auto disabled [Note 2]

	payerUserAgent	string	M	See Appendix 9.7
	payerIP	string	M
	payerName	string	O
	payerEmail	string	M	Payer email address
	payerPhone	string	O
	shippingAddress	object	O	[Note 8]
	billingAddress	object	O	[Note 8]
	paymentItems	object[]	O	[Note 8]
	payerType	string	O	[Note 16]
	payer	object	C	[Note 17]
CARD (CIT Format)	timeout	number	M	60-7200
	ip	string	M	Customer IP
	threeDSecure	string	O	One of enforced auto disabled [Note 2]
	txnType	string	M	REGULAR [Note 12]
	card	object	C	[Note 13]
	token	object	C	[Note 13]
CARD (CIT Format and Fraud Detection)	timeout	number	M	60-7200
	ip	string	M	Customer IP
	threeDSecure	string	O	One of enforced auto disabled [Note 2]
	txnType	string	M	REGULAR [Note 12]
	card	object	C	[Note 13]
	token	object	C	[Note 13]
	payerUserAgent	string	M	See Appendix 9.7
	payerIP	string	M
	payerName	string	O
	payerEmail	string	M	Payer email address
	payerPhone	string	O
	shippingAddress	object	O	[Note 8]
	billingAddress	object	O	[Note 8]
	paymentItems	object[]	O	[Note 8]
	payerType	string	O	[Note 16]
	payer	object	C	[Note 17]
CARD (MIT Format) [Note 15]	timeout	number	M	60-7200
	ip	string	M	Customer IP
	threeDSecure	string	C	[Note 14]
	txnType	string	C	One of RECURRING UNSCHEDULED
	card	object	C	[Note 13]
	token	object	C	[Note 13]
	merchantInitiated	boolean	C	[Note 14]
	merchantInitiatedReason	string	C	[Note 14]
	originalId	string	C	[Note 14]
CARD (MIT Format and Fraud Detection) [Note 15]	timeout	number	M	60-7200
	ip	string	M	Customer IP
	threeDSecure	string	C	[Note 14]
	txnType	string	C	One of RECURRING UNSCHEDULED
	card	object	C	[Note 13]
	token	object	C	[Note 13]
	merchantInitiated	boolean	C	[Note 14]
	merchantInitiatedReason	string	C	[Note 14]
	originalId	string	C	[Note 14]

	payerUserAgent	string	M	See Appendix 9.7
	payerIP	string	M
	payerName	string	O
	payerEmail	string	M	Payer email address
	payerPhone	string	O
	shippingAddress	object	O	[Note 8]
	billingAddress	object	O	[Note 8]
	paymentItems	object[]	O	[Note 8]
	payerType	string	O	[Note 16]
	payer	object	C	[Note 17]
NETSPAY	timeout	number	M	60-7200	X	M	X
WECHATPAY (NATIVE)	txnType	string	M	NATIVE	X	X	M
WECHATPAY (NATIVE)	timeout	number	M	60-7200	X	X	M
WECHATPAY (JSAPI)	txnType	string	M	JSAPI	X	M	X
	timeout	number	M	60-7200
	openid	string	M	[Note 3]
	openidEncrypted	boolean	O	Default false [Note 3]
	ip	string	M	Customer IP
	openidType	string	O	Values: auto (default), primary, secondary
WECHATPAY (APP)	txnType	string	M	APP	[Note 4]
WECHATPAY (APP)	timeout	number	M	60-7200	[Note 4]
WECHATPAY (WXA)	txnType	string	M	WXA	[Note 5]
	timeout	number	M	60-7200
	openid	string	M	[Note 3]
WECHATPAY (MWEB)	txnType	string	M	MWEB	X	M	X
	timeout	number	M	60-7200
	ip	string	M	Customer IP
UNIONPAY (WEB)	txnType	string	M	WEB	X	M	X
UNIONPAY (WEB)	timeout	number	M	60-7200	X	M	X
UNIONPAY (QRCODE)	txnType	string	M	QRCODE	X	X	M
UNIONPAY (QRCODE)	timeout	number	M	60-7200	X	X	M
GRABPAY	timeout	number	M	60-7200	X	M	X
PAYNOW	timeout	number	M	60-7200	X	X	M
SHOPEEPAY (MPM)	txnType	string	M	MPM	X	X	M
SHOPEEPAY (MPM)	timeout	number	M	60-7200	X	X	M
SHOPEEPAY (APP)	txnType	string	M	APP	[Note 6]
	timeout	number	M	60-3600
	platformType	string	M	One of app pc mweb
ATOME	timeout	number	M	60-7200	X	M	X
	payerName	string	M	Full name
	payerEmail	string	O	Email address
	payerPhone	string	M	Phone number
	shippingAddress	object	M	[Note 8]
	billingAddress	object	M	[Note 8]
	paymentItems	object[]	M	[Note 8]
DPT	timeout	number	M	60-7200	X	M	X
DPT	[Note 7]	-	-	-	X	M	X
PAYPAL	txnType	string	M	WEB	X	M	X
	timeout	number	M	60-7200
	shippingAddress	object	O	[Note 8]
	paymentItems	object[]	O	[Note 8]

[*] Please include returnUrl in request if url in Response Fields is mandatory or conditional.

[*] Transaction timeout may not work with some of the source of funds due to the following reasons. Do not infer transaction status even if the transaction appears to be timed out. Instead, always use transaction status retrieved from FOMO Pay.

Some sourceOfFunds use different start time from order creation time for timeout calculations (which renders timeouts less useful)
Some sourceOfFunds accept timeouts but do not follow timeouts accurately
Some sourceOfFunds do not accept timeouts at all

[1] Zero-padding or leading zero is a valid and supported convention for representing months. E.g. Both “8” and “08” (for August) are supported.

[2] Description of 3-D Secure Options.

Option	Comment
auto	(Default to this value if not provided.) The merchant chooses to use FOMO Pay 3-D Secure rules. Response threeDSecure flag can be true or false depending on evaluation result. (Indicative Mode only: Indicates merchant has no preference on 3-D Secure, check threeDSecure in response for final decision.)
enforced	Requires customers complete 3-D Secure challenge before pre-authorization. Reject the payment if the customer fails to complete the challenge or 3-D Secure is not supported by the card issuer. Response threeDSecure will be true. (Indicative Mode only: Indicates merchant prefers payment with 3-D Secure enabled, check threeDSecure in response for final decision.)
disabled	Indicates the payment shall be pre-authorized without 3-D Secure challenge. Reject the payment if 3-D Secure is required by the card issuer. Response threeDSecure will be false. (Indicative Mode only: Indicates merchant prefers payment with 3-D Secure disabled, check threeDSecure in response for final decision.)

[3] Please approach FOMO Pay for configuration and instructions on getting openid.

[4] Response field will be an object named payReq in the following format.

Key	Field Name	Field Type	Required	Comments
appid	WeChat App ID	string	M	Please approach FOMO Pay for App ID binding
partnerid	WeChat MID	string	M	Please approach FOMO Pay for MID registration or binding
prepayid	Prepay session ID	string	M
package	Extended data	string	M
noncestr	Cryptographic nonce	string	M
timestamp	Unix timestamp	string	M
sign	Signature	string	M

[5] Response field will be an object named payReq in the following format.

Key	Field Name	Field Type	Required	Comments
appid	WeChat App ID	string	M	Please approach FOMO Pay for App ID binding
timestamp	Unix timestamp	string	M
noncestr	Cryptographic nonce	string	M
package	Extended data	string	M
signType	Hashing algorithm used for signing	string	M
paysign	Signature	string	M

[6] Please include returnUrl in request. Response field will be an object named payReq in the following format.

Key	Field Name	Field Type	Required	Comments
app	Mobile deep link	string	M	Mobile deep link to launch Shopee App
http	Universal link	string	M	Redirect to a web page which will detect and launch Shopee App if installed

[7] Please approach FOMO Pay for detailed KYC requirements.

[8] Please find data types below for each key.

Key	Field Type
shippingAddress	See Appendix 6 - TPaymentAddress
billingAddress	See Appendix 6 - TPaymentAddress
paymentItems	See Appendix 6 - TPaymentItem

[9] Please find the allowed paymentMethodType below.

paymentMethodType	Wallet that hosts the mini program
TRUEMONEY	TrueMoney Wallet
ALIPAY_HK	AlipayHK Wallet
TNG	Touch 'n Go eWallet
ALIPAY_CN	AlipayCN Wallet
GCASH	GCash Wallet
DANA	DANA Wallet

[10] Response field will be an object named payReq in the following format.

Key	Field Name	Field Type	Required	Comments
normalUrl	Payment URL	string	M	(Non-SDK integration solution) The payment URL that redirects users to a WAP or Web page in the browser or in the WebView
paymentData	Payment data for SDK	string	C	(SDK integration solution) Returned if the merchant app has integrated the Alipay+ client SDK. Contains payment data that is used by the Alipay+ client SDK to render the checkout page

[11] Response field will be an object named payReq in the following format.

Key	Field Name	Field Type	Required	Comments
normalUrl	Payment data	string	M	Payment data for mini program

[12] txnType options will be based on whether a regular card transaction, customer-initiated transaction or a merchant-initiated transaction is done.

Nature of Transaction	txnType	Comments
Customer-Initiated	REGULAR	For customer-transaction with or without token either REGULAR or can leave field as undefined
Merchant-Initiated	RECURRING	For eventual merchant-initiated transaction, starting from the first transaction must use either RECURRING or UNSCHEDULED
Merchant-Initiated	UNSCHEDULED

[13] Data types and fields for the card and token object. The card and token objects are used to initiate CIT or MIT transactions. It is recommended that only one; either the card or token object be sent at payload. If both are sent, the card object will take precedence to initiate the card transaction.

Card

Key	Field Type	Required	Comments
number	string	M
expiryYear	string	M	00-99
expiryMonth	string	M	Zero-padding is supported. 1-12.
securityCode	string	O
nameOnCard	string	O

Token

Key	Field Type	Required	Comments
id	string	M	Tokenized card details
securityCode	string	O

[14] Additional fields and specification for threeDSecure field for MIT.

Key	Field Type	Required	Comments
merchantInitiated	boolean	C	Must be false for 1st transaction. Must be true for subsequent transactions (2nd, 3rd, 4th etc.)
merchantInitiatedReason	string	C	Must be present for subsequent transactions. One of below: DELAYED_CHARGE RESUBMISSION NO_SHOW REAUTHORIZATION
originalId	string	C	Must be present for subsequent transactions. This refers to the primaryTransactionId for the 1st transaction.
threeDSecure	string	C	Must be enforced for the 1st transaction. Must be disabled for subsequent transactions.

[15] Sample request body for MITs

// 1st Transaction
// where threeDSecure is enforced and merchantInitiated is false
{
  "mode": "DIRECT",
  "orderNo": "TEST_MIT001",
  "subject": "FOMOPAY UAT TEST",
  "description": "FOMOPAY UAT TEST",
  "backUrl": "https://fomopay.com/",
  "returnUrl": "https://fomopay.com/",
  "notifyUrl": "http://localhost:443",
  "currencyCode": "SGD",
  "amount": "12.34",
  "sourceOfFund": "CARD",
  "transactionOptions": {
    "timeout": 300,
    "txnType": "RECURRING",
    "ip": "167.163.152.53",
    "threeDSecure": "enforced",
    "merchantInitiated": false,
    "token": {
      "id": "c1FbwzRxQ6xMj3EWvydzkV0SkA"
    }
  }
}

// 2nd Transaction and onwards
// where threeDSecure is disabled, merchantInitiated is true
// merchantInitiatedReason and originalId (primaryTransactionId of the 1st transaction) is required for 2nd transaction onwards
{
  "mode": "DIRECT",
  "orderNo": "TEST_MIT002",
  "subject": "FOMOPAY UAT TEST",
  "description": "FOMOPAY UAT TEST",
  "backUrl": "https://fomopay.com/",
  "returnUrl": "https://fomopay.com/",
  "notifyUrl": "http://localhost:443",
  "currencyCode": "SGD",
  "amount": "12.34",
  "sourceOfFund": "CARD",
  "transactionOptions": {
    "timeout": 300,
    "txnType": "RECURRING",
    "ip": "167.163.152.53",
    "threeDSecure": "disabled",
    "merchantInitiated": true,
    "merchantInitiatedReason": "NO_SHOW",
    "token": {
      "id": "c1FbwzRxQ6xMj3EWvydzkV0SkA"
    },
    "originalId": "100510020231010227133206"
  }
}

[16] Please find the allowed payerType below.

payerType	Comment
INDIVIDUAL	Fields applicable for individual payers.
BUSINESS	Fields applicable for business payers.

[17] payer fields based on payerType.

payer

See Appendix 6 - TIndividual

See Appendix 6 - TBusiness

9.6 Data Types

TPaymentAddress

Key	Field Type	Required	Comments
city	string	M	Name of city or town
country	string	M	Country code in ISO-3166-1 alpha-2
dependentLocality	string	M	Name of dependent locality or sublocality within a city
organization	string	M	Name of the organization
phone	string	M	Telephone number of the recipient or contact person
postalCode	string	M	Postal code
recipient	string	M	Name of the recipient, purchaser, or contact person at the payment address
region	string	M	Top level administrative subdivision of the country, for example a state, province, oblast, or prefecture
addressLine	string[]	M	An array of string providing each line of the address

TPaymentItem

Key	Field Type	Required	Comments
label	string	M	Name of the item
amount	object	M	Price of items [Note 1]
sku	string	M	Stock-keeping unit
quantity	number	M	Number of items

[1] Please see below for amount format.

Key	Field Name	Field Type	Required	Comments
currency	Currency code	string	M	ISO 4217 currency code e.g. SGD Must use the same currency code as in order
value	Amount	string	M	To lowest currency unit e.g. 10.00 for SGD, 10 for JPY

TBusiness

Key	Field Type	Required	Comments
name	string	M	Name of the business
id	object	M	See Appendix 6 - TBusinessID
address	object	M	See Appendix 6 - TBusinessAddress
placeOfIncorporation	string	M	Place of incorporation

TBusinessID

Key	Field Type	Required	Comments
type	string	M	"LEI","REGISTRATION_ID"
value	string	M
countryOfIssue	string	M	Country code in ISO-3166-1 alpha-2

TBusinessAddress

Key	Field Type	Required	Comments
city	string	M	Name of city or town
country	string	M	Country code in ISO-3166-1 alpha-2
dependentLocality	string	O	Name of dependent locality or sublocality within a city
postalCode	string	M	Postal code
region	string	O	Top level administrative subdivision of the country, for example a state, province, oblast, or prefecture
addressLine	string[]	M	An array of string providing each line of the address

TIndividual

Key	Field Type	Required	Comments
name	string	M	Name
id	object	M	See Appendix 6 - TIndividualID
address	object	M	See Appendix 6 - TIndividualAddress
dateOfBirth	string	M	e.g. 2012-12-01
placeOfBirth	string	M

TIndividualID

Key	Field Type	Required	Comments
type	string	M	"ID_CARD","PASSPORT"
value	string	M
countryOfIssue	string	M	Country code in ISO-3166-1 alpha-2

TIndividualAddress

Key	Field Type	Required	Comments
city	string	M	Name of city or town
country	string	M	Country code in ISO-3166-1 alpha-2
dependentLocality	string	O	Name of dependent locality or sublocality within a city
postalCode	string	M	Postal code
region	string	O	Top level administrative subdivision of the country, for example a state, province, oblast, or prefecture
addressLine	string[]	M	An array of string providing each line of the address

9.7 PayerUserAgent

Payer's http user-agent.

e.g.

"Mozilla/5.0 (iPhone; CPU iPhone OS 17_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.6 Mobile/15E148 Safari/604.1"

9.8 returnUrl

The returnUrl parameter behaves differently for WeChatPay's JSAPI and MWEB integration modes.

1. JSAPI Mode：Optional

If provided:
FOMO Pay will host a payment landing page. After the user completes the payment on this page, they will be redirected to the specified returnUrl.
If not provided:
FOMO Pay will directly return the necessary parameters (TPayReqJsapi) for initiating the payment through WeChat's JSAPI. Merchants need to handle the payment flow using these parameters.

2. MWEB Mode：Not Supported

The returnUrl parameter cannot be passed in MWEB mode. If provided, the request will be rejected.

For other sources of fund, returnUrl in request should be included if url in Response Fields is mandatory or conditional. See appendix 9.5.

Web Integration

1. Change Log

1.1 V1.0.0

1.2 V1.0.1-V1.0.7

1.3 V1.0.9

1.4 V1.0.10

1.5 V1.0.11

1.6 V1.0.12

1.7 V1.1.0

1.8 V1.1.1

1.9 V1.1.2

2. PCI Compliance

3. Sequence Diagram

3.1 Hosted Mode

3.2 Direct Mode

4. Security and Encryption

4.1 Transport Security

4.2 Message Authentication

5. Symbols and Abbreviated Terms

5.1 Required Flag

6. Message Types and Specification

6.1 Create an Order (Hosted Mode)

Request

200application/json

201application/json

400application/json

401application/json

403application/json

409application/json

415application/json

429application/json

500application/json

Hosted mode

Direct mode

6.2 Create an Order - (Direct Mode)

Request

200application/json

201application/json

400application/json

401application/json

403application/json

409application/json

415application/json

429application/json

500application/json

Hosted mode

Direct mode

6.3 Query an Order

Request

200application/json

400application/json

403application/json

404application/json

429application/json

500application/json

6.4 Create a Refund Transaction

Request

200application/json

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

412application/json

415application/json

429application/json

500application/json

6.5 Query a Transaction

Request (For SALE/REFUND/DISPUTE transactions)

200application/json

400application/json

401application/json

403application/json

404application/json

412application/json

429application/json

500application/json

6.6 Retrieve Orders

Request

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`