HProxy Reseller API: act as your customers API

openapi: 3.2.0
info:
  title: 'HProxy Reseller API: act as your customers API'
  version: 1.0.0
  description: 'Buy and manage proxies from a prepaid wallet, run the Scraper API, or use the free no-key APIs: a live proxy list, a proxy checker and an IP lookup. JSON in, JSON out. Money is always integer cents (120 = $1.20), never floats.'
  contact:
    url: https://hproxy.com/contact
  license:
    name: Proprietary
servers:
- url: https://hproxy.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: 'Reseller API: act as your customers'
paths:
  /api/v1/deposits:
    post:
      operationId: partner-deposit-create
      summary: Let the named customer pay you
      description: 'With `X-Reseller-Customer-Id`, this creates an invoice on **your own** payment gateway (connected under Payments in your business dashboard) and returns its pay page: crypto through Heleket or NOWPayments (`method: "crypto"`), cards through Stripe Checkout or Payoneer Checkout (`method: "card"`); one live gateway per rail. The page shows your merchant name, the money goes to your account, and when it arrives we credit the customer''s store credit automatically: the exact amount, the whole amount when they overpay, and what actually arrived when a crypto invoice closes short. Amounts are whole cents; sub-floor amounts are raised to the method floor ($3 crypto, $10 card) and one invoice is at most $5,000. Send an `Idempotency-Key` and a retried request returns the same open invoice. No gateway for that method ⇒ `403 deposits_not_available`.


        **An order can pay for itself.** `POST /orders` for a named customer with `method: "crypto"` or `"card"` and short credit still answers `402 customer_credit_insufficient`, but with `payUrl`, `depositId`, `chargeCents` (the shortfall raised to the rail''s minimum) and `shortfallCents` added. Send the customer to `payUrl`: when the money lands, the credit is granted and the order is placed automatically under the same `Idempotency-Key`, a Telegram customer is told in the store''s bot, and `GET /deposits/{id}` shows `for_order: true`. Without a gateway for that rail the 402 carries no pay page and the customer needs credit first.'
      tags:
      - 'Reseller API: act as your customers'
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                deposit_id: rpay_cmt9x2k1a0001
                pay_url: https://pay.heleket.com/pay/4f1c…
                amount_cents: 2500
                status: awaiting_payment
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount_cents:
                  type: integer
                  description: Whole cents at your prices.
                method:
                  type: string
                  description: '"crypto" or "card". Default "card".'
                return_url:
                  type: string
                  description: 'Where the customer lands after paying (https). Default: your website, else your Telegram storefront.'
              required:
              - amount_cents
  /api/v1/customer:
    get:
      operationId: partner-customer-get
      summary: Read the acting customer
      description: 'The named customer''s profile: your id for them, your display name (`label`), the email you attached, the credit they can still spend (in cents, at your prices), and when they were created and last seen. Requires the `X-Reseller-Customer-Id` header.'
      tags:
      - 'Reseller API: act as your customers'
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                customer:
                  externalId: user-4021
                  label: Alex M.
                  contactEmail: alex@example.com
                  creditCents: 2500
                  createdAt: '2026-08-23T15:02:11+00:00'
                  lastSeenAt: '2026-08-23T16:40:03+00:00'
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
  /api/v1/customer/contact:
    put:
      operationId: partner-customer-contact
      summary: Attach their identity
      description: 'Set the customer''s email and your display name for them, ideally right after your own signup flow, so your customer book, your business dashboard and our support all see a person instead of an opaque id. Each field: **omitted = unchanged, empty string = cleared, value = set**. We never send mail to this address; it is identity, not a channel.'
      tags:
      - 'Reseller API: act as your customers'
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                customer:
                  externalId: user-4021
                  label: Alex M.
                  contactEmail: alex@example.com
                  creditCents: 2500
                  createdAt: '2026-08-23T15:02:11+00:00'
                  lastSeenAt: '2026-08-23T16:40:03+00:00'
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: The customer's email address. Stored lowercased. Empty string clears it.
                label:
                  type: string
                  description: Your display name for them, 1 to 120 characters. Empty string clears it.
  /api/v1/customer/credit:
    put:
      operationId: partner-customer-credit
      summary: Credit or revoke their balance
      description: 'Move store credit on the named customer, from your own backend: **grant** when they paid you, **revoke** for a refund on your side or a correction. Amounts are whole cents at your retail prices; one movement is at most $5,000. Send your own `request_id` for every movement (your payment id, your refund id): a repeat with the same id answers `409 already_applied` instead of moving the credit twice, so a retry is always safe. A revoke larger than what is left is refused (`revoke_exceeds_credit`) and names the remaining figure. Requires the `X-Reseller-Customer-Id` header.'
      tags:
      - 'Reseller API: act as your customers'
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                customer:
                  externalId: user-4021
                  label: Alex M.
                  contactEmail: alex@example.com
                  creditCents: 5000
                  createdAt: '2026-08-23T15:02:11+00:00'
                  lastSeenAt: '2026-08-23T16:40:03+00:00'
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount_cents:
                  type: integer
                  description: Positive whole cents at your prices.
                direction:
                  type: string
                  description: '"grant" or "revoke".'
                request_id:
                  type: string
                  description: Your id for this movement, one per intent, 1 to 100 characters.
                note:
                  type: string
                  description: Shown on your statement, up to 200 characters.
              required:
              - amount_cents
              - direction
              - request_id
  /api/v1/deposits/{id}:
    get:
      operationId: partner-deposit-get
      summary: Read one of your customers' payments
      description: 'The state of a deposit your storefront created, for your own backend to show "payment received". `status` is `awaiting_payment`, `paid`, `paid_over`, `underpaid`, `expired`, `cancelled`, `failed`, `locked` (held by the gateway; nothing credited) or `needs_review`. `credited_cents` is what landed on the customer''s store credit. Account-level: no customer header needed, and only your own deposits resolve.'
      tags:
      - 'Reseller API: act as your customers'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                deposit_id: rpay_cmt9x2k1a0001
                status: paid
                provider: heleket
                method: crypto
                amount_cents: 2500
                received_cents: 2500
                credited_cents: 2500
                pay_url: null
                created_at: '2026-09-04T09:12:41+00:00'
                settled_at: '2026-09-04T09:20:03+00:00'
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
  /api/v1/usage:
    get:
      operationId: partner-usage-customer
      summary: A customer's bandwidth history
      description: 'With `X-Reseller-Customer-Id`, the named customer''s traffic from the meter: one row per day and one per plan over the last `days` days (1 to 365, default 30). `gbUsed` is what was consumed that day; `null` means no reading exists for that day (a plan''s first day, or a gap) and is never zero, and `unknownDays` counts those. Each day also carries `gbTotal` (the caps of the plans measured that day) and `gbLeft` (what they still held at the day''s last reading), so how much a customer had and how much is left is a history, not a snapshot. Each plan line carries its cap, the meter at the last reading (`gbUsedEnd`) and `gbLeft`. Narrow to one plan with `plan_id`. What they bought is on `GET /orders`; this is what they used. Readings land every 30 minutes, one pass after the plan''s own figures are synced, so a plan bought in the last hour may have no row yet; for a live figure read the plan itself (`GET /plans/{id}`).'
      tags:
      - 'Reseller API: act as your customers'
      parameters:
      - name: days
        in: query
        required: false
        description: Window in days, 1 to 365. Default 30.
        schema:
          type: integer
      - name: plan_id
        in: query
        required: false
        description: One plan only.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                days: 7
                gbUsed: 3.42
                unknownDays: 1
                daily:
                - day: '2026-09-01'
                  gbUsed: null
                  gbTotal: 10
                  gbLeft: 9.1
                  plans: 1
                  unknown: 1
                  meterResets: 0
                - day: '2026-09-02'
                  gbUsed: 1.2
                  gbTotal: 10
                  gbLeft: 7.9
                  plans: 1
                  unknown: 0
                  meterResets: 0
                plans:
                - planId: plan_…
                  product: residential-premium
                  productName: Residential Premium
                  label: null
                  gbUsed: 3.42
                  daysKnown: 6
                  unknownDays: 1
                  gbTotal: 10
                  gbUsedEnd: 4.3
                  gbLeft: 5.7
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
  /api/v1/store/usage:
    get:
      operationId: partner-usage-store
      summary: Your whole store's bandwidth
      description: 'Account-level (no customer header): what all your customers used per day beside what you sold per day, per product, and the ten customers that used the most, over the last `days` days. `gb_used` is the meter, `gb_sold` is GB on paid orders by the day they were paid, `gb_total` and `gb_left` are what the measured plans had and still held at the day''s last reading; the four are never mixed into one number. `unknown_days` counts plan-days without a reading. Readings land every 30 minutes, one pass after each plan''s own figures are synced. Snake_case like the other account-level doors.'
      tags:
      - 'Reseller API: act as your customers'
      parameters:
      - name: days
        in: query
        required: false
        description: Window in days, 1 to 365. Default 30.
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                days: 30
                totals:
                  gb_used: 41.2
                  gb_sold: 120
                  gb_total: 300
                  gb_left: 212.6
                  unknown_days: 3
                  plans: 17
                daily:
                - day: '2026-09-04'
                  gb_used: 1.4
                  gb_total: 300
                  gb_left: 212.6
                  gb_sold: 10
                  plans: 17
                  unknown: 0
                  meter_resets: 0
                products:
                - product: residential-premium
                  product_name: Residential Premium
                  gb_used: 30.1
                  plans: 9
                  unknown_days: 1
                  gb_sold: 80
                  orders: 12
                customers:
                - external_id: user-4021
                  label: Ali
                  gb_used: 14.2
                  plans: 2
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
  /api/v1/customers:
    get:
      operationId: partner-customers-list
      summary: List your customers
      description: 'Every customer on your account, newest first, with identity and credit, the read your backend reconciles against. This is an **account-level** call: send it **without** the `X-Reseller-Customer-Id` header (naming a customer here is refused with a `400` telling you to drop the header).'
      tags:
      - 'Reseller API: act as your customers'
      parameters:
      - name: limit
        in: query
        required: false
        description: Page size, 1 to 200. Default 50.
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        description: Rows to skip. Default 0.
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                customers:
                - externalId: user-4021
                  label: Alex M.
                  contactEmail: alex@example.com
                  creditCents: 2500
                  createdAt: '2026-08-23T15:02:11+00:00'
                  lastSeenAt: '2026-08-23T16:40:03+00:00'
                - externalId: user-3990
                  label: null
                  contactEmail: null
                  creditCents: 0
                  createdAt: '2026-08-22T10:11:40+00:00'
                  lastSeenAt: null
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your API key. Free keyless endpoints ignore it.
x-endpoint-count: 163
x-generated-from: https://hproxy.com/docs
x-llms: https://hproxy.com/llms-full.txt