Yunzhanghu SDK for Go

https://github.com/yunzhanghuopen/sdk-go
Admin
A Go SDK that encapsulates Yunzhanghu comprehensive service platform APIs, providing features for...
Tokens:10,665
Snippets:27
Trust Score:5.4
License:MIT
Update:10 months ago
Show doc for...
Tokens:
Raw
### GET /order

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Retrieves detailed information about a specific payment order, including its status and transaction details.

```APIDOC
## GET /order

### Description
Retrieve detailed information about a payment order including status and transaction details.

### Method
GET

### Endpoint
/order

### Parameters
#### Query Parameters
- **OrderID** (string) - Required - The unique identifier of the order to query.
- **Channel** (string) - Optional - The payment channel used (e.g., "银行卡", "支付宝", "微信").
- **DataType** (string) - Optional - Specifies the data type for the response, e.g., "encryption" to enable encryption for sensitive data.

### Request Example
```
GET /order?OrderID=ORD1234567890&Channel=支付宝&DataType=encryption
```

### Response
#### Success Response (200)
- **Status** (string) - The current status of the order.
- **StatusMessage** (string) - A human-readable message describing the order status.
- **Pay** (string) - The total amount of the order.
- **UserRealAmount** (string) - The actual amount received by the user.
- **Ref** (string) - The broker's reference number for the transaction.
- **BrokerBankBill** (string) - The bank bill identifier from the broker.
- **CreatedAt** (string) - The timestamp when the order was created.
- **FinishedTime** (string) - The timestamp when the order was finished.
- **TaxDetail** (object) - Optional - Contains details about taxes applied.
  - **PersonalTax** (string) - The amount of personal tax.
  - **ValueAddedTax** (string) - The amount of Value Added Tax.
  - **AdditionalTax** (string) - The amount of additional tax.

#### Response Example
```json
{
  "OrderID": "ORD1234567890",
  "Status": "SUCCESS",
  "StatusMessage": "Payment successful",
  "Pay": "199.50",
  "UserRealAmount": "190.00",
  "Ref": "some_reference_id",
  "BrokerBankBill": "bank_bill_xyz",
  "CreatedAt": "2023-03-15T10:00:00Z",
  "FinishedTime": "2023-03-15T10:05:00Z",
  "TaxDetail": {
    "PersonalTax": "5.00",
    "ValueAddedTax": "3.00",
    "AdditionalTax": "1.50"
  }
}
```

#### Error Response (e.g., 404 Not Found)
- **Code** (string) - Error code.
- **Message** (string) - Error message.

#### Error Response Example
```json
{
  "Code": "2018",
  "Message": "Order does not exist"
}
```
```

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

### Client Initialization

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Initialize the SDK client with authentication credentials and configuration options. Supports middleware for request/response logging and debugging.

```APIDOC
## Client Initialization

### Description
Initialize the SDK client with authentication credentials and configuration options. Supports middleware for request/response logging and debugging.

### Method
Initialization (not an HTTP method, but a setup process)

### Endpoint
N/A (Client-side setup)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
package main

import (
    "context"
    "fmt"
    "net/http"

    "github.com/YunzhanghuOpen/sdk-go/api"
    "github.com/YunzhanghuOpen/sdk-go/core"
)

func main() {
    // Configure SDK with platform credentials
    conf := &api.Config{
        Host:       api.ProductHost,  // Use api.SandboxHost for testing
        DealerID:   "your_dealer_id",
        PrivateKey: "-----BEGIN PRIVATE KEY-----\nYourPrivateKeyHere\n-----END PRIVATE KEY-----",
        AppKey:     "your_app_key",
        Des3Key:    "your_3des_key",
    }

    // Create client with optional middleware
    logMiddleware := func(next core.Handler) core.Handler {
        return func(ctx context.Context, req interface{}) (interface{}, error) {
            fmt.Println("Request:", req)
            resp, err := next(ctx, req)
            fmt.Println("Response:", resp)
            return resp, err
        }
    }

    client, err := api.New(conf,
        core.WithHttpClient(&http.Client{}),
        core.WithMiddleware(logMiddleware),
        core.EnDebug(),
    )
    if err != nil {
        panic(err)
    }

    fmt.Println("SDK initialized successfully")
}
```

### Response
#### Success Response (Initialization)
SDK client is initialized successfully.

#### Response Example
```
SDK initialized successfully
```
```

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

### Initialize Yunzhanghu Go SDK Client

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Initializes the Yunzhanghu SDK client with configuration details including host, dealer ID, private key, app key, and DES3 key. It demonstrates how to add optional middleware like request/response logging and enables debug mode. The function returns an initialized client instance or an error.

```go
package main

import (
    "context"
    "fmt"
    "net/http"

    "github.com/YunzhanghuOpen/sdk-go/api"
    "github.com/YunzhanghuOpen/sdk-go/core"
)

func main() {
    // Configure SDK with platform credentials
    conf := &api.Config{
        Host:       api.ProductHost,  // Use api.SandboxHost for testing
        DealerID:   "your_dealer_id",
        PrivateKey: "-----BEGIN PRIVATE KEY-----\nYourPrivateKeyHere\n-----END PRIVATE KEY-----",
        AppKey:     "your_app_key",
        Des3Key:    "your_3des_key",
    }

    // Create client with optional middleware
    logMiddleware := func(next core.Handler) core.Handler {
        return func(ctx context.Context, req interface{}) (interface{}, error) {
            fmt.Println("Request:", req)
            resp, err := next(ctx, req)
            fmt.Println("Response:", resp)
            return resp, err
        }
    }

    client, err := api.New(conf,
        core.WithHttpClient(&http.Client{}),
        core.WithMiddleware(logMiddleware),
        core.EnDebug(),
    )
    if err != nil {
        panic(err)
    }

    fmt.Println("SDK initialized successfully")
}
```

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

### Initiate H5 Contract Signing with Go

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Initiates a user contract signing process via an H5 web interface. It requires a pre-sign step to obtain a token, followed by requesting the H5 signing URL. Dependencies include the SDK's `api` client and `errorx` for error handling. Inputs include dealer and broker IDs, user's real name, ID card number, certificate type, and a flag to collect phone numbers. Outputs are a signing URL and status codes.

```go
func h5UserSigning(client *api.Client) {
    // Step 1: Pre-sign to get token
    presignReq := &api.H5UserPresignRequest{
        DealerID:        "dealer_123456",
        BrokerID:        "broker_123456",
        RealName:        "张三",
        IDCard:          "11010519491231002X",
        CertificateType: 0,  // 0: ID card
        CollectPhoneNo:  1,  // Collect phone number
    }

    presignResp, err := client.H5UserPresign(context.Background(), presignReq)
    if err != nil {
        e, _ := errorx.FromError(err)
        fmt.Printf("Pre-sign failed: %s\n", e.Message)
        return
    }

    fmt.Printf("Pre-sign successful, Token: %s, Status: %d\n",
        presignResp.Token, presignResp.Status)

    // Step 2: Get H5 signing URL
    signReq := &api.H5UserSignRequest{
        Token: presignResp.Token,
        Color: "#007AFF",  // Custom theme color
    }

    signResp, err := client.H5UserSign(context.Background(), signReq)
    if err != nil {
        e, _ := errorx.FromError(err)
        fmt.Printf("Sign request failed: %s\n", e.Message)
        return
    }

    fmt.Printf("H5 Signing URL: %s\n", signResp.URL)
    fmt.Println("Redirect user to this URL to complete signing")
}
```

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

### POST /alipay/order

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Initiates a real-time payment through Alipay. This endpoint is used to create payment orders that will be processed by Alipay.

```APIDOC
## POST /alipay/order

### Description
Process real-time payments through Alipay accounts. This endpoint creates a payment order to be processed by Alipay.

### Method
POST

### Endpoint
/alipay/order

### Parameters
#### Request Body
- **BrokerID** (string) - Required - Identifier for the broker.
- **DealerID** (string) - Required - Identifier for the dealer.
- **OrderID** (string) - Required - Unique identifier for the order.
- **RealName** (string) - Required - The real name of the Alipay user.
- **IDCard** (string) - Required - The ID card number of the Alipay user.
- **CardNo** (string) - Required - The Alipay account number or associated email/phone.
- **PhoneNo** (string) - Required - The phone number of the Alipay user.
- **Pay** (string) - Required - The amount to be paid.
- **PayRemark** (string) - Optional - Remark for the payment.
- **NotifyURL** (string) - Required - The URL to send payment notifications to.
- **CheckName** (string) - Optional - Flag to check the user's name.
- **DealerPlatformName** (string) - Optional - Name of the dealer's platform.
- **DealerUserNickname** (string) - Optional - Nickname of the dealer's user.
- **DealerUserID** (string) - Optional - User ID on the dealer's platform.

### Request Example
```json
{
  "BrokerID": "broker_123456",
  "DealerID": "dealer_123456",
  "OrderID": "ALI1678886400",
  "RealName": "李四",
  "IDCard": "440524188001010014",
  "CardNo": "lisialipay@example.com",
  "PhoneNo": "13900139000",
  "Pay": "199.50",
  "PayRemark": "服务费结算",
  "NotifyURL": "https://your-domain.com/callback/alipay",
  "CheckName": "Check",
  "DealerPlatformName": "示例电商平台",
  "DealerUserNickname": "lisi_shop",
  "DealerUserID": "user_100002"
}
```

### Response
#### Success Response (200)
- **OrderID** (string) - The order ID created.
- **Ref** (string) - A reference number for the transaction.

#### Response Example
```json
{
  "OrderID": "ALI1678886400",
  "Ref": "some_reference_id"
}
```
```

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

### Create Alipay Payment Order using Go

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Creates a real-time payment order through Alipay. Requires a configured API client and provides details such as broker ID, dealer ID, order ID, user information, payment amount, and callback URL. Returns the created order ID and a reference number upon success.

```go
func createAlipayOrder(client *api.Client) {
    req := &api.CreateAlipayOrderRequest{
        BrokerID:           "broker_123456",
        DealerID:           "dealer_123456",
        OrderID:            fmt.Sprintf("ALI%d", time.Now().Unix()),
        RealName:           "李四",
        IDCard:             "440524188001010014",
        CardNo:             "lisialipay@example.com",
        PhoneNo:            "13900139000",
        Pay:                "199.50",
        PayRemark:          "服务费结算",
        NotifyURL:          "https://your-domain.com/callback/alipay",
        CheckName:          "Check",
        DealerPlatformName: "示例电商平台",
        DealerUserNickname: "lisi_shop",
        DealerUserID:       "user_100002",
    }

    ctx := core.WithRequestID(context.Background(), req.OrderID)
    resp, err := client.CreateAlipayOrder(ctx, req)
    if err != nil {
        e, ok := errorx.FromError(err)
        if !ok {
            fmt.Println("Error:", err)
            return
        }
        fmt.Printf("Failed: %s - %s\n", e.Code, e.Message)
        return
    }

    fmt.Printf("Alipay order created - OrderID: %s, Ref: %s\n",
        resp.OrderID, resp.Ref)
}
```

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

### H5 Contract Signing API

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Initiates the contract signing process for a user via an H5 web interface. This involves two steps: pre-signing to obtain a token and then generating the H5 signing URL.

```APIDOC
## POST /h5/user/presign

### Description
Obtains a token required for initiating the H5 contract signing process.

### Method
POST

### Endpoint
/h5/user/presign

### Parameters
#### Request Body
- **DealerID** (string) - Required - The ID of the dealer.
- **BrokerID** (string) - Required - The ID of the broker.
- **RealName** (string) - Required - The real name of the user.
- **IDCard** (string) - Required - The ID card number of the user.
- **CertificateType** (integer) - Required - The type of certificate (e.g., 0 for ID card).
- **CollectPhoneNo** (integer) - Required - Flag to indicate if the phone number should be collected.

### Request Example
```json
{
  "DealerID": "dealer_123456",
  "BrokerID": "broker_123456",
  "RealName": "张三",
  "IDCard": "11010519491231002X",
  "CertificateType": 0,
  "CollectPhoneNo": 1
}
```

### Response
#### Success Response (200)
- **Token** (string) - The token for signing.
- **Status** (integer) - The status of the pre-sign operation.

#### Response Example
```json
{
  "Token": "some_presign_token",
  "Status": 1
}
```

## POST /h5/user/sign

### Description
Generates the H5 signing URL for the user to complete contract signing.

### Method
POST

### Endpoint
/h5/user/sign

### Parameters
#### Request Body
- **Token** (string) - Required - The token obtained from the pre-sign step.
- **Color** (string) - Optional - Custom theme color for the signing interface.

### Request Example
```json
{
  "Token": "some_presign_token",
  "Color": "#007AFF"
}
```

### Response
#### Success Response (200)
- **URL** (string) - The URL for the H5 signing interface.

#### Response Example
```json
{
  "URL": "https://example.com/sign?token=some_presign_token"
}
```
```

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

### POST /api/bankpay/order

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Create a real-time payment order to transfer funds to a user's bank account. Handles various payment methods and includes detailed order information.

```APIDOC
## POST /api/bankpay/order

### Description
Create a real-time payment order to transfer funds to a user's bank account. Handles various payment methods and includes detailed order information.

### Method
POST

### Endpoint
/api/bankpay/order

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **BrokerID** (string) - Required - Broker identifier.
- **DealerID** (string) - Required - Dealer identifier.
- **OrderID** (string) - Required - Unique order identifier.
- **RealName** (string) - Required - Real name of the recipient.
- **IDCard** (string) - Required - ID card number of the recipient.
- **CardNo** (string) - Required - Bank card number for payment.
- **PhoneNo** (string) - Required - Phone number of the recipient.
- **Pay** (string) - Required - Amount to be paid.
- **PayRemark** (string) - Optional - Remark for the payment.
- **NotifyURL** (string) - Required - Callback URL for payment notifications.
- **ProjectID** (string) - Optional - Project identifier.
- **DealerPlatformName** (string) - Optional - Name of the dealer's platform.
- **DealerUserNickname** (string) - Optional - Nickname of the dealer's user.
- **DealerUserID** (string) - Optional - User ID on the dealer's platform.

### Request Example
```go
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/YunzhanghuOpen/sdk-go/api"
    "github.com/YunzhanghuOpen/sdk-go/core"
    "github.com/YunzhanghuOpen/sdk-go/errorx"
)

func createBankPayment(client *api.Client) {
    orderID := fmt.Sprintf("ORD%d", time.Now().Unix())

    req := &api.CreateBankpayOrderRequest{
        BrokerID:           "broker_123456",
        DealerID:           "dealer_123456",
        OrderID:            orderID,
        RealName:           "张三",
        IDCard:             "11010519491231002X",
        CardNo:             "6228888888888888888",
        PhoneNo:            "13800138000",
        Pay:                "99.99",
        PayRemark:          "项目收益结算",
        NotifyURL:          "https://your-domain.com/callback/payment",
        ProjectID:          "project_001",
        DealerPlatformName: "示例平台",
        DealerUserNickname: "zhangsan",
        DealerUserID:       "user_100001",
    }

    ctx := core.WithRequestID(context.Background(), orderID)
    resp, err := client.CreateBankpayOrder(ctx, req)
    if err != nil {
        e, ok := errorx.FromError(err)
        if !ok {
            fmt.Println("System error:", err)
            return
        }

        switch e.Code {
        case "2002":
            fmt.Println("Duplicate order ID, check existing order")
        case "2018":
            fmt.Println("Order not found")
        default:
            fmt.Printf("Error %s: %s\n", e.Code, e.Message)
        }
        return
    }

    fmt.Printf("Payment created - OrderID: %s, Ref: %s, Amount: %s\n",
        resp.OrderID, resp.Ref, resp.Pay)
}
```

### Response
#### Success Response (200)
- **OrderID** (string) - The order ID.
- **Ref** (string) - A reference number for the transaction.
- **Pay** (string) - The amount paid.

#### Response Example
```json
{
  "OrderID": "ORD1678886400",
  "Ref": "REF123456789",
  "Pay": "99.99"
}
```

#### Error Responses
- **2002**: Duplicate order ID.
- **2018**: Order not found.
```

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

### Query Platform Balance with Go

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Retrieves the account balances across different payment channels for a given dealer. The function takes a dealer ID as input and outputs the balances for bank cards, Alipay, WeChat Pay, service fees, rebates, and the total balance. Dependencies include the SDK's `api` client and `errorx`. The output is printed to the console, detailing balances per broker ID.

```go
func checkPlatformBalance(client *api.Client) {
    req := &api.ListAccountRequest{
        DealerID: "dealer_123456",
    }

    resp, err := client.ListAccount(context.Background(), req)
    if err != nil {
        e, _ := errorx.FromError(err)
        fmt.Printf("Balance query failed: %s\n", e.Message)
        return
    }

    fmt.Println("Platform Account Balances:")
    for _, account := range resp.DealerInfos {
        fmt.Printf("\nBroker ID: %s\n", account.BrokerID)

        if account.IsBankCard {
            fmt.Printf("  Bank Card: ¥%s\n", account.BankCardBalance)
        }
        if account.IsAlipay {
            fmt.Printf("  Alipay: ¥%s\n", account.AlipayBalance)
        }
        if account.IsWxpay {
            fmt.Printf("  WeChat: ¥%s\n", account.WxpayBalance)
        }

        fmt.Printf("  Service Fee Balance: ¥%s\n", account.AcctBalance)
        fmt.Printf("  Rebate Balance: ¥%s\n", account.RebateFeeBalance)
        fmt.Printf("  Total Balance: ¥%s\n", account.TotalBalance)
    }
}
```

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

### POST /wechat/order

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Initiates a payment via WeChat using the user's OpenID. This endpoint is used to create payment orders for WeChat.

```APIDOC
## POST /wechat/order

### Description
Process payments via WeChat using user's OpenID. This endpoint creates a payment order to be processed by WeChat Pay.

### Method
POST

### Endpoint
/wechat/order

### Parameters
#### Request Body
- **BrokerID** (string) - Required - Identifier for the broker.
- **DealerID** (string) - Required - Identifier for the dealer.
- **OrderID** (string) - Required - Unique identifier for the order.
- **RealName** (string) - Required - The real name of the WeChat user.
- **IDCard** (string) - Required - The ID card number of the WeChat user.
- **Openid** (string) - Required - The OpenID of the WeChat user.
- **PhoneNo** (string) - Required - The phone number of the WeChat user.
- **Pay** (string) - Required - The amount to be paid.
- **PayRemark** (string) - Optional - Remark for the payment.
- **NotifyURL** (string) - Required - The URL to send payment notifications to.
- **WxAppID** (string) - Required - The WeChat AppID.
- **WxpayMode** (string) - Required - The WeChat Pay mode (e.g., "transfer").
- **DealerPlatformName** (string) - Optional - Name of the dealer's platform.
- **DealerUserNickname** (string) - Optional - Nickname of the dealer's user.
- **DealerUserID** (string) - Optional - User ID on the dealer's platform.

### Request Example
```json
{
  "BrokerID": "broker_123456",
  "DealerID": "dealer_123456",
  "OrderID": "WX1678886400",
  "RealName": "王五",
  "IDCard": "11010519491231002X",
  "Openid": "o4GgauInH_RCEdvrrNGrntXDuXXX",
  "PhoneNo": "13700137000",
  "Pay": "299.99",
  "PayRemark": "任务奖励",
  "NotifyURL": "https://your-domain.com/callback/wechat",
  "WxAppID": "wx1234567890abcdef",
  "WxpayMode": "transfer",
  "DealerPlatformName": "示例小程序",
  "DealerUserNickname": "wangwu",
  "DealerUserID": "user_100003"
}
```

### Response
#### Success Response (200)
- **OrderID** (string) - The order ID created.
- **Ref** (string) - A reference number for the transaction.

#### Response Example
```json
{
  "OrderID": "WX1678886400",
  "Ref": "some_reference_id"
}
```
```

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

### Create WeChat Payment Order using Go

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Initiates a WeChat payment order. This function requires an API client and WeChat-specific parameters like WxAppID and OpenID, along with standard order details. It handles payment processing and returns the order ID and reference number upon successful creation.

```go
func createWechatOrder(client *api.Client) {
    req := &api.CreateWxpayOrderRequest{
        BrokerID:           "broker_123456",
        DealerID:           "dealer_123456",
        OrderID:            fmt.Sprintf("WX%d", time.Now().Unix()),
        RealName:           "王五",
        IDCard:             "11010519491231002X",
        Openid:             "o4GgauInH_RCEdvrrNGrntXDuXXX",
        PhoneNo:            "13700137000",
        Pay:                "299.99",
        PayRemark:          "任务奖励",
        NotifyURL:          "https://your-domain.com/callback/wechat",
        WxAppID:            "wx1234567890abcdef",
        WxpayMode:          "transfer",
        DealerPlatformName: "示例小程序",
        DealerUserNickname: "wangwu",
        DealerUserID:       "user_100003",
    }

    ctx := core.WithRequestID(context.Background(), req.OrderID)
    resp, err := client.CreateWxpayOrder(ctx, req)
    if err != nil {
        e, ok := errorx.FromError(err)
        if !ok {
            fmt.Println("Error:", err)
            return
        }
        fmt.Printf("Payment failed: %s\n", e.Message)
        return
    }

    fmt.Printf("WeChat payment created - OrderID: %s, Ref: %s\n",
        resp.OrderID, resp.Ref)
}
```

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

### Handle Payment Order Callback (Go)

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Processes asynchronous payment status notifications received via HTTP POST requests. It parses the callback data, verifies the signature using provided credentials, and updates the order status based on the received information. Dependencies include standard Go libraries and Yun Zhanghu Open SDK's api and crypto packages. It expects form-encoded POST data and responds with 'SUCCESS' on successful processing.

```go
package main

import (
    "encoding/json"
    "fmt"
    "net/http"

    "github.com/YunzhanghuOpen/sdk-go/api"
    "github.com/YunzhanghuOpen/sdk-go/crypto"
)

func handlePaymentCallback(w http.ResponseWriter, r *http.Request) {
    if err := r.ParseForm(); err != nil {
        http.Error(w, "Invalid request", http.StatusBadRequest)
        return
    }

    // Extract callback parameters
    data := r.PostForm.Get("data")
    timestamp := r.PostForm.Get("timestamp")
    mess := r.PostForm.Get("mess")
    sign := r.PostForm.Get("sign")
    signType := r.PostForm.Get("sign_type")

    // Verify signature (implement signature verification)
    appKey := "your_app_key"
    if !crypto.VerifySign(appKey, timestamp, data, sign, signType) {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    // Parse notification data
    var notification api.NotifyOrderRequestV2
    if err := json.Unmarshal([]byte(mess), &notification); err != nil {
        http.Error(w, "Parse error", http.StatusBadRequest)
        return
    }

    // Process based on order status
    orderData := notification.Data
    fmt.Printf("Order %s status: %s\n", orderData.OrderID, orderData.Status)

    switch orderData.Status {
    case "0":
        fmt.Println("Order pending")
    case "1":
        fmt.Printf("Payment successful - User received: %s\n", orderData.UserRealAmount)
        // Update your database
    case "2":
        fmt.Printf("Payment failed: %s\n", orderData.StatusDetailMessage)
        // Handle failure
    case "3":
        fmt.Println("Order processing")
    }

    // Respond to acknowledge receipt
    w.WriteHeader(http.StatusOK)
    w.Write([]byte("SUCCESS"))
}

func main() {
    http.HandleFunc("/callback/payment", handlePaymentCallback)
    http.ListenAndServe(":8080", nil)
}

```

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

### Query Platform Balance API

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Retrieves the account balances across different payment channels for a given dealer. This includes bank card, Alipay, WeChat, and other account balances.

```APIDOC
## GET /platform/balance

### Description
Fetches the platform account balances for a specified dealer, including balances across various payment channels.

### Method
GET

### Endpoint
/platform/balance

### Parameters
#### Query Parameters
- **DealerID** (string) - Required - The ID of the dealer for whom to query balances.

### Request Example
```
GET /platform/balance?DealerID=dealer_123456
```

### Response
#### Success Response (200)
- **DealerInfos** (array) - A list of account information for the dealer.
  - **BrokerID** (string) - The ID of the broker.
  - **IsBankCard** (boolean) - Indicates if a bank card account exists.
  - **BankCardBalance** (string) - The balance in the bank card account.
  - **IsAlipay** (boolean) - Indicates if an Alipay account exists.
  - **AlipayBalance** (string) - The balance in the Alipay account.
  - **IsWxpay** (boolean) - Indicates if a WeChat Pay account exists.
  - **WxpayBalance** (string) - The balance in the WeChat Pay account.
  - **AcctBalance** (string) - The service fee balance.
  - **RebateFeeBalance** (string) - The rebate fee balance.
  - **TotalBalance** (string) - The total balance.

#### Response Example
```json
{
  "DealerInfos": [
    {
      "BrokerID": "broker_123456",
      "IsBankCard": true,
      "BankCardBalance": "1000.50",
      "IsAlipay": true,
      "AlipayBalance": "500.75",
      "IsWxpay": false,
      "WxpayBalance": "0.00",
      "AcctBalance": "200.00",
      "RebateFeeBalance": "50.25",
      "TotalBalance": "1751.50"
    }
  ]
}
```
```

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

### POST /callback/payment

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Handles asynchronous payment status notifications from the platform. It verifies the signature, parses the notification data, and processes the order status accordingly. The endpoint acknowledges receipt with a SUCCESS message.

```APIDOC
## POST /callback/payment

### Description
Handles asynchronous payment status notifications from the platform. It verifies the signature, parses the notification data, and processes the order status accordingly. The endpoint acknowledges receipt with a SUCCESS message.

### Method
POST

### Endpoint
/callback/payment

### Parameters
#### Query Parameters
- **data** (string) - Required - Encrypted callback data.
- **timestamp** (string) - Required - Timestamp of the notification.
- **mess** (string) - Required - The actual notification payload, usually JSON.
- **sign** (string) - Required - The signature for the request.
- **sign_type** (string) - Required - The type of signature used (e.g., RSA, MD5).

### Request Example
```
POST /callback/payment?data=...&timestamp=...&mess=...&sign=...&sign_type=...
```

### Response
#### Success Response (200)
- **Success message** (string) - Acknowledges successful receipt of the callback.

#### Response Example
```
SUCCESS
```
```

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

### Create Bank Card Payment Order in Go

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Creates a real-time payment order for bank card transfers using the Yunzhanghu SDK. It requires detailed request parameters including broker, dealer, order, user, and payment information. The function handles potential API errors by checking specific error codes and prints the successful order details or error messages.

```go
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/YunzhanghuOpen/sdk-go/api"
    "github.com/YunzhanghuOpen/sdk-go/core"
    "github.com/YunzhanghuOpen/sdk-go/errorx"
)

func createBankPayment(client *api.Client) {
    orderID := fmt.Sprintf("ORD%d", time.Now().Unix())

    req := &api.CreateBankpayOrderRequest{
        BrokerID:           "broker_123456",
        DealerID:           "dealer_123456",
        OrderID:            orderID,
        RealName:           "张三",
        IDCard:             "11010519491231002X",
        CardNo:             "6228888888888888888",
        PhoneNo:            "13800138000",
        Pay:                "99.99",
        PayRemark:          "项目收益结算",
        NotifyURL:          "https://your-domain.com/callback/payment",
        ProjectID:          "project_001",
        DealerPlatformName: "示例平台",
        DealerUserNickname: "zhangsan",
        DealerUserID:       "user_100001",
    }

    ctx := core.WithRequestID(context.Background(), orderID)
    resp, err := client.CreateBankpayOrder(ctx, req)
    if err != nil {
        e, ok := errorx.FromError(err)
        if !ok {
            fmt.Println("System error:", err)
            return
        }

        switch e.Code {
        case "2002":
            fmt.Println("Duplicate order ID, check existing order")
        case "2018":
            fmt.Println("Order not found")
        default:
            fmt.Printf("Error %s: %s\n", e.Code, e.Message)
        }
        return
    }

    fmt.Printf("Payment created - OrderID: %s, Ref: %s, Amount: %s\n",
        resp.OrderID, resp.Ref, resp.Pay)
}
```

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

### Query Payment Order Details using Go

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Retrieves detailed information for a specific payment order. This function takes an OrderID and optionally a channel (e.g., "银行卡", "支付宝", "微信") and data type (e.g., "encryption"). It returns order status, transaction details, and tax information, with special handling for non-existent orders.

```go
func queryOrder(client *api.Client) {
    req := &api.GetOrderRequest{
        OrderID:  "ORD1234567890",
        Channel:  "银行卡",  // "银行卡", "支付宝", or "微信"
        DataType: "encryption",  // Enable encryption for sensitive data
    }

    ctx := context.Background()
    resp, err := client.GetOrder(ctx, req)
    if err != nil {
        e, ok := errorx.FromError(err)
        if !ok {
            fmt.Println("Query failed:", err)
            return
        }

        if e.Code == "2018" {
            fmt.Println("Order does not exist, safe to retry with same OrderID")
            return
        }

        fmt.Printf("Error: %s - %s\n", e.Code, e.Message)
        return
    }

    fmt.Printf("Order Status: %s (%s)\n", resp.Status, resp.StatusMessage)
    fmt.Printf("Order Details:\n")
    fmt.Printf("  Amount: %s, User Received: %s\n", resp.Pay, resp.UserRealAmount)
    fmt.Printf("  Broker Reference: %s\n", resp.Ref)
    fmt.Printf("  Bank Bill: %s\n", resp.BrokerBankBill)
    fmt.Printf("  Created: %s, Finished: %s\n", resp.CreatedAt, resp.FinishedTime)

    if resp.TaxDetail != nil {
        fmt.Printf("  Tax Details:\n")
        fmt.Printf("    Personal Tax: %s\n", resp.TaxDetail.PersonalTax)
        fmt.Printf("    VAT: %s\n", resp.TaxDetail.ValueAddedTax)
        fmt.Printf("    Additional Tax: %s\n", resp.TaxDetail.AdditionalTax)
    }
}
```

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

### Verify Bank Card Four-Factor Authentication (Go)

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Performs a four-factor bank card verification including SMS code. It first requests an SMS verification code using card number, ID, real name, and mobile number. Upon receiving the code from the user, it submits the code along with other details for final confirmation. Requires an initialized Yun Zhanghu Open SDK client. Errors are caught and logged, indicating success or failure.

```go
import (
    "context"
    "fmt"

    "github.com/YunzhanghuOpen/sdk-go/api"
    "github.com/YunzhanghuOpen/sdk-go/errorx"
)

func verifyBankCardFourFactor(client *api.Client) {
    // Step 1: Request SMS verification code
    verifyReq := &api.BankCardFourAuthVerifyRequest{
        CardNo:   "6228888888888888888",
        IDCard:   "11010519491231002X",
        RealName: "张三",
        Mobile:   "13800138000",
    }

    verifyResp, err := client.BankCardFourAuthVerify(context.Background(), verifyReq)
    if err != nil {
        e, _ := errorx.FromError(err)
        fmt.Printf("Verification request failed: %s\n", e.Message)
        return
    }

    fmt.Printf("SMS sent, Reference: %s\n", verifyResp.Ref)

    // Step 2: User receives SMS code, submit for confirmation
    var smsCode string
    fmt.Print("Enter SMS code: ")
    fmt.Scanln(&smsCode)

    confirmReq := &api.BankCardFourAuthConfirmRequest{
        CardNo:   "6228888888888888888",
        IDCard:   "11010519491231002X",
        RealName: "张三",
        Mobile:   "13800138000",
        Captcha:  smsCode,
        Ref:      verifyResp.Ref,
    }

    _, err = client.BankCardFourAuthConfirm(context.Background(), confirmReq)
    if err != nil {
        e, _ := errorx.FromError(err)
        fmt.Printf("Verification failed: %s\n", e.Message)
        return
    }

    fmt.Println("Bank card verification successful")
}

```

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

### Bank Card Three-Factor Verification API

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Performs a quick verification using only the bank card number, ID card number, and real name. This is a faster alternative to the four-factor verification when SMS is not required.

```APIDOC
## Bank Card Three-Factor Verification API

### Description
Performs a quick verification using only the bank card number, ID card number, and real name. This is a faster alternative to the four-factor verification when SMS is not required.

### Method
POST (or other appropriate method depending on SDK implementation)

### Endpoint
(Not explicitly defined in the code, typically part of the `api.Client` methods)

### Parameters
#### Request Body
- **CardNo** (string) - Required - The bank card number.
- **IDCard** (string) - Required - The ID card number.
- **RealName** (string) - Required - The real name of the cardholder.

### Request Example
```json
{
  "CardNo": "6228888888888888888",
  "IDCard": "11010519491231002X",
  "RealName": "张三"
}
```

### Response
#### Success Response (200)
Indicates successful verification. Specific response body details depend on the SDK implementation.

#### Response Example
(No specific example provided in the source code, typically an empty success response or a confirmation message.)
```

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

### Check User Signing Status with Go

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Queries the signing status of a user for their contract. This function requires dealer and broker IDs, along with the user's real name, ID card number, and certificate type to identify the user. It returns the signing status, which can be 'Not signed', 'Signed', or 'Signing in progress'. Dependencies include the SDK's `api` client and `errorx`.

```go
func checkSigningStatus(client *api.Client) {
    req := &api.GetH5UserSignStatusRequest{
        DealerID:        "dealer_123456",
        BrokerID:        "broker_123456",
        RealName:        "张三",
        IDCard:          "11010519491231002X",
        CertificateType: 0,
    }

    resp, err := client.GetH5UserSignStatus(context.Background(), req)
    if err != nil {
        e, _ := errorx.FromError(err)
        fmt.Printf("Status query failed: %s\n", e.Message)
        return
    }

    statusMap := map[int32]string{
        0: "Not signed",
        1: "Signed",
        2: "Signing in progress",
    }

    fmt.Printf("User signing status: %s\n", statusMap[resp.Status])
}
```

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

### ID Card Verification API

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Verifies that a provided ID card number matches the real name in the national database. This is a fundamental identity verification step.

```APIDOC
## ID Card Verification API

### Description
Verifies that a provided ID card number matches the real name in the national database. This is a fundamental identity verification step.

### Method
POST (or other appropriate method depending on SDK implementation)

### Endpoint
(Not explicitly defined in the code, typically part of the `api.Client` methods)

### Parameters
#### Request Body
- **IDCard** (string) - Required - The ID card number to verify.
- **RealName** (string) - Required - The real name associated with the ID card.

### Request Example
```json
{
  "IDCard": "11010519491231002X",
  "RealName": "张三"
}
```

### Response
#### Success Response (200)
Indicates successful verification. Specific response body details depend on the SDK implementation.

#### Response Example
(No specific example provided in the source code, typically an empty success response or a confirmation message.)
```

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

### Verify ID Card (Go)

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Verifies an ID card number against the real name in the national database. This function is crucial for identity confirmation, ensuring the provided ID belongs to the individual named. It uses the Yun Zhanghu Open SDK client and includes error handling to report verification failures with specific messages. Successful verification confirms the match in the database.

```go
import (
    "context"
    "fmt"

    "github.com/YunzhanghuOpen/sdk-go/api"
    "github.com/YunzhanghuOpen/sdk-go/errorx"
)

func verifyIDCard(client *api.Client) {
    req := &api.IDCardVerifyRequest{
        IDCard:   "11010519491231002X",
        RealName: "张三",
    }

    _, err := client.IDCardVerify(context.Background(), req)
    if err != nil {
        e, _ := errorx.FromError(err)
        fmt.Printf("ID verification failed: %s\n", e.Message)
        return
    }

    fmt.Println("ID card verification successful")
}

```

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

### Verify Bank Card Three-Factor (Go)

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Performs a quick three-factor bank card verification using only the card number, ID card number, and real name. This method is useful for initial checks without requiring an SMS code. It utilizes the Yun Zhanghu Open SDK client. The function handles potential errors by extracting error codes and messages, providing feedback on verification success or failure.

```go
import (
    "context"
    "fmt"

    "github.com/YunzhanghuOpen/sdk-go/api"
    "github.com/YunzhanghuOpen/sdk-go/errorx"
)

func verifyBankCardThreeFactor(client *api.Client) {
    req := &api.BankCardThreeVerifyRequest{
        CardNo:   "6228888888888888888",
        IDCard:   "11010519491231002X",
        RealName: "张三",
    }

    _, err := client.BankCardThreeVerify(context.Background(), req)
    if err != nil {
        e, ok := errorx.FromError(err)
        if !ok {
            fmt.Println("Verification error:", err)
            return
        }
        fmt.Printf("Verification failed: %s - %s\n", e.Code, e.Message)
        return
    }

    fmt.Println("Three-factor verification passed")
}

```

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

### Bank Card Four-Factor Authentication API

Source: https://context7.com/yunzhanghuopen/sdk-go/llms.txt

Verifies user identity using bank card, ID, name, and mobile number. This process includes an SMS verification step where a code is sent to the user's mobile number and then submitted for confirmation.

```APIDOC
## Bank Card Four-Factor Authentication API

### Description
Verifies user identity using bank card, ID, name, and mobile number. This process includes an SMS verification step where a code is sent to the user's mobile number and then submitted for confirmation.

### Method
POST (or other appropriate method depending on SDK implementation)

### Endpoint
(Not explicitly defined in the code, typically part of the `api.Client` methods)

### Parameters
#### Request Body (for initial verification)
- **CardNo** (string) - Required - The bank card number.
- **IDCard** (string) - Required - The ID card number.
- **RealName** (string) - Required - The real name of the cardholder.
- **Mobile** (string) - Required - The mobile number associated with the card.

#### Request Body (for confirmation)
- **CardNo** (string) - Required - The bank card number.
- **IDCard** (string) - Required - The ID card number.
- **RealName** (string) - Required - The real name of the cardholder.
- **Captcha** (string) - Required - The SMS verification code received.
- **Ref** (string) - Required - The reference ID from the initial verification request.

### Request Example (Initial Verification)
```json
{
  "CardNo": "6228888888888888888",
  "IDCard": "11010519491231002X",
  "RealName": "张三",
  "Mobile": "13800138000"
}
```

### Request Example (Confirmation)
```json
{
  "CardNo": "6228888888888888888",
  "IDCard": "11010519491231002X",
  "RealName": "张三",
  "Captcha": "123456",
  "Ref": "some_reference_id"
}
```

### Response
#### Success Response (200)
Indicates successful verification. Specific response body details depend on the SDK implementation.

#### Response Example (Initial Verification Success)
```json
{
  "Ref": "some_reference_id"
}
```
```
Tokens:
Raw