Skip to main content

Clients

Create and manage clients, dedicated CVUs, transaction history, and invoices

Clients are the end recipients you register under your PaymentHub. Each client receives a dedicated CVU — an Argentine bank account number that maps exclusively to that client. When a transfer arrives at that CVU, Basilic automatically identifies the client and can send a webhook to the callback URL you configured.

What you can do​

  • Create clients and provision a dedicated CVU in a single API call.
  • Update client data, including the callback URL for incoming transfer notifications.
  • View transaction history — every credit and debit recorded for the client — with pagination and filters.
  • Check the client's balance — get the client credit balance and the client debt, plus informational totals (cash-in, cash-out, invoiced), independently of transaction pagination.
  • Create and update invoices assigned to each client to track what they owe.

Dedicated CVU provisioning​

When you create a client, Basilic automatically provisions a CVU/alias pair specific to that client. Provisioning happens inline — the response includes the CVU and alias once they are available.

Your call → POST /api/v1/clients
                        ↓
              Basilic creates the row in billing_clients
                        ↓
              Basilic provisions the CVU/alias
                        ↓
              Response: client + cvu + alias

The cvuStatus field reflects the current provisioning state of the CVU:

StatusMeaning
not_provisionedCVU has not been requested yet
provisioningCVU request is in progress
activeCVU is ready to receive transfers
provisioning_failedCVU request failed; contact support
disabledCVU is disabled

Cash-in callback​

Set a cashinCallbackUrl on the client to receive a POST notification every time a transfer arrives at that client's CVU.

Delivery model:

  • Up to 3 delivery attempts with retries on failure.
  • The event is recorded in Basilic's internal log with status pending → retrying → delivered / failed.

Webhook payload:

{
  "eventId": "uuid",
  "clientId": "uuid",
  "eventType": "client.cashin",
  "taxId": "30-12345678-9",
  "amount": 4970.00,
  "total": 5000.00,
  "totalWithoutTaxes": 4970.00,
  "taxes": 30.00,
  "currency": "ARS",
  "cvu": "0000726100000000014782",
  "alias": "ACMESA.HUB1",
  "operationId": "internal-op-id",
  "createdAt": "2026-05-18T12:00:00Z"
}

Tax fields:

FieldDescription
amountNet amount credited after taxes (what the client effectively received)
totalGross amount before taxes
totalWithoutTaxesSame as amount — net amount after taxes, kept for clarity
taxesTax amount retained by the provider. total - taxes = amount

In most transfers there are no taxes and total === amount while taxes === 0. For Argentine transfers that include tax operations (e.g. withholding), these fields carry the breakdown.

Headers sent by Basilic:

HeaderValue
Content-Typeapplication/json
User-AgentBasilic-Client-Callback/1.0
X-Basilic-Event-IdEvent UUID
X-Basilic-Event-Typeclient.cashin

Your endpoint must return HTTP 2xx to confirm delivery.

Financial summary​

GET /api/v1/clients/{id}/balance returns the client credit balance and the client debt for a client, independently of transaction pagination:

FieldFormula
creditBalanceGross transfers of the client, minus the amounts already applied to invoices, minus the debits
debtSum of the pending amounts of the open invoices of the client
balancecreditBalance - debt
totalCashInInformational: sum of all cash_in entries (positive amounts)
totalCashOutInformational: absolute sum of all debit entries (negative amounts)
totalInvoicedInformational: sum of total_amount across all client invoices

creditBalance and debt are never netted with each other before this endpoint computes them: a client can carry both a credit balance and a debt at once. An optional hubId query parameter narrows creditBalance to one PaymentHub; debt always covers every open invoice of the client, company-wide.

Requirements​

  • The PaymentHub must have dedicated client CVUs enabled (dedicated_client_cvus_enabled = true).
  • Each client can have at most one CVU per PaymentHub (1:1 constraint enforced at the API level).
  • The client's taxId (CUIT) must be unique within your account.