### Install waffo-go SDK

Source: https://waffo-docs.mintlify.app/zh/developer-docs/sdk/go

Installs the waffo-go SDK v2. Requires Go 1.20+ and has no external dependencies beyond the standard library.

```bash
go get github.com/waffo-com/waffo-go/v2

```

--------------------------------

### Installation

Source: https://waffo-docs.mintlify.app/zh/developer-docs/sdk/php

Install the Waffo PHP SDK via Composer.

```APIDOC
## Install

### Description
Install the Waffo PHP SDK using Composer.

### Command
bash
composer require waffo/waffo-php


### Notes
- Requires PHP 8.0+
- Requires Composer
- Requires PHP extensions: cURL, JSON, OpenSSL
- Current latest version: v0.3.0 (check Packagist for latest)
```

--------------------------------

### Installation

Source: https://waffo-docs.mintlify.app/zh/developer-docs/sdk/nodejs

Install the Waffo Node.js SDK using npm, yarn, or pnpm.

```APIDOC
## Installation

### Description
Install the Waffo Node.js SDK package.

### Package Manager
npm / yarn / pnpm

### Command
```bash
npm install @waffo/waffo-node
# or
yarn add @waffo/waffo-node
# or
pnpm add @waffo/waffo-node
```
```

--------------------------------

### Install Waffo Node.js SDK

Source: https://waffo-docs.mintlify.app/zh/developer-docs/sdk/nodejs

Install the @waffo/waffo-node package using npm, yarn, or pnpm. Requires Node.js >= 18.0.0.

```bash
npm install @waffo/waffo-node
# or
yarn add @waffo/waffo-node
# or
pnpm add @waffo/waffo-node
```

--------------------------------

### Initialize waffo-go client

Source: https://waffo-docs.mintlify.app/zh/developer-docs/sdk/go

Initializes the waffo-go client using a configuration builder. Requires your API key, base64-encoded private key, Waffo public key, and merchant ID. Uses the Sandbox environment in this example.

```go
package main

import (
    "log"
    waffo "github.com/waffo-com/waffo-go/v2"
    "github.com/waffo-com/waffo-go/v2/config"
)

func main() {
    cfg, err := config.NewConfigBuilder().
        APIKey("your-api-key").
        PrivateKey("your-base64-encoded-private-key").
        WaffoPublicKey("waffo-public-key").
        MerchantID("your-merchant-id").
        Environment(config.Sandbox).
        Build()
    if err != nil {
        log.Fatal(err)
    }

    client := waffo.New(cfg)
}

```

--------------------------------

### Initialize Waffo client with config

Source: https://waffo-docs.mintlify.app/zh/developer-docs/sdk/java

Build a WaffoConfig with API key, private key, public key, merchant ID, and environment, then create a Waffo instance. Use Environment.SANDBOX for testing.

```java
import com.waffo.Waffo;
import com.waffo.types.config.WaffoConfig;
import com.waffo.types.config.Environment;

WaffoConfig config = WaffoConfig.builder()
    .apiKey("your-api-key")
    .privateKey("your-base64-encoded-private-key")
    .waffoPublicKey("waffo-public-key")
    .merchantId("your-merchant-id")
    .environment(Environment.SANDBOX)
    .build();

Waffo waffo = new Waffo(config);
```

--------------------------------

### HTML Examples for Purchase Link Embedding

Source: https://waffo-docs.mintlify.app/zh/developer-docs/point-topup/mode-a-offline-import

Two HTML examples for embedding the purchase link: a normal link and a button style. Both use the example URL https://supplier.waffoplay.com/jp/.

```html
<!-- 普通链接 -->
<a href="https://supplier.waffoplay.com/jp/">Buy Points</a>

<!-- 按钮样式 -->
<button onclick="window.location.href='https://supplier.waffoplay.com/jp/'">
    Purchase Credits
</button>
```

--------------------------------

### Initialize Waffo client

Source: https://waffo-docs.mintlify.app/zh/developer-docs/sdk/python

Create a Waffo client with your API key, private key, public key, and merchant ID. Use Environment.SANDBOX for testing.

```python
from waffo import Environment, Waffo, WaffoConfig

config = WaffoConfig(
    api_key="your-api-key",
    private_key="your-base64-encoded-private-key",
    waffo_public_key="waffo-public-key",
    merchant_id="your-merchant-id",
    environment=Environment.SANDBOX,
)

waffo = Waffo(config)
```

--------------------------------

### CSV Example for Point Card Import

Source: https://waffo-docs.mintlify.app/zh/developer-docs/point-topup/mode-a-offline-import

Example CSV file with point card data. The header row includes skuId, pointCode, faceValue, amount, currency, expiryDate, and batchNo. The example shows three rows with sample data.

```csv
skuId,pointCode,faceValue,amount,currency,expiryDate,batchNo
SUPPLIER_POINT_001,ABCD-1234-EFGH-5678,1000,1000,JPY,2026-12-31,BATCH_20250105_001
SUPPLIER_POINT_001,EFGH-5678-IJKL-9012,1000,1000,JPY,2026-12-31,BATCH_20250105_001
SUPPLIER_POINT_002,MNOP-3456-QRST-7890,3000,2900,JPY,2026-12-31,BATCH_20250105_001
```

--------------------------------

### Go: 使用 SDK handleWebhook() 处理 Webhook

Source: https://waffo-docs.mintlify.app/zh/developer-docs/webhook/signature-verification

使用 Waffo SDK 的 HandleWebhook 方法自动处理签名验证和响应构建。需要从请求头获取 X-SIGNATURE 并读取原始 body。

```Go
func webhookHandler(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    signature := r.Header.Get("X-SIGNATURE")

    result := handler.HandleWebhook(string(body), signature)

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(200)
    w.Write([]byte(result.ResponseBody))
}
```

--------------------------------

### Initialization

Source: https://waffo-docs.mintlify.app/zh/developer-docs/sdk/nodejs

Initialize the Waffo client with API key, private key, public key, merchant ID, and environment.

```APIDOC
## Initialization

### Description
Create a Waffo client instance with the required credentials and environment.

### Method
Constructor

### Parameters
- **apiKey** (string) - Required - Your API key.
- **privateKey** (string) - Required - Your base64-encoded private key.
- **waffoPublicKey** (string) - Required - Waffo public key.
- **merchantId** (string) - Required - Your merchant ID.
- **environment** (Environment) - Required - Environment (e.g., Environment.SANDBOX).

### Example
```javascript
import { Waffo, Environment } from '@waffo/waffo-node';

const waffo = new Waffo({
  apiKey: 'your-api-key',
  privateKey: 'your-base64-encoded-private-key',
  waffoPublicKey: 'waffo-public-key',
  merchantId: 'your-merchant-id',
  environment: Environment.SANDBOX,
});
```
```

--------------------------------

### Example of the string to be signed

Source: https://waffo-docs.mintlify.app/zh/developer-docs/point-topup/mode-c-direct-fulfillment

Example of the sorted and concatenated string to be signed, using the given parameters. The returnUrl value is unencoded in this step.

```text
https://supplier.waffoplay.com/redirect?amount=3000&currency=JPY&faceValue=3000&returnUrl=https://example.com/return_url_page?salesOrderId=XXX&salesOrderId=A123456&siteCode=US&supplierId=WAFFO_POINT_TOPUP_001&supplierUserAccount=supplier_user_12345&supplierUserEmail=test@supplier.com&theme=light&timestamp=1713483091000
```

--------------------------------

### Install Waffo Python SDK

Source: https://waffo-docs.mintlify.app/zh/developer-docs/sdk/python

Install the waffo package version 0.5.0b0 or the latest pre-release version using pip. Requires Python 3.9+.

```bash
python -m pip install "waffo==0.5.0b0"
# 或安装最新预发布版本
python -m pip install --pre waffo
```

--------------------------------

### Initialize Waffo Client

Source: https://waffo-docs.mintlify.app/zh/developer-docs/sdk/nodejs

Create a Waffo instance with your API key, base64-encoded private key, public key, merchant ID, and environment (SANDBOX or PRODUCTION).

```typescript
import { Waffo, Environment } from '@waffo/waffo-node';

const waffo = new Waffo({
  apiKey: 'your-api-key',
  privateKey: 'your-base64-encoded-private-key',
  waffoPublicKey: 'waffo-public-key',
  merchantId: 'your-merchant-id',
  environment: Environment.SANDBOX,
});
```

--------------------------------

### Complete signed redirect URL example

Source: https://waffo-docs.mintlify.app/zh/developer-docs/point-topup/mode-c-direct-fulfillment

Complete example URL with the signature appended. Note that returnUrl is URL-encoded in the final URL, while the string to be signed uses the unencoded value.

```text
https://supplier.waffoplay.com/redirect?amount=3000&currency=JPY&faceValue=3000&returnUrl=https%3A%2F%2Fexample.com%2Freturn_url_page%3FsalesOrderId%3DXXX&salesOrderId=A123456&siteCode=US&supplierId=WAFFO_POINT_TOPUP_001&supplierUserAccount=supplier_user_12345&supplierUserEmail=test@supplier.com&theme=light&timestamp=1713483091000&signature=ABC123XYZ456DEF789
```

--------------------------------

### Example Reconciliation Report CSV

Source: https://waffo-docs.mintlify.app/zh/developer-docs/tools-and-references/references/reconciliation-reports

A sample CSV report showing the expected format and field order for reconciliation reports. The header row lists all fields, and the data rows show example transactions including payments and refunds.

```csv
Merchant Id,Sub Merchant Id,Settlement Batch Id,Settlement Date,Order Id,Merchant Order Id,Payment Request Id,Original Order Id,Order Amount,Order Amount (Settlement Currency),Order Currency,Transaction Type,Payment Method Type,Payment Method,Payment Option,Payment Request Datetime,Payment Date,Payment Time,Product Name,Forex Currency Pair,Forex Rate,Fee Amount,Fee Amount (Settlement Currency),Fee Currency,VAT Amount,VAT Amount (Settlement Currency),VAT Currency,WHT Amount,WHT Amount (Settlement Currency),WHT Currency,Settlement Amount,Settlement Currency
1000000001,2000000001,S2024073108214,2020-08-08,A202407310821400761571,MO202407310821400601331,PR2024073108214006013331,,100.00,100.00,USD,PAYMENT,EWALLET,ALIPAY,,2024-08-06 16:21:00,2024-08-06,16:21:00,ONE_TIME_PAYMENT,,,1.00,1.00,USD,,,,,,,99.00,USD
1000000001,2000000001,S2024073108214,2020-08-08,A202407310826263631572,MO202407310821400601332,PR2024073108214006013332,A202407310821400761571,10.00,10.00,USD,REFUND,EWALLET,ALIPAY,,2024-08-06 16:22:00,2024-08-06,16:22:00,ONE_TIME_PAYMENT,,,0.00,0.00,USD,,,,,,,-10.00,USD
1000000001,2000000001,S2024073108214,2020-08-08,A202407310821400761573,MO202407310821400601333,PR2024073108214006013333,,100.00,12.83,HKD,PAYMENT,EWALLET,ALIPAY,,2024-08-06 16:23:00,2024-08-06,16:23:00,ONE_TIME_PAYMENT,USD/HKD,7.79217921,1.00,0.12,HKD,,,,,,,12.71,USD
1000000001,2000000001,S2024073108214,2020-08-08,A202407310826263631584,MO202407310821400601334,PR2024073108214006013334,A202407310821400761573,10.00,1.28,HKD,REFUND,EWALLET,ALIPAY,,2024-08-06 16:24:00,2024-08-06,16:24:00,ONE_TIME_PAYMENT,USD/HKD,7.79217921,0.00,0.00,HKD,,,,,,,-1.28,USD
```

--------------------------------

### 创建支付并声明后续使用（setupFutureUsage: true）

Source: https://waffo-docs.mintlify.app/zh/developer-docs/integration/tokenization/checkout-card-binding

在创建支付请求中设置 paymentInfo.setupFutureUsage 为 true，以声明本次支付用于后续 MIT。不要同时传入 setupFutureUsage 和 userPaymentAccessToken。

```json
{
  "paymentRequestId": "PAY_202609160001",
  "merchantOrderId": "ORDER_202609160001",
  "orderCurrency": "HKD",
  "orderAmount": "100.00",
  "orderDescription": "Initial payment with card binding",
  "orderRequestedAt": "2026-09-17T02:00:00.000Z",
  "notifyUrl": "https://merchant.example.com/webhooks/payment",
  "successRedirectUrl": "https://merchant.example.com/payment/success",
  "failedRedirectUrl": "https://merchant.example.com/payment/failed",
  "merchantInfo": {
    "merchantId": "YOUR_MERCHANT_ID"
  },
  "userInfo": {
    "userId": "USER_001",
    "userEmail": "user@example.com",
    "userTerminal": "WEB",
    "userCountryCode": "HKG"
  },
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "setupFutureUsage": true
  }
}
```

--------------------------------

### Settlement Summary Report CSV Example

Source: https://waffo-docs.mintlify.app/zh/developer-docs/tools-and-references/references/reconciliation-reports

Example CSV content showing the report structure with columns for merchant ID, settlement batch ID, settlement date, transaction type, transaction count, fee, VAT, WHT, settlement amount, and currency. The rows include TOTAL, PAYMENT, REFUND, and CHARGEBACK transaction types.

```csv
Merchant Id,Settlement Batch Id,Settlement Date,Transaction Type,Transaction Count,Fee Amount (Settlement Currency),VAT Amount (Settlement Currency),WHT Amount (Settlement Currency),Settlement Amount,Settlement Currency
1000000001,S2024073108214,2020-08-08,TOTAL,100,1.12,1.12,,90.42,USD
1000000001,S2024073108214,2020-08-08,PAYMENT,97,1.00,1.12,,111.70,USD
1000000001,S2024073108214,2020-08-08,REFUND,2,,,,-11.28,USD
1000000001,S2024073108214,2020-08-08,CHARGEBACK,1,0.12,,,-10.00,USD
```

--------------------------------

### SDK 传入：初始化 WaffoSDK 主题配置

Source: https://waffo-docs.mintlify.app/zh/developer-docs/integration/checkout/customization

Initializes the frontend SDK (@waffo/payment-sdk) with theme variables. This method has the lowest priority and only applies when neither API nor Merchant Portal configuration is set.

```javascript
const waffo = new WaffoSDK({
  env: 'production',
  appearance: {
    variables: {
      colorPrimary: '#0570de',
      colorBackground: '#ffffff',
      colorText: '#30313d',
      borderRadius: '8px'
    }
  }
});
```

--------------------------------

### Set cashierLogoUrl with Portal pre-created ID

Source: https://waffo-docs.mintlify.app/zh/developer-docs/integration/checkout/customization

Uses a logo pre-created via Merchant Portal. The value must start with `logo_` and is obtained after uploading the logo in the Portal.

```json
{
  "brandInfo": {
    "cashierLogoUrl": "logo_abc123"
  }
}
```

--------------------------------

### 初始化客户端 (Java)

Source: https://waffo-docs.mintlify.app/zh/developer-docs/getting-started/quickstart

使用构建器模式配置 WaffoConfig，并创建 Waffo 实例。

```java
import com.waffo.Waffo;
import com.waffo.types.config.WaffoConfig;
import com.waffo.types.config.Environment;

WaffoConfig config = WaffoConfig.builder()
    .apiKey(System.getenv("WAFFO_API_KEY"))
    .privateKey(System.getenv("WAFFO_PRIVATE_KEY"))
    .waffoPublicKey(System.getenv("WAFFO_PUBLIC_KEY"))
    .merchantId(System.getenv("WAFFO_MERCHANT_ID"))
    .environment(Environment.SANDBOX)
    .build();

Waffo waffo = new Waffo(config);

```