Skip to Content
API ReferenceTransactionsIn-Person PaymentsRefund

Refund

Important

A successful API response (code = 0) only indicates that the refund request has been accepted — it does not mean the refund is complete. Use the transactionStatus field in the response to determine the final refund result, or check via the Transaction Query API or Webhook notification.

The refund API supports an optional signatureConfig object for non-referenced refunds (a refund sent with referenceOrderId instead of an original transaction identifier), where the cardholder presents a card and can be asked to sign:

// Follow the terminal's own signature settings (default)
{ "signatureConfig": { "useHostConfig": true } }
 
// Print a signature line on the receipt for this refund
{ "signatureConfig": { "useHostConfig": false, "entryLocation": "ON_RECEIPT" } }

entryLocation accepts ON_SCREEN, ON_RECEIPT and NONE, and an optional threshold (smallest currency unit) captures a signature only when the amount is greater than the threshold. Sending signatureConfig on a referenced refund is rejected with E302. See Sale for the full field semantics.

ENDPOINT
POST
https://open.sunbay.us/v1/semi-integration/transaction/refund

The Transaction Refund API is used to initiate refunds for successful transactions. Supports full refunds and partial refunds. For non-referenced refunds, originalTransactionId and originalTransactionRequestId must be empty, and referenceOrderId is required. For referenced refunds, originalTransactionId or originalTransactionRequestId must be provided, and referenceOrderId is not needed.

Parameters

Header parameters

NameTypeRequiredDescription
Authorization
stringYes
Bearer Token authentication, format: Bearer {your_api_key}
Example: "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"
Content-Type
stringYes
Request content type, fixed value: application/json
X-Client-Request-Id
string(64)Yes
Request unique identifier, used to prevent duplicate requests and issue tracking. UUID format is recommended, each request must use a unique Request ID
Example: "550e8400-e29b-41d4-a716-446655440000"
X-Timestamp
stringYes
Request timestamp, Unix timestamp (milliseconds), 13 digits. The deviation between the request timestamp and server time cannot exceed ±10 minutes
Pattern: ^[0-9]{13}$
Example: "1701234567890"

Body parameters

NameTypeRequiredDescription
appId
string(32)Yes
Application ID, the unique identifier of the integrated application created through the SUNBAY Connect developer platform
Example: "smkrjobsk3sifh90"
merchantId
string(11-11)Yes
SUNBAY platform merchant unique identifier, created via the SUNBAY Copilot portal. Format: 11-character alphanumeric string starting with M.
⚠ Note: This is not the MID assigned by a payment processor
Pattern: ^M[A-Za-z0-9]{10}$
Example: "M1261833002"
originalTransactionId
string(64)No
SUNBAY Nexus transaction ID of the original transaction to be refunded. Use either this or originalTransactionRequestId. If both are provided, originalTransactionId takes priority. For referenced refunds, one of them is required; for non-referenced refunds, both must be empty
Example: "TXN20231119001"
originalTransactionRequestId
string(32)No
Transaction request ID of the original transaction to be refunded. Use either this or originalTransactionId. If both are provided, originalTransactionId takes priority. For referenced refunds, one of them is required; for non-referenced refunds, both must be empty
Example: "PAY_REQ_20231119001"
referenceOrderId
string(6-32)No
Merchant-assigned reference identifying a business order in your system, used to associate this transaction. A single order may be shared across multiple transactions. Length: 6-32 characters. Allowed characters: letters, digits, and `_-|*`. Required only for non-referenced refunds (when `originalTransactionId` is not provided); for referenced refunds, this field is not needed and the system links to the original transaction's order reference automatically.
Pattern: ^[A-Za-z0-9_\-|*]+$
Example: "ORDER20231119002"
transactionRequestId
string(32)Yes
Transaction request ID. Client-generated unique identifier for API idempotency control. Must be unique per request.
Pattern: ^[A-Za-z0-9_\-]+$
Example: "PAY_REQ_20231119006"
amount
objectYes
paymentMethod
objectNo
Payment method information, applicable only for non-referenced refunds. It is recommended not to pass this parameter to maintain maximum flexibility. When not passed, the payment terminal will display all available payment method options, ensuring customers can choose the latest payment methods
cardNetworkType
string(32)No
Card network type, see Card Network Type. This parameter only takes effect when paymentMethod.category is CARD; if not specified, the system will automatically identify based on card BIN
Example: "CREDIT"
description
string(128)Yes
Refund reason description. A description that accurately represents the refund reason is required
Example: "Product return"
terminalSn
string(32)Yes
Payment terminal serial number. The serial number of the payment terminal provided by SUNBAY, which is used for reading bank cards, processing PINs, and other security operations
Example: "T1234567890"
attach
string(128)No
Additional data, returned as is, JSON format recommended
Example: "{\"reason\":\"quality_issue\"}"
notifyUrl
string(200)No
Asynchronous notification URL. Receives Transaction Result Webhook notifications.
Format: uri
Example: "https://merchant.com/notify"
terminalEventNotifyUrl
string(200)No
URL to receive terminal event notifications. Events are pushed only when pushToTerminal=true (transaction dispatched to the terminal). See Subscribe to Terminal Events.
Format: uri
Example: "https://merchant.com/terminal-events"
timeExpire
string(64)No
Transaction expiration time, format: yyyy-MM-DDTHH:mm:ss+TIMEZONE (ISO 8601), the transaction will be closed if payment is not completed after this time. Minimum 3 minutes, maximum 1 day, defaults to 1 day if omitted. Only used for non-referenced refunds (requires customer action on terminal), referenced refunds do not need this parameter
Format: date-time
Example: "2023-11-19T10:45:00-05:00"
signatureEntryLocationdeprecated
stringNo
[Deprecated] Signature entry location. Use signatureConfig instead
Possible values:
  • ON_SCREEN- On-screen signature
  • ON_RECEIPT- On-receipt signature
Example: "ON_SCREEN"
signatureConfig
objectNo
Signature configuration. Controls the signature collection behavior after transaction completion. When this field is not provided, the SUNBAY platform's signature configuration is used by default. Only used for unreferenced refunds (requires customer interaction on terminal); not needed for referenced refunds
printReceipt
stringNo
Receipt printing option
Possible values:
  • NONE- Do not print receipt
  • MERCHANT- Print merchant copy only
  • CUSTOMER- Print customer copy only
  • BOTH- Print both merchant and customer copies
  • AUTO- Auto mode. The receipt printing behavior is automatically determined by the Tapro application
Default: "AUTO"
Example: "MERCHANT"
pushToTerminal
booleanNo
Whether to push the transaction request to the payment terminal for processing. When true, the transaction request is pushed to the specified terminal device; when false, the transaction is processed directly in the cloud
Default: true
Example: true

Request Example

{
  "appId": "smkrjobsk3sifh90",
  "merchantId": "M1261833002",
  "referenceOrderId": "ORDER20231119002",
  "transactionRequestId": "PAY_REQ_20231119006",
  "amount": {
    "orderAmount": 10000,
    "tipAmount": 500,
    "taxAmount": 800,
    "surchargeAmount": 200,
    "cashbackAmount": 1000,
    "priceCurrency": "USD"
  },
  "paymentMethod": {
    "category": "CARD",
    "id": "VISA",
    "subId": "APPLE_PAY"
  },
  "cardNetworkType": "CREDIT",
  "description": "Product return",
  "terminalSn": "T1234567890",
  "attach": "{\"reason\":\"quality_issue\"}",
  "notifyUrl": "https://merchant.com/notify",
  "timeExpire": "2023-11-19T10:45:00-05:00"
}

Code Examples

cURLbash

Response parameters

NameTypeRequiredDescription
code
string(16)Y
Response code, 0 indicates request has been successfully dispatched to terminal
Example: "0"
msg
string(128)N
Response description
Example: "Refund request sent"
traceId
string(64)Y
Trace ID for troubleshooting
Example: "TRACE123456789"
data
objectY
Last updated on
Post authVoid