Ecommerce Web API

Integration Document
(26 Mar 2024)
Table of Contents

1 Revision History.................................................................. 4
2 Introduction ........................................................................ 5
2.1 Overview ...................................................................................................5
2.1.1 Sequence Diagram .......................................................................................................6
2.1.2 Environment ..................................................................................................................7
3 API Authentication ............................................................. 8
4 Create Order API................................................................. 9
4.1 Request .....................................................................................................9
4.1.1 Parameters....................................................................................................................9
4.1.2 CreateOrderRequest .................................................................................................. 12
4.2 Response................................................................................................. 16
4.3 Sample Code...........................................................................................20
4.4 Notify - Callback.....................................................................................22
4.4.1 Callback mechanism ................................................................................................. 22
4.4.2 Callback validation .................................................................................................... 22
4.4.3 Online tool to verify signature.................................................................................. 23
4.4.4 Sample code for HmacSHA256 ............................................................................... 23
[Link] Java ........................................................................................................................................................ 23
[Link] JavaScript with CryptoJS ..................................................................................................................... 23
4.4.5 Request Body............................................................................................................. 23
5 Get Order API .................................................................... 26
5.1 Request ...................................................................................................26
5.1.1 Parameters................................................................................................................. 26
5.2 Response.................................................................................................27
5.3 Sample Code........................................................................................... 31
6 Create Card Tokenization API.......................................... 32
6.1 Overview .................................................................................................32
6.2 Request ...................................................................................................32
6.2.1 Parameters................................................................................................................. 32
6.2.2 CreateOrderRequest ................................................................................................. 36
6.3 Response................................................................................................. 41
6.4 Sample Code.......................................................................................... 46

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 2 / 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
7 Appendix........................................................................... 48
7.1 Hosted Payment Page .......................................................................... 48

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 3 / 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Revision History

1 Revision History
Version Date Summary of changes By

1.0 24 Nov 2022 • Initial version Howard Man

1.1 28 Nov 2022 • Add flow description, Howard Man

• Remove UAT, redundant country
code, currency code,
• Simplify CreateOrderRequest

1.2 28 Feb 2023 • Update endpoint Howard Man

• Add order callback mechanism

1.3 31 May 2023 Update order notify details: Ben Chan

• Add online tool to verify signature

• Add sample code with Java &
JavaScript

1.4 March 26, • Add Card Tokenization API Billy Han

2024 documentation and examples

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 4/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Introduction

2 Introduction
2.1 Overview
Prior to any integration, merchant should first contact SPECTRA for initialization: account
registration, shop creation, e-commerce API token registration. It is essential for
merchant to keep the API token and user ID secret and safe since they are required for
authentication whenever the API is called.

 The organizeId which is required in the Create Order API (see page 9) will be
provided to merchant together with the API token and user ID. (Please refer to
the Create Order API (see page 9) section)

Overall, there are two API in the e-commerce integration:

• Create Order (see page 9)

• Get Order Info (see page 26)

For Create Order, (see page 9) once the customer checkout on the merchant’s website,
the Create Order API (see page 9) should be called. The order information should be
passed to SPECTRA with the API. For example, the total amount of the order, the
preferred currency, the products in the sale, etc. After that, SPECTRA will return a URL
of the Hosted Payment Page (Please refer to the Hosted Payment Page (see page 48) in
appendix) together with other information in JSON format. The merchant should redirect
the customer to the Hosted Payment Page with the URL. The Hosted Payment Page will
collect the customer’s payment information such as the billing address, the card data,
e.t.c. to process the transaction. Once the customer submits the information on the
Hosted Payment Page, a transaction request will be sent to SPECTRA Gateway. Then
the transaction result will be returned and displayed on the Hosted Payment Page.

For Get Order Info, (see page 26) the merchant can call the Get Order Info API (see page
26) to get the information order. For example, the order status, the billing address of the
customer, and the contact email/ phone of the customer (If the customer has submitted
the information).

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 5/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Introduction

2.1.1 Sequence Diagram

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 6/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Introduction

2.1.2 Environment
The API use different BASE_URL for different environment.

Environment BASE_URL

DEMO [Link]

PROD [Link]

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 7/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 API Authentication

3 API Authentication
The API token and user ID are required for the authentication of every API call. Merchant
should contact Spectra operator to obtain these credentials.

 Please be reminded to keep the credentials secret and safe.

• Each shop can only have one API token

• Each shop can have multiple users
• Each user can only have one user ID

Name Data (example value)

x-soepay-api-token 80ed0e668f65156129261c1bc0f84791fd66c3201eb919bd48c743
0764d4c134

x-soepay-api-userid cb55607718473ae45d701ab7bb06aeacd95e61ba

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 8/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

4 Create Order API

4.1 Request
Method POST

Endpoint $BASE_URL + "ecommerce/order/public/create"

4.1.1 Parameters

Type Name Data (example value)

body createOrderRequest
 There is 4 types of request body can be
REQUIRED
like:

Basic - (buyer info input in payment page)

{
"currency": "HKD",
"products": [
{
"name": "test product",
"price": 10,
"quantity": 1
}
],
"total": 10
}

With callback URL (notify when order status

updated)

{
"currency": "HKD",
"products": [
{
"name": "test product",
"price": 10,
"quantity": 1
}

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 9/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

],
"total": 10,
"notify": {
"url": "[Link]
}
}

With buyer info

{
"contactEmail": "spectra@[Link]",
"contactName": "spectra",
"contactTel": "98765432",
"currency": "HKD",
"products": [
{
"name": "test product 2",
"price": 10,
"quantity": 1
}
],
"sendPaymentMail": true,
"shippingInfo": {
"address1": "string",
"address2": "string",
"address3": "string",
"city": "string",
"company": "string",
"country": "HK",
"email": "spectra@[Link]",
"name": "payer",
"postalCode": "string",
"remark": "string",
"state": "string"
},
"total": 10
}

With buyer info (billing info different with

shopping info)

{
"billingInfo": {
"address1": "aaa",
"address2": "aaa",
"address3": "aaa",
"city": "string",
"company": "string",
"country": "HK",
"email": "spectra@[Link]",

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 10/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

"name": "payer",
"postalCode": "string",
"remark": "string",
"state": "string"
},
"contactEmail": "spectra@[Link]",
"contactName": "spectra",
"contactTel": "98765432",
"currency": "HKD",
"products": [
{
"name": "test product 2",
"price": 10,
"quantity": 1
}
],
"sendPaymentMail": true,
"shippingInfo": {
"address1": "bbb",
"address2": "bbb",
"address3": "bbb",
"city": "string",
"company": "string",
"country": "HK",
"email": "spectra@[Link]",
"name": "payer",
"postalCode": "string",
"remark": "string",
"state": "string"
},
"total": 10
}

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 11/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

4.1.2 CreateOrderRequest
Field Type (length) Description Example

currency String HKD / USD

REQUIRED

total REQUIRED BigDecimal

products List<Product>

notify Notify

contactEmail String

contactName String

contactTel String

sendPaymentMail Boolean

shippingInfo PaymentInfo

billingInfo PaymentInfo

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 12/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

Product

Field Type (length) Description Example

name REQUIRED String

price REQUIRED BigDecimal

quantity REQUIRED Int

uuid String

description String

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 13/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

Notify

Field Type (length) Description Example

url REQUIRED String Callback url for

SPECTRA to notify
merchant when the
order status change

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 14/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

PaymentInfo

Field Type (length) Description Example

address1 String

address2 String

address3 String

city String

company String

country String HK

email String

name String

postalCode String

remark String

state String

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 15/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

4.2 Response
Code Message Data (example value)

200 OK
{
"checksum": "string",
"data": {
"active": true,
"configData": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"currency": "string",
"expiry_duration": "string",
"expiry_time": "2022-11-22T[Link].298Z",
"id": "string",
"identity": {
"active": true,
"id": "string",
"identityType": "DEVICE",
"name": "string",
"status": "ACTIVE"
},
"identity_lite": {
"id": "string",
"name": "string"
},
"instrumentType": "CARD",
"invoice": {
"billingInfo": {
"address1": "string",
"address2": "string",
"address3": "string",
"company": "string",
"country": "AD",
"email": "string",
"id": "string",
"name": "string",
"postalCode": "string",
"state": "string"
},
"contactEmail": "string",
"contactName": "string",
"contactTel": "string",
"id": "string",
"invoiceNumber": "string",
"paid": true,
"paidDate": "2022-11-22T[Link].298Z",
"payerAccount": "string",
"paymentLinkUrl": "string",
"paymentMethod": "ALIPAY",
"shippingInfo": {
"address1": "string",
"address2": "string",
"address3": "string",
"company": "string",

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 16/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

Code Message Data (example value)

"country": "AD",
"email": "string",
"id": "string",
"name": "string",
"postalCode": "string",
"state": "string"
}
},
"line_item": {
"id": "string",
"products": [
{
"currency": "string",
"description": "string",
"id": "string",
"name": "string",
"price": 0,
"quantity": 0,
"total": 0
}
]
},
"on_behalf_of": "MERCHANT",
"organize": {
"active": true,
"address": "string",
"country": "AD",
"currency": "string",
"email": "string",
"id": "string",
"name": "string",
"noticeConfig": {
"emailConfigList": {
"additionalProp1": {
"receiveCompleteOrder": true,
"receiveExpiredOrder": true,
"receivePendingOrder": true,
"receiveStatusChangeOrder": true
},
"additionalProp2": {
"receiveCompleteOrder": true,
"receiveExpiredOrder": true,
"receivePendingOrder": true,
"receiveStatusChangeOrder": true
},
"additionalProp3": {
"receiveCompleteOrder": true,
"receiveExpiredOrder": true,
"receivePendingOrder": true,
"receiveStatusChangeOrder": true
}
},
"hash": "string"
},
"phone": "string",
"status": "ACTIVE",
"type": "AGENT"

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 17/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

Code Message Data (example value)

},
"organize_lite": {
"autoSettlement": true,
"id": "string",
"name": "string",
"plan": "ENTERPRISE",
"settlementTime": "HH:mm:ss",
"type": "AGENT"
},
"payment_id": "string",
"remark": "string",
"source": "ECOMMERCE",
"status": "CANCELLED",
"total": 0
},
"message": "string",
"result": "ACCEPTED_ATC_SYNC"
}

201 Created

401 Unauthorized

403 Forbidden

404 Not Found

Field Type (length) Description Example

result Response Code Response Code

message string Response Message

data Response Data

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 18/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

Hpp Payment Link

• The hpp url is returned in the response under "data" -> "invoice" ->
"paymentLinkUrl" .

{
"checksum": "string",
"data": {
...
"invoice": {
...
"paymentLinkUrl": "I am hpp url",
...
},
...
},
"message": "string",
"result": "ACCEPTED_ATC_SYNC"
}

Order ID

• The order ID is returned in the response under "data" -> "id" .

• The order expiry time is returned in the response under "data" -> "expiry_time" .

{
"checksum": "string",
"data": {
...
"expiry_time": "I am the order expiry time"
"id": "I am order ID"
...
},
"message": "string",
"result": "ACCEPTED_ATC_SYNC"
}

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 19/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

4.3 Sample Code

cURL

curl --location --request POST '$BASE_URL/ecommerce/order/public/create' \

--header 'x-soepay-api-token: $your_api_token' \
--header 'x-soepay-api-userid: $your_user_id' \
--header 'Content-Type: application/json' \
--data-raw '{
"currency": "HKD",
"products": [
{
"name": "test product",
"price": 10,
"quantity": 1
}
],
"total": 10
}'

Java - OkHttp

OkHttpClient client = new OkHttpClient().newBuilder()

.build();
MediaType mediaType = [Link]("application/json");
RequestBody body = [Link](mediaType, "{\n \"currency\": \"HKD\",\n
\"products\": [\n {\n \"name\": \"test product\",\n \"price\": 10,\n
\"quantity\": 1\n }\n ],\n \"total\": 10\n}");
Request request = new [Link]()
.url("$BASE_URL/ecommerce/order/public/create")
.method("POST", body)
.addHeader("x-soepay-api-token", $your_api_token)
.addHeader("x-soepay-api-userid", $your_user_id)
.addHeader("Content-Type", "application/json")
.build();
Response response = [Link](request).execute();

JavaScript - XHR

var data = [Link]({

"currency": "HKD",
"products": [
{
"name": "test product",
"price": 10,
"quantity": 1
}
],
"total": 10
});

var xhr = new XMLHttpRequest();

[Link] = true;

[Link]("readystatechange", function() {
if([Link] === 4) {

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 20/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

[Link]([Link]);
}
});

[Link]("POST", "$BASE_URL/ecommerce/order/public/create");
[Link]("x-soepay-api-token", $your_api_token);
[Link]("x-soepay-api-userid", $your_user_id);
[Link]("Content-Type", "application/json");

[Link](data);

Python - Requests

import requests
import json

url = "$BASE_URL/ecommerce/order/public/create"
payload = [Link]({
"currency": "HKD",
"products": [
{
"name": "test product",
"price": 10,
"quantity": 1
}
],
"total": 10
})
headers = {
'x-soepay-api-token': $your_api_token,
'x-soepay-api-userid': $your_user_id,
'Content-Type': 'application/json'
}

response = [Link]("POST", url, headers=headers, data=payload)

print([Link])

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 21/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

4.4 Notify - Callback

It is an optional field in the request body of Create Order API (see page 9). Merchant can
provide a URL for SPECTRA to notify merchant side whenever the order status changed
so that merchant can get the latest order status as soon as possible.

4.4.1 Callback mechanism

The callback will be trigger when status changed asap, and SPECTRA will retry every 5
mins if callback failed (maximum 3 times).

4.4.2 Callback validation

SPECTRA will sign the request body in HmacSHA256 in Base64 format with the following
key:

Environment hash key

UAT
yEDByWMJ3kgVZtuEcpcgPbswkKEqQBFf242WEj6hexrAghd2ByJXJ9qtuJDq7cFWVQCPMaKEj35VQS8
k8mTy5QRmA5KEuuDa2K3TXfcP79npdcHPrayHSB5bTdaAJhBTvgDNNeH67jRLFYAE8qrNhHe6pkbLvp
Ubhd5NYZeZvwAkjFjhndyJznrAFThNA6cG6Y9AZwKnGrWqhKyPDaSnYprLDHU6W93ECGpcpqUJzsqkT
JBGPpawvu7nNYYYfpvsMJkN7rRpzWTTmmADtEf68UTN33rSpvdRmsCmCe6KS3uQbNVGmBsULGANAFDQ
vhce67srnuSawA9fHv6X5HWbxNx5kRQBbpMDMB2sAZRv2qdUTbEHgv5xgcgHSpTYX8CDbtCCjkTUtFa
zgsMXrUPYhcLw26ATcW34njej9dLHEdurctyB9LwC2CsLFJvsBZpmswuS8nHSDaGJdZVpTD39J4jTqx
hW4ccvwyAwWcN6RYDJfEXtep6p7NqU5fV33q6B

PROD Provided by SPECTRA after api integration done in testing environment

The signature will be included in the request header with key named “sign“.

Since amount handling for json may be different, please make sure there are no trailing
zeros.

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 22/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

 Please test signature with different decimal places (such as $10, $10.01, $10.1
etc…)

4.4.3 Online tool to verify signature

[Link]

4.4.4 Sample code for HmacSHA256

[Link] Java

var algorithm = "HmacSHA256";

var mac = [Link](algorithm);
[Link](new SecretKeySpec([Link](), algorithm));
var hash = [Link]([Link]());
var sign = Base64.encodeBase64String(hash);

[Link] JavaScript with CryptoJS

var hash = CryptoJS.HmacSHA256(body, key);

var sign = [Link](hash);

4.4.5 Request Body

{
"checksum": "string",
"data": {
"active": true,
"configData": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"currency": "string",
"expiry_duration": "string",
"expiry_time": "2022-11-22T[Link].298Z",
"id": "string",
"identity": {
"active": true,
"id": "string",
"identityType": "DEVICE",

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 23/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

"name": "string",
"status": "ACTIVE"
},
"identity_lite": {
"id": "string",
"name": "string"
},
"instrumentType": "CARD",
"invoice": {
"billingInfo": {
"address1": "string",
"address2": "string",
"address3": "string",
"company": "string",
"country": "AD",
"email": "string",
"id": "string",
"name": "string",
"postalCode": "string",
"state": "string"
},
"contactEmail": "string",
"contactName": "string",
"contactTel": "string",
"id": "string",
"invoiceNumber": "string",
"paid": true,
"paidDate": "2022-11-22T[Link].298Z",
"payerAccount": "string",
"paymentLinkUrl": "string",
"paymentMethod": "ALIPAY",
"shippingInfo": {
"address1": "string",
"address2": "string",
"address3": "string",
"company": "string",
"country": "AD",
"email": "string",
"id": "string",
"name": "string",
"postalCode": "string",
"state": "string"
}
},
"line_item": {
"id": "string",
"products": [
{
"currency": "string",
"description": "string",
"id": "string",
"name": "string",
"price": 0,
"quantity": 0,
"total": 0
}
]
},
"on_behalf_of": "MERCHANT",
"organize": {
"active": true,
"address": "string",

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 24/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Order API

"country": "AD",
"currency": "string",
"email": "string",
"id": "string",
"name": "string",
"noticeConfig": {
"emailConfigList": {
"additionalProp1": {
"receiveCompleteOrder": true,
"receiveExpiredOrder": true,
"receivePendingOrder": true,
"receiveStatusChangeOrder": true
},
"additionalProp2": {
"receiveCompleteOrder": true,
"receiveExpiredOrder": true,
"receivePendingOrder": true,
"receiveStatusChangeOrder": true
},
"additionalProp3": {
"receiveCompleteOrder": true,
"receiveExpiredOrder": true,
"receivePendingOrder": true,
"receiveStatusChangeOrder": true
}
},
"hash": "string"
},
"phone": "string",
"status": "ACTIVE",
"type": "AGENT"
},
"organize_lite": {
"autoSettlement": true,
"id": "string",
"name": "string",
"plan": "ENTERPRISE",
"settlementTime": "HH:mm:ss",
"type": "AGENT"
},
"payment_id": "string",
"remark": "string",
"source": "ECOMMERCE",
"status": "CANCELLED",
"total": 0
},
"message": "string",
"result": "ACCEPTED_ATC_SYNC"
}

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 25/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Get Order API

5 Get Order API

5.1 Request
Method GET

Endpoint $BASE_URL + "ecommerce/order/public/info/{orderId}"

 orderId is returned in the response of

CreateOrder (see page 9) API.

5.1.1 Parameters

Type Name Data (example value)

path orderId 89e05b302f44f4e6158b21fd955e88af

REQUIRED

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 26/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Get Order API

5.2 Response
Code Message Data (example value)

200 OK
{
"checksum": "string",
"data": {
"active": true,
"configData": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"currency": "string",
"expiry_duration": "string",
"expiry_time": "2022-11-22T[Link].298Z",
"id": "string",
"identity": {
"active": true,
"id": "string",
"identityType": "DEVICE",
"name": "string",
"status": "ACTIVE"
},
"identity_lite": {
"id": "string",
"name": "string"
},
"instrumentType": "CARD",
"invoice": {
"billingInfo": {
"address1": "string",
"address2": "string",
"address3": "string",
"company": "string",
"country": "AD",
"email": "string",
"id": "string",
"name": "string",
"postalCode": "string",
"state": "string"
},
"contactEmail": "string",
"contactName": "string",
"contactTel": "string",
"id": "string",
"invoiceNumber": "string",
"paid": true,
"paidDate": "2022-11-22T[Link].298Z",
"payerAccount": "string",
"paymentLinkUrl": "string",
"paymentMethod": "ALIPAY",
"shippingInfo": {
"address1": "string",
"address2": "string",
"address3": "string",
"company": "string",

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 27/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Get Order API

Code Message Data (example value)

"country": "AD",
"email": "string",
"id": "string",
"name": "string",
"postalCode": "string",
"state": "string"
}
},
"line_item": {
"id": "string",
"products": [
{
"currency": "string",
"description": "string",
"id": "string",
"name": "string",
"price": 0,
"quantity": 0,
"total": 0
}
]
},
"on_behalf_of": "MERCHANT",
"organize": {
"active": true,
"address": "string",
"country": "AD",
"currency": "string",
"email": "string",
"id": "string",
"name": "string",
"noticeConfig": {
"emailConfigList": {
"additionalProp1": {
"receiveCompleteOrder": true,
"receiveExpiredOrder": true,
"receivePendingOrder": true,
"receiveStatusChangeOrder": true
},
"additionalProp2": {
"receiveCompleteOrder": true,
"receiveExpiredOrder": true,
"receivePendingOrder": true,
"receiveStatusChangeOrder": true
},
"additionalProp3": {
"receiveCompleteOrder": true,
"receiveExpiredOrder": true,
"receivePendingOrder": true,
"receiveStatusChangeOrder": true
}
},
"hash": "string"
},
"phone": "string",
"status": "ACTIVE",
"type": "AGENT"

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 28/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Get Order API

Code Message Data (example value)

},
"organize_lite": {
"autoSettlement": true,
"id": "string",
"name": "string",
"plan": "ENTERPRISE",
"settlementTime": "HH:mm:ss",
"type": "AGENT"
},
"payment_id": "string",
"remark": "string",
"source": "ECOMMERCE",
"status": "CANCELLED",
"total": 0
},
"message": "string",
"result": "ACCEPTED_ATC_SYNC"
}

401 Unauthorized

403 Forbidden

404 Not Found

Field Type (length) Description Example

result Response Code Response Code

message string Response Message

data Response Data

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 29/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Get Order API

Order info

• The order status is returned in the response under "data" -> "status" .
• The order total amount is returned in the response under "data" -> "total" .

{
"checksum": "string",
"data": {
...
"status": "I am order status",
"total": "I am order total amount",
...
},
"message": "string",
"result": "ACCEPTED_ATC_SYNC"
}

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 30/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Get Order API

5.3 Sample Code

cURL

curl --location --request GET '$BASE_URL/ecommerce/order/public/info/$your_order_id' \

--header 'x-soepay-api-token: $your_api_token' \
--header 'x-soepay-api-userid: $your_user_id'

Java - OkHttp

OkHttpClient client = new OkHttpClient().newBuilder()

.build();
MediaType mediaType = [Link]("text/plain");
RequestBody body = [Link](mediaType, "");
Request request = new [Link]()
.url("$BASE_URL/ecommerce/order/public/info/$your_order_id")
.method("GET", body)
.addHeader("x-soepay-api-token", $your_api_token)
.addHeader("x-soepay-api-userid", $your_user_id)
.build();
Response response = [Link](request).execute();

JavaScript - XHR

var xhr = new XMLHttpRequest();

[Link] = true;

[Link]("readystatechange", function() {
if([Link] === 4) {
[Link]([Link]);
}
});

[Link]("GET", "$BASE_URL/ecommerce/order/public/info/$your_order_id");
[Link]("x-soepay-api-token", $your_api_token);
[Link]("x-soepay-api-userid", $your_user_id);

[Link]();

Python - Requests

import requests

url = "$BASE_URL/ecommerce/order/public/info/$your_order_id"
payload={}
headers = {
'x-soepay-api-token': $your_api_token,
'x-soepay-api-userid': $your_user_id
}

response = [Link]("GET", url, headers=headers, data=payload)

print([Link])

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 31/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

6 Create Card Tokenization API

6.1 Overview
A customer’s card information can be tokenized during the checkout process.
To enable the card tokenization option, insert the following parameters in the
“hppConfig” node of the Create Order API request body.

6.2 Request
Method POST

Endpoint $BASE_URL + "ecommerce/order/public/create"

6.2.1 Parameters

Type Name Data (example value)

body createOrderRequest
 There is 5 types of request body can be
REQUIRED
like:

Basic - (buyer info input in payment page)

{
"currency": "HKD",
"products": [
{
"name": "test product",
"price": 10,
"quantity": 1
}
],
"total": 10
}

With callback URL (notify when order status

updated)

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 32/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

{
"currency": "HKD",
"products": [
{
"name": "test product",
"price": 10,
"quantity": 1
}
],
"total": 10,
"notify": {
"url": "[Link]
}
}

With additional HPP options (Card Tokenization,

etc.)

{
"currency": "HKD",
"hppConfig": {
"lang": "en",
"quickPay": "true",
"redirect": "[Link]",
"shopper": "customer12345"
},
"products": [
{
"name": "test product",
"price": 10,
"quantity": 1
}
],
"total": 10,
"notify": {
"url": "[Link]
}
}

With buyer info

{
"contactEmail": "spectra@[Link]",
"contactName": "spectra",
"contactTel": "98765432",
"currency": "HKD",
"products": [
{
"name": "test product 2",
"price": 10,

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 33/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

"quantity": 1
}
],
"sendPaymentMail": true,
"shippingInfo": {
"address1": "string",
"address2": "string",
"address3": "string",
"city": "string",
"company": "string",
"country": "HK",
"email": "spectra@[Link]",
"name": "payer",
"postalCode": "string",
"remark": "string",
"state": "string"
},
"total": 10
}

With buyer info (billing info different with

shopping info)

{
"billingInfo": {
"address1": "aaa",
"address2": "aaa",
"address3": "aaa",
"city": "string",
"company": "string",
"country": "HK",
"email": "spectra@[Link]",
"name": "payer",
"postalCode": "string",
"remark": "string",
"state": "string"
},
"contactEmail": "spectra@[Link]",
"contactName": "spectra",
"contactTel": "98765432",
"currency": "HKD",
"products": [
{
"name": "test product 2",
"price": 10,
"quantity": 1
}
],
"sendPaymentMail": true,
"shippingInfo": {
"address1": "bbb",
"address2": "bbb",
"address3": "bbb",
"city": "string",
"company": "string",

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 34/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

"country": "HK",
"email": "spectra@[Link]",
"name": "payer",
"postalCode": "string",
"remark": "string",
"state": "string"
},
"total": 10
}

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 35/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

6.2.2 CreateOrderRequest
Field Type (length) Description Example

currency String HKD / USD

REQUIRED

total REQUIRED BigDecimal

products List<Product>

notify Notify

contactEmail String

contactName String

contactTel String

sendPaymentMail Boolean

shippingInfo PaymentInfo

billingInfo PaymentInfo

hppConfig HppConfig

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 36/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

Product

Field Type (length) Description Example

name REQUIRED String

price REQUIRED BigDecimal

quantity REQUIRED Int

uuid String

description String

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 37/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

Notify

Field Type (length) Description Example

url REQUIRED String Callback url for

SPECTRA to notify
merchant when the
order status change

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 38/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

HppConfig

Field Type (length) Description Example

lang REQUIRED String Display language of “lang”: “zh” //

the Hosted Payment Chinese
Page
“lang”: “en” //
English

quickPay String When set to “true”, “quickPay”: “true”

address information
required is reduced “quickPay”: “false”
to Postal Code and
Country.

redirect String The redirection URL “redirect”: “https://

once the payment is [Link]”
completed.

shopper String The external Unique “shopper”:

ID of the customer “customer12345”
to map to the card
tokenization value.
This value is from
the merchant’s
online shop.

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 39/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

PaymentInfo

Field Type (length) Description Example

address1 String

address2 String

address3 String

city String

company String

country String HK

email String

name String

postalCode String

remark String

state String

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 40/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

6.3 Response
Code Message Data (example value)

200 OK
{
"checksum": "string",
"data": {
"active": true,
"configData": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"currency": "string",
"expiry_duration": "string",
"expiry_time": "2022-11-22T[Link].298Z",
"id": "string",
"identity": {
"active": true,
"id": "string",
"identityType": "DEVICE",
"name": "string",
"status": "ACTIVE"
},
"identity_lite": {
"id": "string",
"name": "string"
},
"instrumentType": "CARD",
"invoice": {
"billingInfo": {
"address1": "string",
"address2": "string",
"address3": "string",
"company": "string",
"country": "AD",
"email": "string",
"id": "string",
"name": "string",
"postalCode": "string",
"state": "string"
},
"contactEmail": "string",
"contactName": "string",
"contactTel": "string",
"id": "string",
"invoiceNumber": "string",
"paid": true,
"paidDate": "2022-11-22T[Link].298Z",
"payerAccount": "string",
"paymentLinkUrl": "string",
"paymentMethod": "ALIPAY",
"shippingInfo": {
"address1": "string",
"address2": "string",
"address3": "string",
"company": "string",

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 41/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

Code Message Data (example value)

"country": "AD",
"email": "string",
"id": "string",
"name": "string",
"postalCode": "string",
"state": "string"
}
},
"line_item": {
"id": "string",
"products": [
{
"currency": "string",
"description": "string",
"id": "string",
"name": "string",
"price": 0,
"quantity": 0,
"total": 0
}
]
},
"on_behalf_of": "MERCHANT",
"organize": {
"active": true,
"address": "string",
"country": "AD",
"currency": "string",
"email": "string",
"id": "string",
"name": "string",
"noticeConfig": {
"emailConfigList": {
"additionalProp1": {
"receiveCompleteOrder": true,
"receiveExpiredOrder": true,
"receivePendingOrder": true,
"receiveStatusChangeOrder": true
},
"additionalProp2": {
"receiveCompleteOrder": true,
"receiveExpiredOrder": true,
"receivePendingOrder": true,
"receiveStatusChangeOrder": true
},
"additionalProp3": {
"receiveCompleteOrder": true,
"receiveExpiredOrder": true,
"receivePendingOrder": true,
"receiveStatusChangeOrder": true
}
},
"hash": "string"
},
"phone": "string",
"status": "ACTIVE",
"type": "AGENT"

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 42/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

Code Message Data (example value)

},
"organize_lite": {
"autoSettlement": true,
"id": "string",
"name": "string",
"plan": "ENTERPRISE",
"settlementTime": "HH:mm:ss",
"type": "AGENT"
},
"payment_id": "string",
"remark": "string",
"source": "ECOMMERCE",
"status": "CANCELLED",
"total": 0
},
"message": "string",
"result": "ACCEPTED_ATC_SYNC"
}

201 Created

401 Unauthorized

403 Forbidden

404 Not Found

Field Type (length) Description Example

result Response Code Response Code

message string Response Message

data Response Data

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 43/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

Hpp Payment Link

• The hpp url is returned in the response under "data" -> "invoice" ->
"paymentLinkUrl" .

{
"checksum": "string",
"data": {
...
"invoice": {
...
"paymentLinkUrl": "I am hpp url",
...
},
...
},
"message": "string",
"result": "ACCEPTED_ATC_SYNC"
}

Card Token

• The Card Token is returned in the Notify Callback under "remark" item.
• The response is in the format “tokenMsg: THE_CARD_TOKEN”
• If the tokenization fails, the tokenMsg content is the failure reason.
(e.g. tokenMsg: Token is failed to create.)

{
"createTime": "2024-03-26T[Link]+0000",
...
"remark": "tokenMsg: THE_CARD_TOKEN",
"hppConfig": {
...
}
...
"source": "ECOMMERCE"
}

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 44/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

Order ID

• The order ID is returned in the response under "data" -> "id" .

• The order expiry time is returned in the response under "data" -> "expiry_time" .

{
"checksum": "string",
"data": {
...
"expiry_time": "I am the order expiry time"
"id": "I am order ID"
...
},
"message": "string",
"result": "ACCEPTED_ATC_SYNC"
}

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 45/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

6.4 Sample Code

cURL

curl --location --request POST '$BASE_URL/ecommerce/order/public/create' \

--header 'x-soepay-api-token: $your_api_token' \
--header 'x-soepay-api-userid: $your_user_id' \
--header 'Content-Type: application/json' \
--data-raw '{
"currency": "HKD",
"products": [
{
"name": "test product",
"price": 10,
"quantity": 1
}
],
"total": 10
}'

Java - OkHttp

OkHttpClient client = new OkHttpClient().newBuilder()

.build();
MediaType mediaType = [Link]("application/json");
RequestBody body = [Link](mediaType, "{\n \"currency\": \"HKD\",\n
\"products\": [\n {\n \"name\": \"test product\",\n \"price\": 10,\n
\"quantity\": 1\n }\n ],\n \"total\": 10\n}");
Request request = new [Link]()
.url("$BASE_URL/ecommerce/order/public/create")
.method("POST", body)
.addHeader("x-soepay-api-token", $your_api_token)
.addHeader("x-soepay-api-userid", $your_user_id)
.addHeader("Content-Type", "application/json")
.build();
Response response = [Link](request).execute();

JavaScript - XHR

var data = [Link]({

"currency": "HKD",
"products": [
{
"name": "test product",
"price": 10,
"quantity": 1
}
],
"total": 10
});

var xhr = new XMLHttpRequest();

[Link] = true;

[Link]("readystatechange", function() {
if([Link] === 4) {

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 46/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Create Card Tokenization API

[Link]([Link]);
}
});

[Link]("POST", "$BASE_URL/ecommerce/order/public/create");
[Link]("x-soepay-api-token", $your_api_token);
[Link]("x-soepay-api-userid", $your_user_id);
[Link]("Content-Type", "application/json");

[Link](data);

Python - Requests

import requests
import json

url = "$BASE_URL/ecommerce/order/public/create"
payload = [Link]({
"currency": "HKD",
"products": [
{
"name": "test product",
"price": 10,
"quantity": 1
}
],
"total": 10
})
headers = {
'x-soepay-api-token': $your_api_token,
'x-soepay-api-userid': $your_user_id,
'Content-Type': 'application/json'
}

response = [Link]("POST", url, headers=headers, data=payload)

print([Link])

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 47/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.
 Appendix

7 Appendix
7.1 Hosted Payment Page
Collect Payment Info

Transaction Result

© Copyright SPECTRA Technologies Holdings Co. Ltd. p. 48/ 48

It may not be duplicated, published or disclosed without SPECTRA written permission.