Endpoints, OpenAPI, and errors. Pick an SDK or integrate with cURL; all examples use the same HMAC authentication.
Reference
Routes aligned with the Postman collection «HANIX - BACK» → Business folder. Base: https://api.hanix.io/api/v1.
| Method | Path | ||
|---|---|---|---|
| Payment orders | |||
| POST | /business/payment-orders | createPaymentOrder | Creates a payment order. With optional items[], amounts are calculated from the catalog (no sales_order). |
| GET | /business/payment-orders | listPaymentOrders | Lists the merchant's payment orders. |
| GET | /business/payment-orders/:payment_order_id | getPaymentOrder | Payment order detail by UUID. |
| POST | /business/payment-orders/:payment_order_id/attempts | createPaymentAttempt | Creates a payment attempt and returns PSP checkout data. |
| GET | /business/payment-orders/:payment_order_id/attempts | listPaymentOrderAttempts | Payment attempts for an order. |
| POST | /business/payment-orders/:payment_order_id/cancel | cancelBusinessPaymentOrder | Cancels a merchant payment order. |
| GET | /business/payment-orders/:payment_order_id/checkout | getBusinessPaymentOrderCheckout | Enriched checkout UI view: PSP methods, attempts, Wompi legal context. |
| GET | /business/payment-orders/by-public-token/:public_token/checkout | getBusinessPaymentOrderCheckoutByPublicToken | Enriched checkout view by public_token (authenticated merchant orders only). |
| PSP — Config (backend only) | |||
| GET | /business/merchant-payment-settings/psp-methods | listMerchantPspMethods | Merchant PSP configuration (credentials, webhooks). Backend only — never on the buyer frontend. |
| Catalog — Categories | |||
| GET | /business/merchant-catalog/categories | listCatalogCategories | Lists catalog categories. |
| PUT | /business/merchant-catalog/categories/bulk | upsertCatalogCategories | Creates or updates categories in bulk. |
| DELETE | /business/merchant-catalog/categories/bulk | deleteCatalogCategories | Deletes categories by id. |
| POST | /business/merchant-catalog/categories/images/direct-uploads | requestCatalogCategoryImageDirectUploads | Requests direct upload URLs to Cloudflare. |
| PUT | /business/merchant-catalog/categories/images/bulk | registerCatalogCategoryImages | Registers category images already uploaded. |
| DELETE | /business/merchant-catalog/categories/images/bulk | deleteCatalogCategoryImages | Removes category images. |
| Catalog — Products | |||
| GET | /business/merchant-catalog/currencies | listCatalogCurrencies | Currencies available for merchant products. |
| POST | /business/merchant-catalog/products | createCatalogProduct | Creates a product with at least one required variant. |
| GET | /business/merchant-catalog/products | listCatalogProducts | Lists products with filters and pagination. |
| GET | /business/merchant-catalog/products/:product_id | getCatalogProduct | Product detail with variants and images. |
| PATCH | /business/merchant-catalog/products/:product_id | updateCatalogProduct | Updates name, slug, category, status, etc. |
| DELETE | /business/merchant-catalog/products/bulk | deleteCatalogProducts | Deletes products by id. |
| PATCH | /business/merchant-catalog/products/:product_id/variants/:variant_id | updateCatalogProductVariant | Updates SKU, price, stock, options, etc. |
| PATCH | /business/merchant-catalog/products/:product_id/variants/:variant_id/warehouse-stock | setCatalogVariantWarehouseStock | Warehouse physical stock (panel / integrations only). |
| PUT | /business/merchant-catalog/variants/bulk | upsertCatalogVariants | Creates or updates variants in bulk. |
| DELETE | /business/merchant-catalog/variants/bulk | deleteCatalogVariants | Deletes variants by id. |
| POST | /business/merchant-catalog/images/direct-uploads | requestCatalogImageDirectUploads | Requests direct upload URLs for product images. |
| PUT | /business/merchant-catalog/images/bulk | registerCatalogImages | Registers product images already uploaded. |
| PATCH | /business/merchant-catalog/images/bulk | updateCatalogImages | Updates product images (isPrimary = card image, variantId, altText, sortOrder). |
| DELETE | /business/merchant-catalog/images/bulk | deleteCatalogImages | Deletes product images by id. |
| POST | /business/merchant-catalog/inventory/adjustments/bulk | adjustCatalogInventory | Adjusts variant inventory in bulk. |
| Checkout — Cart | |||
| POST | /business/cart/quote | quoteBusinessCart | Quotes without persisting; returns server-calculated discount_in_cents, applied_coupon, tax_in_cents, and taxes[]. |
| Checkout — Orders | |||
| POST | /business/sales-orders | createBusinessSalesOrder | Creates the order with server coupon and taxes; returns discount_in_cents and tax_in_cents (applied_coupon and taxes[] come from quote). |
| GET | /business/sales-orders | listBusinessSalesOrders | Lists orders with discount_in_cents and tax_in_cents; applied_coupon and taxes[] belong to the prior quote. |
| GET | /business/sales-orders/:sales_order_id | getBusinessSalesOrder | Detail with discount_in_cents and tax_in_cents; use quote for applied_coupon and taxes[] detail. |
| POST | /business/sales-orders/:sales_order_id/pay | payBusinessSalesOrder | Creates or reuses a payment order and returns payment_url. |
| GET | /business/sales-orders/:sales_order_id/tracking | getBusinessSalesOrderTracking | Shipping tracking for a sales order. |
| GET | /business/sales-orders/:sales_order_id/invoice | getBusinessSalesOrderInvoice | Invoice or receipt for a sales order. |
| POST | /business/sales-orders/:sales_order_id/cancel | cancelBusinessSalesOrder | Cancels a sales order when its status allows. |
| PATCH | /business/sales-orders/:sales_order_id/fulfillment | changeBusinessSalesOrderFulfillment | Updates fulfillment status, tracking, and shipping photo for the order. |
| POST | /business/sales-orders/:sales_order_id/refund | refundBusinessSalesOrder | Refunds a sales order and restocks inventory when applicable. |
| Checkout — Payment | |||
| GET | /business/checkout/psp-methods | listBusinessCheckoutPspMethods | PSP methods with required_fields for the payment form (no credentials). Use on the buyer checkout — not merchant-payment-settings/psp-methods. |
| Reference | |||
| GET | /business/countries | listBusinessCountries | Active system countries (shipping forms). |
| GET | /business/currencies | listBusinessCurrencies | System currencies. |
| Store | |||
| GET | /business/store/settings | getBusinessStoreSettings | Store settings: checkout mode, WhatsApp, logos, shipping. |
| Webhooks | |||
| GET | /business/webhooks/settings | getBusinessWebhookSettings | Configured webhook URL for the merchant. |
| PUT | /business/webhooks/settings | updateBusinessWebhookSettings | Updates the webhook URL (HTTPS, anti-SSRF). |
| Shipping | |||
| GET | /business/shipping/settings | getBusinessShippingSettings | Default weight and volumetric divisor for shipping quotes. |
| PUT | /business/shipping/settings | updateBusinessShippingSettings | Updates merchant shipping settings. |
| GET | /business/shipping/zones | listBusinessShippingZones | Shipping zones with rates for the merchant. |
| POST | /business/shipping/zones | createBusinessShippingZone | Creates a shipping zone by country. |
| PUT | /business/shipping/zones/:zone_id | updateBusinessShippingZone | Updates a shipping zone. |
| DELETE | /business/shipping/zones/:zone_id | deleteBusinessShippingZone | Deletes a shipping zone. |
| POST | /business/shipping/zones/:zone_id/rates | createBusinessShippingRate | Creates a shipping rate in a zone. |
| PUT | /business/shipping/zones/:zone_id/rates/:rate_id | updateBusinessShippingRate | Updates a shipping rate. |
| DELETE | /business/shipping/zones/:zone_id/rates/:rate_id | deleteBusinessShippingRate | Deletes a shipping rate. |
| GET | /business/shipping/package-profiles | listBusinessShippingPackageProfiles | Merchant package profiles. |
| POST | /business/shipping/package-profiles | createBusinessShippingPackageProfile | Creates a package profile. |
| PUT | /business/shipping/package-profiles/:profile_id | updateBusinessShippingPackageProfile | Updates a package profile. |
| DELETE | /business/shipping/package-profiles/:profile_id | deleteBusinessShippingPackageProfile | Deletes a package profile. |
| Catalog — Storefront | |||
| GET | /business/catalog/products/search | searchBusinessCatalogProducts | Public storefront catalog product search. |
| GET | /business/catalog/products/search/facets | getBusinessCatalogProductSearchFacets | Public product search facets. |
| GET | /business/catalog/products/by-slug/:slug | getBusinessCatalogProductBySlug | Public product detail by slug. |
| GET | /business/catalog/categories | listBusinessCatalogCategories | Public storefront catalog category listing. |
Specification
OpenAPI 3.1 spec generated from the Business API endpoint catalog. Use with client generators, Postman, or contract validation.
Errors
import {
HanixBusinessError,
HanixBusinessNetworkError,
HanixBusinessConfigError,
} from '@hanix.io/business';
try {
await client.getPaymentOrder(id);
} catch (error) {
if (error instanceof HanixBusinessError) {
console.log(error.status, error.body);
}
}HanixBusinessError4xx/5xx API responseHanixBusinessNetworkErrorTimeout or network failureHanixBusinessConfigErrorInvalid options when creating the client