Overview

API Only means you run checkout on your own website or app, complete wallet authorization and payload handling on the merchant side, then your backend calls SUNBAY to charge—without the Hosted Payment Page (HPP).

The public integration path focuses on digital wallets:

Google Pay, Apple Pay, etc.: integrate the wallet’s official JS/SDK, obtain the encrypted token / payload after user consent, and send it as cardEncryptedData with paymentMethod to Direct payment.

Send payloads only to your backend; do not keep raw wallet tokens in the browser or client storage long term.

Channel-specific steps (button, fields, payload shape) live in each payment-method guide (e.g. Google Pay™, “API Only integration”).

This page covers shared topics: direct payment request/response, Webhook, and security baselines.

When to use

Aspect	Details
Credential capture	Wallet authorization on your page; you receive encrypted credentials from the wallet
Front end	You integrate official SDK/JS, custom buttons, risk UX
Backend	One direct payment API for capture + Webhook/reconciliation
Typical use	Mature checkout, tight coupling with orders or risk systems

Payment flow

Direct payment

After your backend receives the wallet payload, call Direct payment API. Payment-related fields (public OpenAPI):

paymentMethod: GOOGLE_PAY, APPLE_PAY, etc.
GOOGLE_PAY / APPLE_PAY: required cardEncryptedData—wallet token/JSON string, pass through as returned by the wallet
Amounts, order IDs, etc. follow the same rules as other online flows; notifyUrl is optional (include it only if you need Webhooks)

Example (wallet)


POST /v1/checkout/sale
 
{
  "appId": "your_app_id",
  "merchantId": "your_merchant_id",
  "transactionRequestId": "sale_req_1741680000000",
  "referenceOrderId": "ORDER_20260311_001",
  "description": "Order description",
  "amount": {
    "orderAmount": 99999,
    "taxAmount": 8000,
    "priceCurrency": "USD"
  },
  "paymentMethod": "GOOGLE_PAY",
  "cardEncryptedData": "<encrypted payload from wallet>",
  "notifyUrl": "https://merchant.example.com/webhook/payment"
}

Full field list: Direct payment API.

Response handling

transactionStatus values: see Transaction status—I / P / S / F / C.

`data.transactionStatus`	Typical case	Action
`S`	Paid	Update order, show success
`P`	In progress (e.g. 3DS)	If `data.action.redirectUrl` exists, redirect immediately
`F`	Failed	Show `data.transactionResultMsg`, offer retry

3DS redirect: when data.transactionStatus = "P" and data.action.redirectUrl is present, redirect the user immediately; final outcome still comes from Webhook.

Webhook

If you send notifyUrl, SUNBAY POSTs there when payment completes—treat Webhook as the source of truth for final status. If omitted, no Webhook is sent—use transaction query or another channel for the final outcome.

Verify signatures to block forged calls
Idempotency on referenceOrderId (or documented field) to avoid duplicate processing
Return HTTP 200; otherwise SUNBAY retries with backoff

Security

Use HTTPS in production
Parse and forward credentials only on the server; avoid logging or persisting sensitive data on the client
Keep API and signing keys server-side only
Respect wallet rules for data use/retention (e.g. billing address from Google Pay)