Overview

This document defines the unified OpenAPI specification for SUNBAY Nexus, covering interface standards, protocols, and integration processes.

Core Capabilities:

• RESTful interface design with standardized request/response formats
• Bearer Token authentication for secure transactions
• Idempotency guarantee to prevent duplicate transactions
• Multi-currency support (ISO 4217)
• Asynchronous notifications and active queries

Document structure

The sidebar groups APIs by scenario and shared services, consistent with integration docs (In-person / Online):

• In-person → Semi-integration: terminal/cloud payment APIs (sale, auth, refund, etc.), OpenAPI path prefix /v1/semi-integration/transaction/....
• Online: Hosted Payment Page session APIs (/v1/checkout/create-session, etc.); Direct payment at /v1/checkout/sale without creating a session first (public specification focuses on digital wallet encrypted payloads; merchant-submitted plaintext card data is not documented).

Query and Settlement are shared by online and in-person flows and live outside the scenario folders.

The API list below uses the same grouping.

General Rules

Protocol and Format

• Transport Protocol: HTTPS (TLS 1.2 and above)
• Character Encoding: UTF-8
• Request Format: JSON
• Response Format: JSON
• Content-Type: application/json

Authentication Method

Uses Bearer Token authentication (RFC 6750), add to request header:

Authorization: Bearer {your_api_key}

Description:

• Header Name: Authorization
• Header Value Format: Bearer {your_api_key} (space between Bearer and API Key)
• API Key Example: sk_test_4eC39HqLyjWDarjtT1zdp7dc

Idempotency and Request Identification

All requests must include the following headers:

X-Client-Request-Id (Required)

Unique request identifier used to prevent duplicate requests and track issues.

• Format: UUID (e.g., 550e8400-e29b-41d4-a716-446655440000)
• Each request must use a unique Request ID
• POST requests: Same ID within 10 minutes will be identified as duplicate request
• GET requests: Duplicate queries are allowed

X-Timestamp (Required)

Request timestamp used to prevent replay attacks.

• Format: Unix timestamp (milliseconds), 13-digit number
• Time deviation cannot exceed ±10 minutes

Complete Request Example:

curl -X POST https://open.sunbay.dev/v1/semi-integration/transaction/sale \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -H "X-Client-Request-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Timestamp: 1701234567890" \
  -d '{...}'

Difference Between referenceOrderId and transactionRequestId

referenceOrderId (Reference Order ID)

Identifies the order in the merchant system, used for business tracing, reconciliation, and customer service.

Applicable Scope:

• Can be passed: Sale, Auth, Forced Auth, Refund without reference
• Cannot be passed: Incremental Auth, Post Auth, Void, Abort, Tip Adjust, Refund with reference

Characteristics: One order can be associated with multiple transactions. Follow-up transactions (such as Incremental Auth, Post Auth) only associate with transactions, not orders.

Common Scenario Examples:

1. Partial Refund Scenario (Most Common)

   • Order ID: ORDER123 (Order amount $100)
   • Sale transaction: $100 (Sale, referenceOrderId: ORDER123)
   • First partial refund: $30 (Refund with reference, no referenceOrderId needed, linked via originalTransactionId)
   • Second partial refund: $20 (Refund with reference, no referenceOrderId needed, linked via originalTransactionId)
   • Same order associated with 3 transactions

2. Pre-authorization Scenario (Hotels, car rentals, etc.)

   • Order ID: ORDER456
   • Pre-authorization transaction: $500 (Auth, referenceOrderId: ORDER456)
   • Incremental authorization: $100 (Incremental Auth, no referenceOrderId needed, linked to original auth via originalTransactionId)
   • Post authorization: $600 (Post Auth, no referenceOrderId needed, linked to original auth via originalTransactionId)
   • Note: Incremental Auth and Post Auth are operations on transactions, not new orders

transactionRequestId (Transaction Request ID)

Identifies a single transaction request, serves as the API idempotency control field. Each transaction must have a unique transactionRequestId, duplicates are not allowed.

Usage Recommendations

❌ Wrong Approach:

// Using order ID as transaction request ID
referenceOrderId: "ORDER123"
transactionRequestId: "ORDER123"  // Wrong: Cannot support multiple transactions for the same order

✅ Correct Approach:

Example 1: Partial Refund Scenario

// Sale transaction
referenceOrderId: "ORDER123"
transactionRequestId: "ORDER123_SALE"

// First partial refund (same order)
referenceOrderId: "ORDER123"
transactionRequestId: "ORDER123_REFUND_001"

// Second partial refund (same order)
referenceOrderId: "ORDER123"
transactionRequestId: "ORDER123_REFUND_002"

Example 2: Pre-authorization Scenario

// Pre-authorization transaction
referenceOrderId: "ORDER456"
transactionRequestId: "ORDER456_AUTH"

// Incremental authorization transaction (for transaction, not order)
originalTransactionId: "TXN_AUTH_001"
transactionRequestId: "ORDER456_INCR"
// Note: Do not pass referenceOrderId

// Post authorization transaction (for transaction, not order)
originalTransactionId: "TXN_AUTH_001"
transactionRequestId: "ORDER456_POST"
// Note: Do not pass referenceOrderId

Retry Scenario

When retrying after transaction failure, must use a new transactionRequestId:

// First request (failed)
referenceOrderId: "ORDER456"
transactionRequestId: "ORDER456_SALE_001"

// Retry request
referenceOrderId: "ORDER456"
transactionRequestId: "ORDER456_SALE_002"  // Use new ID

Important Note: Do not use referenceOrderId directly as transactionRequestId

API List

Semi-integration payment APIs (In-person)

Hosted Payment Page (Online)

Direct payment (Online)

Query APIs

Settlement APIs