API docs by Redocly

Spiral Checkout (2.0.0)

Download OpenAPI specification:Download

E-mail: support@eftsolutions.freshdesk.com

The API used for online payment by Spiral Checkout

API Call (Merchant to Spiral)

API call request from merchant to Spiral

Transaction Operations

The API call for transaction operation, includes Sale, SaleSession, Auth, AuthSession, Capture and Refund

path Parameters
clientId
required
string
Example: merchantOne

The ID of the account assigned by Spiral

merchantRef
required
string
Example: 1627965086558-1

The reference created by merchants on this order, must be unique.

header Parameters
Spiral-Request-Datetime
string
Example: 2021-08-03T04:31:26.558Z

The UTC time in %Y-%m-%d'T'%H:%M:%S'Z' format when the request/response is composed

Spiral-Client-Signature
string
Example: KsUJDwropdIGZ/G6vVEXG4FiEOw/+u6dzeuYaFCxnulnJp9vrhyxP0wj0HxzXx/EQyOD6qq5VJFlFvw0Cez1/qnwpoQPHONOE0aQLcxFcEa7TpIU33Ihy3z0lMSRq5xVreuYSawRQi1kVOpVPtLPPBRbk/hYc1NqzQ/gVnwTgHOkP8Cuk4G2e1mV0sq7GISNcvilvOWGoD6DT0Qpln1Tz76ttEn+9dzAzq8G0dLAI2Xp7fJhKGjQNR+aaWibqq8x+FJFafZpFpMP835QUsZmcC740oV/nL2O0LpDpCrTGd5VjIBQa7hJ3q0m4MtEqiWKfTdQ1gZM6FJ+eFzS72qEOw==

Signature of the client

Request Body schema: application/json
One of
clientId
required
string

The ID of the account assigned by Spiral

merchantRef
required
string

The reference created by merchants on this order, must be unique.

cmd
required
string

indication of the operation SALE / AUTH / SALESESSION / AUTHSESSION

type
required
string

transaction type, details refer to the Support Types page.

amt
required
number

transaction amount

goodsName
required
string

Goods title

goodsDesc
string

Description of Goods

channel
string

To indicate the channel of the payment, should be APP or WEB in requst

cardToken
string

Only be submitted for direct payment as a substitution of the card numbers. Need to provide the cardTokenSrc at the same time.

cardTokenSrc
string

The source of the card tokens, must be used with cardToken. Can be SPIRAL, APPLE_PAY, GOOGLE_PAY

successUrl
string <uri>

The page to be redirect on the browser when payment completed successfully

failureUrl
required
string <uri>

The page to be redirect on the browser when payment did not complete successfully

webhookUrl
required
string <uri>

The endpoint of the payment result notification

metadata
string

A json object that contains the user defined data. The data will not be used for the authorization or any other operation of the payment. It will be stored in the database and be further used for reporting or query.

duration
number

number of days the qrCode will be valid (should be only used by the FPS bill payment sending via mail)

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
Example
{
  • "dateTime": "string",
  • "clientId": "testAccount",
  • "merchantRef": "Order-1001",
  • "cmd": "SALE",
  • "orderId": "0c170aa0-7c5a-4b32-9529-102aaa454f51",
  • "type": "VM",
  • "txnId": "5fe3368b-453a-4cc1-81f1-4c2054cb4ca4",
  • "txnType": "SALE",
  • "merchantId": "H345678H3620000",
  • "hostId": "1",
  • "card": "VISA",
  • "status": "Approved",
  • "amt": 100.5,
  • "resp": "APPROVED",
  • "hostTime": "2021-02-03T17:29:09+08:00",
  • "appCode": "123456",
  • "pan": "444000xxxxxx0010",
  • "expDate": "1027",
  • "respMsg": "ok",
  • "goodsName": "Sunmi T2 Lite",
  • "goodsDesc": "Electronic product",
  • "cardToken": 4444555566667777,
  • "cardTokenSrc": "SPIRAL",
  • "metadata": {
    },
  • "paidAmt": 100.5,
  • "orderAmt": 100.5,
  • "currency": "HKD"
}

Transaction Query

The API call for query transaction status

path Parameters
clientId
required
string
Example: merchantOne

The ID of the account assigned by Spiral

merchantRef
required
string
Example: 1627965086558-1

The reference created by merchants on this order, must be unique.

header Parameters
Spiral-Request-Datetime
string
Example: 2021-08-03T04:31:26.558Z

The UTC time in %Y-%m-%d'T'%H:%M:%S'Z' format when the request/response is composed

Spiral-Client-Signature
string
Example: KsUJDwropdIGZ/G6vVEXG4FiEOw/+u6dzeuYaFCxnulnJp9vrhyxP0wj0HxzXx/EQyOD6qq5VJFlFvw0Cez1/qnwpoQPHONOE0aQLcxFcEa7TpIU33Ihy3z0lMSRq5xVreuYSawRQi1kVOpVPtLPPBRbk/hYc1NqzQ/gVnwTgHOkP8Cuk4G2e1mV0sq7GISNcvilvOWGoD6DT0Qpln1Tz76ttEn+9dzAzq8G0dLAI2Xp7fJhKGjQNR+aaWibqq8x+FJFafZpFpMP835QUsZmcC740oV/nL2O0LpDpCrTGd5VjIBQa7hJ3q0m4MtEqiWKfTdQ1gZM6FJ+eFzS72qEOw==

Signature of the client

Responses

Response samples

Content type
application/json
Example
{
  • "dateTime": "string",
  • "clientId": "testAccount",
  • "merchantRef": "Order-1001",
  • "cmd": "SALE",
  • "orderId": "0c170aa0-7c5a-4b32-9529-102aaa454f51",
  • "type": "VM",
  • "txnId": "5fe3368b-453a-4cc1-81f1-4c2054cb4ca4",
  • "txnType": "SALE",
  • "merchantId": "H345678H3620000",
  • "hostId": "1",
  • "card": "VISA",
  • "status": "Approved",
  • "amt": 100.5,
  • "resp": "APPROVED",
  • "hostTime": "2021-02-03T17:29:09+08:00",
  • "appCode": "123456",
  • "pan": "444000xxxxxx0010",
  • "expDate": "1027",
  • "respMsg": "ok",
  • "goodsName": "Sunmi T2 Lite",
  • "goodsDesc": "Electronic product",
  • "cardToken": 4444555566667777,
  • "cardTokenSrc": "SPIRAL",
  • "metadata": {
    },
  • "paidAmt": 100.5,
  • "orderAmt": 100.5,
  • "currency": "HKD"
}

Payment Link Creation

The API call for creating a payment link from gateway

path Parameters
clientId
required
string
Example: merchantOne

The ID of the account assigned by Spiral

merchantRef
required
string
Example: 1627965086558-1

The reference created by merchants on this order, must be unique.

header Parameters
Spiral-Request-Datetime
string
Example: 2021-08-03T04:31:26.558Z

The UTC time in %Y-%m-%d'T'%H:%M:%S'Z' format when the request/response is composed

Spiral-Client-Signature
string
Example: KsUJDwropdIGZ/G6vVEXG4FiEOw/+u6dzeuYaFCxnulnJp9vrhyxP0wj0HxzXx/EQyOD6qq5VJFlFvw0Cez1/qnwpoQPHONOE0aQLcxFcEa7TpIU33Ihy3z0lMSRq5xVreuYSawRQi1kVOpVPtLPPBRbk/hYc1NqzQ/gVnwTgHOkP8Cuk4G2e1mV0sq7GISNcvilvOWGoD6DT0Qpln1Tz76ttEn+9dzAzq8G0dLAI2Xp7fJhKGjQNR+aaWibqq8x+FJFafZpFpMP835QUsZmcC740oV/nL2O0LpDpCrTGd5VjIBQa7hJ3q0m4MtEqiWKfTdQ1gZM6FJ+eFzS72qEOw==

Signature of the client

Request Body schema: application/json
clientId
required
string

The ID of the account assigned by Spiral

merchantRef
required
string

The reference created by merchants on this order, must be unique.

amt
required
number

transaction amount

goodsName
required
string

Goods title

goodsDesc
string

Description of Goods

webhookUrl
required
string <uri>

The endpoint of the payment result notification

durationHr
required
number

number of hours the payment link will be valid

Responses

Request samples

Content type
application/json
{
  • "clientId": "merchantOne",
  • "merchantRef": "Order-1001",
  • "amt": 100.5,
  • "goodsName": "Sunmi T2 Lite",
  • "goodsDesc": "Electronic product",
  • "webhookUrl": "https://www.merchantsite.com/webhook",
  • "durationHr": 24
}

Response samples

Content type
application/json
Example
{}

Payment Link Query

The API call for query payment link status

path Parameters
clientId
required
string
Example: merchantOne

The ID of the account assigned by Spiral

merchantRef
required
string
Example: 1627965086558-1

The reference created by merchants on this order, must be unique.

header Parameters
Spiral-Request-Datetime
string
Example: 2021-08-03T04:31:26.558Z

The UTC time in %Y-%m-%d'T'%H:%M:%S'Z' format when the request/response is composed

Spiral-Client-Signature
string
Example: KsUJDwropdIGZ/G6vVEXG4FiEOw/+u6dzeuYaFCxnulnJp9vrhyxP0wj0HxzXx/EQyOD6qq5VJFlFvw0Cez1/qnwpoQPHONOE0aQLcxFcEa7TpIU33Ihy3z0lMSRq5xVreuYSawRQi1kVOpVPtLPPBRbk/hYc1NqzQ/gVnwTgHOkP8Cuk4G2e1mV0sq7GISNcvilvOWGoD6DT0Qpln1Tz76ttEn+9dzAzq8G0dLAI2Xp7fJhKGjQNR+aaWibqq8x+FJFafZpFpMP835QUsZmcC740oV/nL2O0LpDpCrTGd5VjIBQa7hJ3q0m4MtEqiWKfTdQ1gZM6FJ+eFzS72qEOw==

Signature of the client

Responses

Response samples

Content type
application/json
Example
{}

Reconciliations

The API call for querying a list of the transactions within the time range for reconciliations purpose. Only processed transactions will be returned.

path Parameters
clientId
required
string

The ID of the account assigned by Spiral

header Parameters
Spiral-Request-Datetime
string
Example: 2021-08-03T04:31:26.558Z

The UTC time in %Y-%m-%d'T'%H:%M:%S'Z' format when the request/response is composed

Spiral-Client-Signature
string
Example: KsUJDwropdIGZ/G6vVEXG4FiEOw/+u6dzeuYaFCxnulnJp9vrhyxP0wj0HxzXx/EQyOD6qq5VJFlFvw0Cez1/qnwpoQPHONOE0aQLcxFcEa7TpIU33Ihy3z0lMSRq5xVreuYSawRQi1kVOpVPtLPPBRbk/hYc1NqzQ/gVnwTgHOkP8Cuk4G2e1mV0sq7GISNcvilvOWGoD6DT0Qpln1Tz76ttEn+9dzAzq8G0dLAI2Xp7fJhKGjQNR+aaWibqq8x+FJFafZpFpMP835QUsZmcC740oV/nL2O0LpDpCrTGd5VjIBQa7hJ3q0m4MtEqiWKfTdQ1gZM6FJ+eFzS72qEOw==

Signature of the client (no merchantRef such payload is constructed from clientId & time)

Request Body schema: application/json
dateTimeStart
required
string

The UTC time in %Y-%m-%d'T'%H:%M:%S'Z' format when the request/response is composed

dateTimeEnd
required
string

The UTC time in %Y-%m-%d'T'%H:%M:%S'Z' format when the request/response is composed

limit
integer

The maximum number of transactions return in a single message, default value is 50 and the maximum limit is 100

nextToken
string

The value is returned in previous query and used for pagination. Do not include this field in the first query.

Responses

Request samples

Content type
application/json
{
  • "dateTimeStart": "2022-03-02T08:00:00Z",
  • "dateTimeEnd": "2021-03-03T08:00:00Z",
  • "limit": 100,
  • "nextToken": "{\"merchantRef\": \"1676337454148\", \"clientId\": \"hebbe\", \"dateTime\": \"2021-08-03T09:17:44Z\"}"
}

Response samples

Content type
application/json
{
  • "clientId": "testAccount",
  • "nextToken": "{\"merchantRef\": \"1676337454100\", \"clientId\": \"hebbe\", \"dateTime\": \"2021-08-00T08:17:44Z\"}",
  • "dateTime": "2023-03-03 11:34:06+0800",
  • "txns": [
    ]
}

Webhook (Spiral to Merchant)

To notify the transaction result from Spiral to merchant

Transaction Notification

The webhook to notify merchant on the transaction result

path Parameters
transactionWebhookURL
required
string

The URL specified in the sale request

header Parameters
Spiral-Request-Datetime
string
Example: 2021-08-03T04:31:26.558Z

The UTC time in %Y-%m-%d'T'%H:%M:%S'Z' format when the request/response is composed

Spiral-Server-Signature
string
Example: KsUJDwropdIGZ/G6vVEXG4FiEOw/+u6dzeuYaFCxnulnJp9vrhyxP0wj0HxzXx/EQyOD6qq5VJFlFvw0Cez1/qnwpoQPHONOE0aQLcxFcEa7TpIU33Ihy3z0lMSRq5xVreuYSawRQi1kVOpVPtLPPBRbk/hYc1NqzQ/gVnwTgHOkP8Cuk4G2e1mV0sq7GISNcvilvOWGoD6DT0Qpln1Tz76ttEn+9dzAzq8G0dLAI2Xp7fJhKGjQNR+aaWibqq8x+FJFafZpFpMP835QUsZmcC740oV/nL2O0LpDpCrTGd5VjIBQa7hJ3q0m4MtEqiWKfTdQ1gZM6FJ+eFzS72qEOw==

Signature of the Server

Request Body schema: application/json
dateTime
string

transaction date time in YY-MM-DD hh:mm:ss+0800 format

clientId
required
string

The ID of the account assigned by Spiral

merchantRef
required
string

The reference created by merchants on this order, must be unique.

cmd
required
string

indication of the operation

orderId
required
string <uuid>

generated by Spiral, reference for an order

type
required
string

transaction type, details refer to the Support Types page.

txnId
required
string <uuid>

generated by Spiral, if a refund to made to a sale transaction, the OrderID will be the same with a new TxnID

txnType
string

Transaction type, SALE/AUTH/CAPTURE/REFUND

merchantId
required
string

Merchant ID of the payment acquirer

hostId
required
string

indicator ID of the payment acquirer

card
string

card type

status
required
string

Status of the transaction
Approved- transaction approved
Declined- transaction declined by host
Timeout- input timeout
Unconfirmed- the transaction result is not yet confirmed
Cancelled- the transaction is cancelled by user
PartialPaid- the transaction is only partial paid (for FPS only)
OverPaid- the transaction is over paid (for FPS only)

amt
required
number

transaction amount

resp
string

Response Code from the payment acquirer

hostTime
required
string <date-time>

The transaction time from the payment system

appCode
string

Approval code

pan
string

Card PAN in truncated format.

expDate
string

Expiry date. Usually in truncated format.

respMsg
string

Response Message (Text) from the payment system

goodsName
string

Goods title for eComm
(Required for SALE/SALESESSION/AUTH/AUTHSESSION)

goodsDesc
string

Description of Goods that will be an indication to payment or discount calculation or shown as info in eComm

cardToken
string

Only be submitted for direct payment as a substitution of the card numbers. Need to provide the cardTokenSrc at the same time.

cardTokenSrc
string

The source of the card tokens, can be SPIRAL, APPLE_PAY, GOOGLE_PAY

metadata
string

A json object that contains the user defined data. The data will not be used for the authorization or any other operation of the payment. It will be stored in the database and be further used for reporting or query.

paidAmt
required
number

Amount paid (It should be identical to amt except FPS)

orderAmt
number

Total amount paid for this order, only available for FPS

currency
string

payment currency

Responses

Request samples

Content type
application/json
{
  • "dateTime": "string",
  • "clientId": "testAccount",
  • "merchantRef": "Order-1001",
  • "cmd": "SALE",
  • "orderId": "0c170aa0-7c5a-4b32-9529-102aaa454f51",
  • "type": "VM",
  • "txnId": "5fe3368b-453a-4cc1-81f1-4c2054cb4ca4",
  • "txnType": "SALE",
  • "merchantId": "H345678H3620000",
  • "hostId": "1",
  • "card": "VISA",
  • "status": "Approved",
  • "amt": 100.5,
  • "resp": "APPROVED",
  • "hostTime": "2021-02-03T17:29:09+08:00",
  • "appCode": "123456",
  • "pan": "444000xxxxxx0010",
  • "expDate": "1027",
  • "respMsg": "ok",
  • "goodsName": "Sunmi T2 Lite",
  • "goodsDesc": "Electronic product",
  • "cardToken": 4444555566667777,
  • "cardTokenSrc": "SPIRAL",
  • "metadata": {
    },
  • "paidAmt": 100.5,
  • "orderAmt": 100.5,
  • "currency": "HKD"
}

Payment Link Notification

The webhook to notify merchant on the payment link result

path Parameters
paymentLinkWebhookURL
required
string

The URL specified in the sale request

header Parameters
Spiral-Request-Datetime
string
Example: 2021-08-03T04:31:26.558Z

The UTC time in %Y-%m-%d'T'%H:%M:%S'Z' format when the request/response is composed

Spiral-Server-Signature
string
Example: KsUJDwropdIGZ/G6vVEXG4FiEOw/+u6dzeuYaFCxnulnJp9vrhyxP0wj0HxzXx/EQyOD6qq5VJFlFvw0Cez1/qnwpoQPHONOE0aQLcxFcEa7TpIU33Ihy3z0lMSRq5xVreuYSawRQi1kVOpVPtLPPBRbk/hYc1NqzQ/gVnwTgHOkP8Cuk4G2e1mV0sq7GISNcvilvOWGoD6DT0Qpln1Tz76ttEn+9dzAzq8G0dLAI2Xp7fJhKGjQNR+aaWibqq8x+FJFafZpFpMP835QUsZmcC740oV/nL2O0LpDpCrTGd5VjIBQa7hJ3q0m4MtEqiWKfTdQ1gZM6FJ+eFzS72qEOw==

Signature of the Server

Request Body schema: application/json
clientId
required
string

The ID of the account assigned by Spiral

merchantRef
required
string

The reference created by merchants on this order, must be unique.

approvedTxnId
required
string

the txnId of the approved transaction of the payment link

status
required
string

Status of the transaction
Approved- transaction approved
Declined- transaction declined by host
Timeout- input timeout
Unconfirmed- the transaction result is not yet confirmed
Cancelled- the transaction is cancelled by user
PartialPaid- the transaction is only partial paid (for FPS only)
OverPaid- the transaction is over paid (for FPS only)

amt
required
number

transaction amount

paymentLinkUrl
required
string

payment link URL

Responses

Request samples

Content type
application/json
{}