> ## 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.

# API Methods

> Request and response contracts for payment, balance, support, refund, chargeback, attachment, notification, and ping methods

# API Methods

All API methods are sent to one endpoint:

```http theme={null}
POST /public/api/multihub/v1
```

## Request Envelope

```json theme={null}
{
  "method": "payment.in",
  "service_id": 14701,
  "params": {
    "payment": {}
  }
}
```

| Field            | Type    |   Required  | Description                                                     |
| ---------------- | ------- | :---------: | --------------------------------------------------------------- |
| `method`         | string  |     Yes     | One of the supported API methods                                |
| `service_id`     | integer | Conditional | Required for `payment.in` and `payment.out`; optional elsewhere |
| `params.payment` | object  | Conditional | Required for payment methods                                    |

The API also accepts `method` as `{ "const": "balance.get" }` and numeric-string `service_id` values. Payment identifiers must be strings; numeric `c_id` and `h_id` values are rejected to avoid precision loss.

## Application Rate Limits

Authenticated merchant applications have separate per-method protective rate-limit buckets for `payment.in`, `payment.out`, `payment.status`, and `balance.get`. Buckets are keyed by merchant and application, not by client IP address. The payment creation buckets are configured as high safety ceilings for runaway or abusive traffic, not as normal operating limits. When a bucket is exhausted, the endpoint returns HTTP `429` with the standard API error envelope and `Retry-After-*` rate-limit headers.

## Support, refund, and chargeback methods

The following strict method-discriminated requests use the same endpoint, signature, response envelope, and `request_id` as payment methods. They accept only canonical dot-notation names and never accept `service_id`, `merchant_id`, actor, source, or application ID in the body.

| Resource        | Methods                                                                                  | Required scope                                         |
| --------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| Tickets         | `ticket.create`, `ticket.get`, `ticket.list`, `ticket.summary`                           | `tickets.create` or `tickets.read` by action           |
| Ticket changes  | `ticket.description.update`, `ticket.reopen`                                             | `tickets.update`                                       |
| Ticket comments | `ticket.comment.create`, `ticket.comments.list`, `ticket.comment.update`                 | `tickets.comment` for writes; `tickets.read` for reads |
| Attachments     | `attachment.prepare`, `attachment.finalize`, `attachment.status`, `attachment.get`       | Purpose/parent-dependent ticket or chargeback scope    |
| Refunds         | `refund.request`, `refund.get`, `refund.list`, `refund.summary`                          | `refunds.create` or `refunds.read` by action           |
| Refund comments | `refund.comment.create`, `refund.comments.list`                                          | `refunds.comment` for writes; `refunds.read` for reads |
| Chargebacks     | `chargeback.get`, `chargeback.list`, `chargeback.summary`, `chargeback.attachments.list` | `chargebacks.read`                                     |

Start with [Support API fundamentals](/guides/support-api), then use the resource guides for [tickets](/guides/tickets), [refunds](/guides/refunds), [chargebacks](/guides/chargebacks), [attachments](/guides/attachments), and [support webhooks](/guides/support-webhooks).

## `payment.in`

Creates a deposit.

### Required Fields

| Field                             | Type    | Description                                               |
| --------------------------------- | ------- | --------------------------------------------------------- |
| `service_id`                      | integer | Route assigned during onboarding                          |
| `params.payment.amount.value`     | integer | Amount in minor units; fractional values are rejected     |
| `params.payment.amount.currency`  | string  | ISO 4217 currency code; must match the `service_id` route |
| `params.payment.identifiers.c_id` | string  | Merchant reference, unique per payment                    |
| `params.payment.payer`            | object  | Customer who sends funds                                  |

### Optional Fields

| Field                       | Type   | Description                                                  |
| --------------------------- | ------ | ------------------------------------------------------------ |
| `description`               | string | Max 1024 characters                                          |
| `payer.email`               | string | Customer email                                               |
| `payer.phone`               | string | Customer phone                                               |
| `payer.person.first_name`   | string | Customer first name                                          |
| `payer.person.last_name`    | string | Customer last name                                           |
| `payer.customer_account.id` | string | Merchant-side customer identifier                            |
| `client.language`           | string | Language hint, max 10 characters                             |
| `client.country`            | string | Country hint, max 3 characters                               |
| `redirect.on_success`       | string | HTTP(S) URL returned in the response redirect object         |
| `redirect.on_fail`          | string | HTTP(S) URL returned in the response redirect object         |
| `webhook_url`               | string | Absolute public HTTP(S) URL for per-payment webhook delivery |

### Example

```json theme={null}
{
  "method": "payment.in",
  "service_id": 14701,
  "params": {
    "payment": {
      "description": "Order #12345",
      "identifiers": { "c_id": "order-12345" },
      "amount": { "value": 10000, "currency": "INR" },
      "payer": {
        "email": "customer@example.com",
        "phone": "9876543210",
        "person": { "first_name": "John", "last_name": "Doe" },
        "customer_account": { "id": "cust-123" }
      },
      "client": { "language": "EN", "country": "IN" },
      "webhook_url": "https://merchant.example/webhooks/123hub"
    }
  }
}
```

## `payment.out`

Creates a withdrawal/payout.

### Required Fields

| Field                                     | Type    | Description                                                       |
| ----------------------------------------- | ------- | ----------------------------------------------------------------- |
| `service_id`                              | integer | Route assigned during onboarding                                  |
| `params.payment.amount.value`             | integer | Amount in minor units                                             |
| `params.payment.amount.currency`          | string  | ISO 4217 currency code; must match the `service_id` route         |
| `params.payment.identifiers.c_id`         | string  | Merchant payout reference and idempotency key, unique per payment |
| `params.payment.receiver.bank.account.id` | string  | Recipient account identifier                                      |

### Region-Specific Bank Fields

| Region    | Account Field                                  | Additional Field              |
| --------- | ---------------------------------------------- | ----------------------------- |
| India     | `receiver.bank.account.id`                     | `receiver.bank.ifsc`          |
| Mexico    | `receiver.bank.account.id` with 18-digit CLABE | None                          |
| Argentina | `receiver.bank.account.id` with CBU/CVU        | Optional `receiver.bank.code` |
| Turkey    | `receiver.bank.account.id` with IBAN           | None                          |

`receiver.bank.clabe` is not part of the current request DTO. For Mexico, send the CLABE in `receiver.bank.account.id`.

### Tracking

The create response returns your `c_id`, a 123hub `h_id`, and, when available, an opaque provider `p_id`. Use `c_id` or `h_id` with `payment.status`; payout webhooks also include these identifiers under `data.result.payment.identifiers`.

Provider-specific callback fields such as `order_id`, `transaction_id`, `session_token`, or `user_id` are not part of the public API contract.

### Example

```json theme={null}
{
  "method": "payment.out",
  "service_id": 14702,
  "params": {
    "payment": {
      "description": "Payout #67890",
      "identifiers": { "c_id": "payout-67890" },
      "amount": { "value": 50000, "currency": "INR" },
      "receiver": {
        "bank": {
          "account": { "id": "1234567890" },
          "ifsc": "SBIN0001234"
        },
        "email": "recipient@example.com",
        "phone": "9876543210",
        "person": { "first_name": "Jane", "last_name": "Doe" }
      }
    }
  }
}
```

## `payment.status`

Returns the current payment state.

```json theme={null}
{
  "method": "payment.status",
  "params": {
    "payment": {
      "identifiers": { "c_id": "order-12345" }
    }
  }
}
```

At least one lookup identifier is required:

| Identifier | Supported | Notes                      |
| ---------- | :-------: | -------------------------- |
| `c_id`     |    Yes    | Merchant reference         |
| `h_id`     |    Yes    | Hub payment ID             |
| `p_id`     |     No    | Returned in responses only |

## `payment.notification`

Queues a webhook re-delivery for a payment and returns the same payment result shape as `payment.status`.

The delivered merchant webhook uses the same envelope as automatic lifecycle webhooks: `data.success`, `data.result.payment`, `data.next: null`, `data.request_id`, and `data.processing_time`. The public webhook `id` stays payment/event-stable; durable delivery idempotency uses `operation_id` when supplied.

```json theme={null}
{
  "method": "payment.notification",
  "operation_id": "notification-retry-1001",
  "params": {
    "payment": {
      "identifiers": { "h_id": "pay_1774892151645_abcd" }
    }
  }
}
```

`operation_id` is optional but recommended. Reuse it only for an exact retry; a
changed intent needs a new value. Without it, the compatibility identity is
derived from the payment, canonical request and current minute. The method is
limited to 10 requests per minute. `service_id` is optional; stored payment
metadata is preferred.

## `balance.get`

Returns balances for the authenticated merchant.

`value_blocking` and `enabled` are currently constant runtime compatibility fields: `value_blocking` is always `0`, and `enabled` is always `true` at both the balance and currency levels.

```json theme={null}
{
  "method": "balance.get",
  "params": {}
}
```

Response:

```json theme={null}
{
  "success": true,
  "result": {
    "balance": {
      "id": 0,
      "amounts": [
        {
          "value": 150000,
          "value_freezing": 25000,
          "value_blocking": 0,
          "currency": "INR",
          "enabled": true
        }
      ],
      "enabled": true
    }
  },
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "processing_time": 15
}
```

All balance values are integers in minor units.

## `gateway.ping`

Validates authentication and connectivity.

```json theme={null}
{
  "method": "gateway.ping",
  "params": {}
}
```

Response:

```json theme={null}
{
  "success": true,
  "result": { "message": "pong" },
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "processing_time": 5
}
```

## Payment Response Object

| Field                                | Type                | Description                                                              |
| ------------------------------------ | ------------------- | ------------------------------------------------------------------------ |
| `payment.payer`                      | object              | Present for deposits when customer data is known                         |
| `payment.receiver`                   | object              | Bank/customer destination details when known                             |
| `payment.receiver.bank_account.id`   | string              | Deposit account number, IBAN, CBU or CLABE when supplied by the provider |
| `payment.receiver.bank_account.name` | string              | Deposit account holder name                                              |
| `payment.receiver.bank.name`         | string              | Deposit bank or payment-network name                                     |
| `payment.receiver.bank.code`         | string              | Deposit bank or payment-network code                                     |
| `payment.receiver.phone`             | string              | P2P receiver phone when required to complete the deposit                 |
| `payment.receiver.document.type`     | string              | Receiver document type, for example `cedula`                             |
| `payment.receiver.document.number`   | string              | Receiver document number                                                 |
| `payment.receiver.qr_payload`        | string              | Provider-issued QR payload, capped at 4096 characters                    |
| `payment.amount.value`               | integer             | Amount in minor units                                                    |
| `payment.amount.currency`            | string              | ISO 4217 code                                                            |
| `payment.description`                | string              | Description when available                                               |
| `payment.identifiers.c_id`           | string              | Merchant reference                                                       |
| `payment.identifiers.h_id`           | string              | Hub payment ID                                                           |
| `payment.identifiers.p_id`           | string              | Provider reference when available                                        |
| `payment.identifiers.utr`            | string              | Bank/provider tracking reference when available                          |
| `payment.redirect.to`                | string or string\[] | Payment URL or payment-app deep links                                    |
| `payment.status`                     | object              | Current status and optional history                                      |
| `payment.timestamps`                 | object              | `created`, `updated`, and terminal `finished` timestamps when available  |
| `payment.destination`                | string              | `in` or `out`                                                            |
| `payment.operations`                 | array               | Operation records derived from the payment                               |
| `payment.service_id`                 | integer             | Route ID when known                                                      |
| `operation`                          | object              | Shortcut to the primary operation                                        |

## Status Values

| Status               | Final | Success | Internal Source      |
| -------------------- | :---: | :-----: | -------------------- |
| `created`            |   No  |  `null` | `created`, `pending` |
| `processing`         |   No  |  `null` | `processing`         |
| `success`            |  Yes  |  `true` | `completed`          |
| `error`              |  Yes  | `false` | `failed`             |
| `canceled`           |  Yes  | `false` | `cancelled`          |
| `declined`           |  Yes  | `false` | `expired`            |
| `refunded`           |  Yes  |  `true` | `refunded`           |
| `partially_refunded` |  Yes  |  `true` | `partial_refund`     |