Skip to Content
API ReferenceOverview

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 the integration docs:

  • In-Person Payments → Semi-integration: terminal/cloud payment APIs (sale, auth, refund, etc.), OpenAPI path prefix /v1/semi-integration/transaction/...; Settlement: batch query and batch close, path prefix /v1/settlement/....
  • Online Payments: Hosted Payment Page session APIs (/v1/checkout/create-session, /v1/checkout/expire-session); Direct payment at /v1/checkout/sale without creating a session first; Online Refund at /v1/checkout/refund.
  • Transaction Inquiry: shared across in-person and online scenarios.
  • Merchants: merchant and terminal lookup APIs.

Query is shared by online and in-person flows and lives outside the scenario folders.

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.us/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

Last updated on
Sale