Skip to main content

Documentation Index

Fetch the complete documentation index at: https://waffo.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Response Codes

Waffo API response format: 
{
  "code": "0",
  "msg": "Success",
  "data": { ... }
}
  • code of "0" indicates success
  • On failure, code is an error code string (e.g., "A0003", "E0001")
  • The response field is named msg (not message)

​
Error Code Categories

PrefixCategoryDescription
0Success—
AMerchant errorInvalid parameters, insufficient permissions, etc.
BUser errorInsufficient balance, payment timeout, etc.
CSystem errorChannel rejection, system errors, etc.
DRisk Control rejectionTransaction blocked by Risk Control
EUnknown errorCritical: payment may have succeeded
For the full error code list, see Error Code Reference.

​
Handling E0001 Unknown Status

This is the most critical exception scenario. When you encounter a network timeout, connection interruption, or the server returns E0001, the payment status is unknown.

​
Principles

  • Do not assume failure: a network timeout does not mean the payment failed
  • Do not automatically close the order: the payment may have already completed on the channel side
  • Do not create a new order: use the original paymentRequestId to query

​
Error Types in the SDK

LanguageUnknown status errorClient error
Node.jsWaffoUnknownStatusErrorWaffoError
JavaWaffoUnknownStatusExceptionWaffoException
Go*core.WaffoUnknownStatusError*core.WaffoError
The SDK has only two error types. WaffoUnknownStatusError/Exception means the payment may have succeeded, while WaffoError/Exception indicates a client-side error (configuration, signature, etc.).

​
SDK Error Codes

Error codeTypeDescription
S0001UnknownStatusNetwork error (timeout, connection failure)
E0001UnknownStatusServer returned unknown status
S0002ErrorInvalid public key
S0003ErrorSignature failed
S0004ErrorResponse signature verification failed
S0005ErrorRequest serialization failed
S0007ErrorInvalid private key

​
Handling Flow

Network timeout / E0001 / WaffoUnknownStatusError
    │
    ▼
Query using the original paymentRequestId
    │
    ├── PAY_SUCCESS found    → Update local status to success
    ├── ORDER_CLOSE found    → Update local status to failure
    └── Still unknown        → Wait for Webhook notification

​
Code Example

import { WaffoUnknownStatusError, WaffoError } from '@waffo/waffo-node';

try {
  const response = await waffo.order().create(params);
  if (response.isSuccess()) {
    // code === "0", handle success
  } else {
    // API returned an error code (e.g. A0003), safe to treat as failure
  }
} catch (error) {
  if (error instanceof WaffoUnknownStatusError) {
    // Important: payment may have succeeded! Query before deciding
    const inquiry = await waffo.order().inquiry({ paymentRequestId });
    if (inquiry.isSuccess()) {
      const status = inquiry.getData().orderStatus;
      await updateOrderStatus(paymentRequestId, status);
    }
    // If the query also fails, wait for a Webhook
  } else if (error instanceof WaffoError) {
    // Client error (configuration, signature), safe to retry after fixing
    console.error('Client error:', error.errorCode, error.message);
  }
}