> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bafanglaicai88.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Describe only the public 123hub merchant API documented on this site. The primary endpoint is POST /public/api/multihub/v1.
> Preserve API method names, field names, header names, and error codes exactly as documented. Do not invent endpoints or parameters.
> Treat every amount as an integer in minor units unless a page explicitly states otherwise.
> Never expose, request, or fabricate a merchant secret key. The SDK pages contain reference implementations, not official SDK packages.

# SDKs Overview

> Code examples and client libraries for integrating with the 123hub API

# SDKs & Code Examples

We provide example client implementations in popular programming languages to help you integrate with the 123hub API. These are reference implementations, not official SDK packages -- you can adapt them to your needs or use them as-is.

<Info>
  Each client is configured with one explicit **Application ID + API version** pair. Version 1 uses
  the legacy exact-body SHA-512 hash at `POST /public/api/multihub/v1`; version 2 uses canonical
  HMAC-SHA512 and mandatory replay protection at `POST /public/api/multihub/v2`. Clients never fall
  back between versions.
</Info>

## Available Examples

<CardGroup cols={2}>
  <Card title="Python" icon="python" href="/sdks/python">
    Client class using `requests` and `hashlib`
  </Card>

  <Card title="Node.js" icon="node-js" href="/sdks/nodejs">
    Client class using `crypto` and native `fetch`
  </Card>

  <Card title="PHP" icon="php" href="/sdks/php">
    Client class using cURL and `hash('sha512', ...)`
  </Card>

  <Card title="Go" icon="golang" href="/sdks/go">
    Client struct using `crypto/sha512` and `net/http`
  </Card>
</CardGroup>

## How It Works

Every API call follows the same pattern regardless of the programming language:

<Steps>
  <Step title="Build the request body">
    Construct a JSON body containing `method` (the operation), an optional `service_id`, and a
    `params` object.
  </Step>

  <Step title="Sign the request">
    For v1, hash the exact body plus the secret. For v2, generate timestamp and nonce, then sign the
    documented canonical request payload with HMAC-SHA512.
  </Step>

  <Step title="Send the POST request">
    POST to the endpoint selected by the configured API version. Both versions send the exact
    configured `X-Data-Application-Id`; v2 never retries as v1.
  </Step>

  <Step title="Handle the response">
    Successful responses return HTTP 200, errors return HTTP 400 (or 404 for unknown methods). Check
    the `success` boolean field to determine if the operation succeeded, and handle `error.code` /
    `error.message` when it did not.
  </Step>
</Steps>

## Authentication

All requests require `X-Data-Application-Id`. The remaining headers depend on the configured version:

| Header                  | v1       | v2       | Description                                    |
| ----------------------- | -------- | -------- | ---------------------------------------------- |
| `X-Data-Application-Id` | required | required | Exact application ID selected with the version |
| `X-Data-Hash`           | required | omitted  | `sha512(exactBody + secretKey)`                |
| `X-Data-Timestamp`      | optional | required | Canonical Unix seconds                         |
| `X-Data-Nonce`          | optional | required | Unique 16–128 character nonce                  |
| `X-Data-Signature`      | omitted  | required | Canonical HMAC-SHA512 signature                |

<Warning>
  Never expose your secret key in client-side code, logs, or version control. Always store it in
  environment variables or a secrets manager.
</Warning>

### Environment Variables

Store your credentials securely:

<CodeGroup>
  ```bash Linux/macOS theme={null}
  export PAYMENT_API_APP_ID="1"
  export PAYMENT_API_VERSION="2"
  export PAYMENT_API_SECRET_KEY="your_secret_key"
  ```

  ```powershell Windows PowerShell theme={null}
  $env:PAYMENT_API_APP_ID = "1"
  $env:PAYMENT_API_VERSION = "2"
  $env:PAYMENT_API_SECRET_KEY = "your_secret_key"
  ```

  ```env .env file theme={null}
  PAYMENT_API_APP_ID=1
  PAYMENT_API_VERSION=2
  PAYMENT_API_SECRET_KEY=your_secret_key
  ```
</CodeGroup>

## API Methods

Method-based routing replaces traditional REST endpoints. You specify the operation in the `method` field of the request body:

| Method           | Description                         |
| ---------------- | ----------------------------------- |
| `gateway.ping`   | Health check / connectivity test    |
| `payment.in`     | Create a deposit (pay-in)           |
| `payment.out`    | Create a withdrawal (payout)        |
| `payment.status` | Check payment status by identifiers |
| `balance.get`    | Retrieve account balances           |

## Request Format

Every request follows this structure:

```json theme={null}
{
  "method": "payment.in",
  "service_id": 14701,
  "params": {
    "payment": {
      "identifiers": { "c_id": "12345" },
      "amount": { "value": 10000, "currency": "INR" },
      "description": "Order #12345"
    }
  }
}
```

## Response Envelope

Every response uses a consistent envelope:

```json Success (HTTP 200) theme={null}
{
  "success": true,
  "result": { ... },
  "request_id": "abc-123",
  "processing_time": 42
}
```

When an error occurs (HTTP 400):

```json Error (HTTP 400) theme={null}
{
  "success": false,
  "error": {
    "code": 1005,
    "message": "Invalid request format",
    "details": {
      "description": "missing required properties including: 'service_id'. Path: $"
    },
    "context": null
  },
  "request_id": "abc-456",
  "processing_time": 3
}
```

## Common Pattern Across All SDKs

Regardless of language, every SDK example follows this pseudocode:

Payment status handling should treat `success`, `error`, `canceled`, `declined`, `refunded`, and `partially_refunded` as final statuses for polling loops. Handle `refunded` and `partially_refunded` as refund outcomes, not as new successful order payments.

```
function send(body):
    body_string = compact_json_serialize(body)
    hash = sha512_hex(body_string + secret_key)
    response = http_post(BASE_URL, body, headers={
        "X-Data-Application-Id": app_id,
        "X-Data-Hash": hash,
        "X-Data-Timestamp": str(int(time.time())),
        "X-Data-Nonce": str(uuid.uuid4()),
    })
    return parse_json(response.body)
```

## Community SDKs

If you have built an SDK or wrapper for the 123hub API, we would love to feature it here. Contact us at [support@123hub.pro](mailto:support@123hub.pro).

## Need Help?

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Complete API documentation
  </Card>

  <Card title="Support" icon="envelope" href="mailto:support@123hub.pro">
    Contact developer support
  </Card>
</CardGroup>