Skip to Content
DocumentationIntegration GuideIn-Person PaymentsTapro Semi-IntegrationCloud IntegrationQuick Start

Cloud Integration

Cloud integration refers to your backend server interacting with SUNBAY payment platform through Nexus API, including initiating payment requests to payment terminals, querying transaction status, executing management operations, etc. Suitable for businesses that need centralized transaction management and support multi-terminal scenarios.

Solution Description: For transaction flow of cloud integration, please refer to Solution Overview.

Integration Methods

Choose one of the following integration methods based on your technology stack and requirements:

Using SUNBAY server-side SDK is the most recommended cloud integration method. SDK encapsulates complex logic such as authentication, message assembly, HTTP connection management, etc.

Advantages:

  • Out-of-the-box, integration can be completed with just a few lines of code
  • Automatically handles API authentication and request headers
  • Input and output parameters are modeled, type-safe
  • Automatically handles message assembly and parsing
  • Built-in HTTP connection management and retry mechanism
  • Follows API updates, maintains compatibility

Supported Languages:

  • Java
  • Python
  • Node.js
  • PHP
  • Go
  • .NET

View SDK Documentation →

Method 2: Direct API Calls

If your technology stack does not support the SDKs we provide, you can directly call Nexus API.

Applicable Scenarios:

  • Programming languages not supported by SDK
  • Need complete control over request process
  • Special business requirements

Note: Direct API calls require handling authentication, message assembly, HTTP connection management and other logic yourself, with higher development difficulty. It is recommended to prioritize using SDK.

View API Documentation →

Start Development

1. Configure Tapro Application

Before starting integration, ensure that the payment terminal has Tapro application installed, then go to Settings → Operation Mode and set the mode to PinPad. In cloud integration mode, the terminal receives orders dispatched from the SUNBAY cloud through PinPad mode.

Tapro Operation Mode - PinPad

How Cloud Mode Works:

  • Terminal stays online, receiving cloud-dispatched orders through PinPad mode
  • Your server sends payment requests to SUNBAY cloud via Nexus API
  • SUNBAY cloud pushes payment commands to the terminal for execution
  • Suitable for SaaS platforms, chain stores, and other scenarios requiring centralized management

2. Obtain Development Credentials

Before starting integration, you need to obtain necessary development credentials first. For detailed steps, please refer to Pre-Development Preparation Documentation.

Brief process:

  1. Contact SUNBAY to obtain Copilot account
  2. Log in to Copilot portal to create payment application (select “Cloud Deployment” mode)
  3. Obtain application credentials (including sandbox and production environments):
    • App ID: Application unique identifier
    • API Key: API access key
    • Webhook Secret: Key for verifying Webhook signatures

3. Choose SDK or API

Choose appropriate integration method based on your technology stack:

Using SDK: Visit Server-side SDK Documentation to select SDK for corresponding language

Direct API Calls: Refer to API Reference Documentation to understand API details

4. Configure Permissions

Apply for required API permissions for your application in Copilot portal. Each API corresponds to one permission, permission identifier is the API path.

Common API Permissions:

API FunctionAPI Path (Permission Identifier)Description
Sale/v1/semi-integration/transaction/saleSale transaction
Pre-authorization/v1/semi-integration/transaction/authPre-authorization
Pre-authorization Completion/v1/semi-integration/transaction/post-authPre-authorization completion
Forced Pre-authorization/v1/semi-integration/transaction/forced-authForced pre-authorization
Incremental Pre-authorization/v1/semi-integration/transaction/incremental-authIncremental pre-authorization
Refund/v1/semi-integration/transaction/refundRefund transaction
Void/v1/semi-integration/transaction/voidVoid transaction
Tip Adjustment/v1/semi-integration/transaction/tip-adjustTip adjustment
Abort Transaction/v1/semi-integration/transaction/abortAbort transaction
Retrieve Transaction/v1/transaction/queryQuery transaction status
Open Batch Query/v1/settlement/batch-queryQuery open (unsettled) batch summary
Batch Close/v1/settlement/batch-closeClose batch and trigger settlement
Closed Batch Query/v1/settlement/batch-close-listQuery closed (settled) batch records
Retrieve Merchant/v1/merchant/queryQuery merchant information
List Merchant Terminals/v1/merchant/terminals/queryList terminals bound to a merchant

For complete API list, please refer to API Reference Documentation.

Important: Some APIs require completing sandbox environment test acceptance to obtain production environment usage permission. For detailed process, please refer to Sandbox Environment Testing Documentation.

5. Subscribe to Terminal Events (Optional)

In cloud integration mode, once a transaction is dispatched, the terminal goes through steps like card presentation, signature capture, and receipt printing. SUNBAY lets you subscribe to these terminal process events by passing a terminalEventNotifyUrl parameter when placing an order. This enables you to:

  • Drive live UI progress on your front end (“Waiting for card” → “Processing” → “Receipt printed”)
  • Use the TRANSACTION_ENDED event to precisely know when the terminal is idle and safe to dispatch the next transaction

Terminal events are complementary to the Transaction Result Webhook: the result webhook tells you the final payment outcome, while terminal events tell you what the terminal is doing along the way.

For the full event model, integration details, and best practices, see Subscribe to Terminal Events.

Last updated on
Local IntegrationSubscribe to Terminal Events