EPIS API Document (1.0.0)

Download OpenAPI specification:Download

Environments

Development
https://store-hub-api-develop.myepis.cloud
(Testing and staging)
Production
https://store-hub-api.myepis.cloud
(Live traffic)

Authentication

Required Headers

Header	Description
`x-api-key`	Merchant API key
`x-request-id`	Unique request identifier
`x-api-signature`	Generated HMAC-SHA256 signature
`x-timestamp`	Current UTC timestamp

🔑 API Key Usage

Include x-api-key in all requests
Obtain from Merchant Dashboard
Example: x-api-key: ak_1234567890abcdef

🔒 Signature Requirements

x-api-signature = HMAC-SHA256(secretKey, x-request-id + "." + x-timestamp)

⚠️ Important Notes

Never share your secretKey - it's only shown once during API key creation
Requests must include a timestamp (UTC milliseconds) in the payload
Requests older than 5 minutes will be rejected (prevent replay attacks)
Test credentials available in Sandbox environment

Rate Limits

⚡ API Throttling

60 requests per 30 seconds per API key
Applies to all endpoints

Response Convention

All API responses:

Return HTTP 200 status code

Follow format:

{
  "errorCode": "SUCCESS|ERROR_CODE",
  "data": { ... },  // or null
  "message": "Optional description"
}

Interpret results using errorCode not HTTP status

Error Codes

Code	Name	Description
0	SUCCESS	Operation completed successfully
4000	BAD_PAYLOAD	Invalid request parameters/body
4100	UNAUTHORIZED	Authentication credentials invalid
4101	INACTIVE	API key/account inactive
5000	NOT_AVAILABLE	Service temporarily unavailable

Always check the errorCode field rather than HTTP status codes

Transactions

Group of transaction-related endpoints

Create a new transaction

Request Body schema: application/json

timestamp required	integer <int64> >= 0 Current UTC timestamp (milliseconds) Used for: Signature generation Request expiration (5 minutes validity) Example value: `1693324800000` = 2023-08-30T00:00:00Z
transactionId required	string Unique identifier for the store request. ⚠️ Must be unique per store transaction (duplicates will be rejected)
currency required	string Default: "AUD" Enum: "AUD" "EUR" "USD" Transaction currency. Supported values: `AUD` (Australian Dollar) `EUR` (Euro) `USD` (United States Dollar) Defaults to AUD if not provided
required	Array of objects (TransactionItemModel) non-empty Transaction items At least 1 item required Total calculated from sum of (item.amount × item.quantity)
required	object (StoreModel) Merchant details Name will be shown in payment link in billing info
required	object (PayerModel) Customer information Email will be shown in payment link in billing info
discount	number >= 0 Optional discount amount
returnUrl	string <uri> After payment is successfully, page will redirect to this url
cancelUrl	string <uri> When user cancel payment, page will redirect to this url

Responses

Request samples

Payload

Content type

application/json

{"timestamp": 1693324800000,
"transactionId": "txn_12345",
"currency": "AUD",
"items": [{"name": "Premium Widget",
"amount": "29.99",
"quantity": "2"
}
],
"store": {"id": "store_1234567890abcdef",
"name": "Tech Store",
"email": "store@tech.com",
"slug": "string",
"applicationId": "string"
},
"payer": {"firstName": "John",
"lastName": "Doe",
"email": "john.doe@email.com",
"address": {"line": "123 Main Street",
"street": "Downtown District",
"city": "Sydney",
"state": "NSW",
"country": "Australia",
"zipCode": "2000"
}
},
"discount": 5.99,
"returnUrl": "https://store.example.com/return",
"cancelUrl": "https://store.example.com/cancel"
}

Response samples

200

Content type

application/json

{"errorCode": 0,
"data": {"code": "1741519556587",
"partnerTransactionId": "test33146",
"status": 9,
"amount": 10,
"discount": 1,
"currency": "AUD",
"items": [{"name": "test",
"amount": 1000,
"quantity": 1,
"createdAt": "2025-03-09T11:25:56.590Z",
"updatedAt": "2025-03-09T11:25:56.590Z",
"id": "95c85df8-6d27-4a64-98bb-48f4963e4c30"
}
],
"metadata": {"returnUrl": "https://example.com",
"cancelUrl": "https://example.com",
"payer": {"firstName": "test",
"lastName": "hello",
"email": "test@demo.com"
}
},
"paymentUrl": "https://invoice-agent.pages.dev/transaction/1741519556587..."
},
"message": "Transaction created successfully"
}

Get a transaction by ID

path Parameters

id

required

string

Responses

Response samples

200

Content type

application/json

{"errorCode": 100,
"data": {"code": "1741519556587",
"partnerTransactionId": "test33146",
"status": 9,
"amount": 10,
"discount": 1,
"currency": "AUD",
"items": [{"name": "test",
"amount": 1000,
"quantity": 1,
"createdAt": "2025-03-09T11:25:56.590Z",
"updatedAt": "2025-03-09T11:25:56.590Z",
"id": "95c85df8-6d27-4a64-98bb-48f4963e4c30"
}
],
"metadata": {"returnUrl": "https://example.com",
"cancelUrl": "https://example.com",
"payer": {"firstName": "test",
"lastName": "hello",
"email": "test@demo.com"
}
}
}
}

Payment

Group of payment-related endpoints

Create a new payment

Request Body schema: application/json

timestamp required	integer <int64> >= 0 Current UTC timestamp (milliseconds) Used for: Signature generation Request expiration (5 minutes validity) Example value: `1693324800000` = 2023-08-30T00:00:00Z
transactionId required	string Unique identifier for the store request. ⚠️ Must be unique per store transaction (duplicates will be rejected)
method required	string Value: "CARD"
currency required	string Default: "AUD" Enum: "AUD" "EUR" "USD" Transaction currency. Supported values: `AUD` (Australian Dollar) `EUR` (Euro) `USD` (United States Dollar) Defaults to AUD if not provided
required	Array of objects (TransactionItemModel) non-empty Transaction items At least 1 item required Total calculated from sum of (item.amount × item.quantity)
required	object (StoreModel) Merchant details Name will be shown in payment link in billing info
required	object (PayerModel) Customer information Email will be shown in payment link in billing info
discount	number >= 0 Optional discount amount
returnUrl	string <uri> After payment is successfully, page will redirect to this url
cancelUrl	string <uri> When user cancel payment, page will redirect to this url

Responses

Request samples

Payload

Content type

application/json

{"timestamp": 1693324800000,
"transactionId": "txn_12345",
"method": "CARD",
"currency": "AUD",
"items": [{"name": "Premium Widget",
"amount": "29.99",
"quantity": "2"
}
],
"store": {"id": "store_1234567890abcdef",
"name": "Tech Store",
"email": "store@tech.com",
"slug": "string",
"applicationId": "string"
},
"payer": {"firstName": "John",
"lastName": "Doe",
"email": "john.doe@email.com",
"address": {"line": "123 Main Street",
"street": "Downtown District",
"city": "Sydney",
"state": "NSW",
"country": "Australia",
"zipCode": "2000"
}
},
"discount": 5.99,
"returnUrl": "https://store.example.com/return",
"cancelUrl": "https://store.example.com/cancel"
}

Response samples

200

Content type

application/json

{"errorCode": 0,
"data": {"code": "1741519556587",
"partnerTransactionId": "test33146",
"status": 9,
"amount": 10,
"discount": 1,
"currency": "AUD",
"items": [{"name": "test",
"amount": 1000,
"quantity": 1,
"createdAt": "2025-03-09T11:25:56.590Z",
"updatedAt": "2025-03-09T11:25:56.590Z",
"id": "95c85df8-6d27-4a64-98bb-48f4963e4c30"
}
],
"metadata": {"returnUrl": "https://example.com",
"cancelUrl": "https://example.com",
"payer": {"firstName": "test",
"lastName": "hello",
"email": "test@demo.com",
"phoneNumber": "123456789",
"address": {"line": "123 Main St",
"city": "Anytown",
"state": "CA",
"country": "US",
"zipCode": "12345"
}
}
},
"paymentUrl": "https://invoice-agent.pages.dev/transaction/1741519556587...",
"token": "test_api"
},
"message": "Transaction created successfully"
}

Get Payment Methods

Responses

Response samples

200

Content type

application/json

{"errorCode": 0,
"data": ["CARD"
]
}

Store

Group of store-related endpoints

Get store detail

Responses

Response samples

200

Content type

application/json

{"errorCode": 100,
"data": {"id": "1741519556587",
"slug": "retail*demo",
"name": "demo",
"applicationId": "test"
}
}