# Lumo B2B Platform API

API reference for **company-facing** endpoints of Lumo B2B platform.

Scope of this reference:
- Company auth/profile
- Orders (prepare/accept/list/get)
- Company disputes
- Company wallet + deposits
- User wallets (per externalId) + user deposits

Not included:
- Admin endpoints


Version: 1.0.0

## Servers

Production
```
https://b2b.lumowallet.io
```

Staging
```
https://b2b-staging.lumowallet.io
```

## Security

### apiKeyAuth

Company API key.
Service also accepts `Authorization: Bearer <api-key>` and `api_key` query param,
but `X-API-Key` is recommended.


Type: apiKey
In: header
Name: X-API-Key

## Download OpenAPI description

[Lumo B2B Platform API](https://lumo.redocly.app/_bundle/apis/index.yaml)

## Company Auth

Company registration, login, and profile management.

### Company login

 - [POST /auth/company/login](https://lumo.redocly.app/apis/company-auth/logincompany.md): Authenticates company by email/password and rotates API key.
Previous key becomes invalid after successful login.

### Get company profile

 - [GET /auth/company/profile](https://lumo.redocly.app/apis/company-auth/getcompanyprofile.md)

### Update company profile

 - [PATCH /auth/company/profile](https://lumo.redocly.app/apis/company-auth/updatecompanyprofile.md)

### Regenerate company API key

 - [POST /auth/company/regenerate-key](https://lumo.redocly.app/apis/company-auth/regeneratecompanyapikey.md): Rotates and returns a new API key for current company.

## Orders

Quote preparation and order lifecycle operations.

### Prepare order (create quote)

 - [POST /orders/prepare](https://lumo.redocly.app/apis/orders/prepareorder.md): Creates quote from NSPK QR code.
Quote TTL is short-lived (30 seconds in current implementation).

### Accept quote and create order

 - [POST /orders/accept/{id}](https://lumo.redocly.app/apis/orders/acceptorder.md): Converts quote into order and reserves funds (frozenBalance).

Idempotency:
- Optional header Idempotency-Key.
- Repeated request with same key for same company returns stored response.

### List company orders

 - [GET /orders](https://lumo.redocly.app/apis/orders/listorders.md)

### Get order by id

 - [GET /orders/{id}](https://lumo.redocly.app/apis/orders/getorder.md)

## Disputes

Company dispute creation and listing.

### Open dispute for order

 - [POST /orders/{id}/disputes](https://lumo.redocly.app/apis/disputes/createdispute.md): Allowed only for completed order states (success or failed).

Behavior:
- On create, order is moved to disputed.
- If an open dispute already exists for the order (submitted / in_review), API returns that dispute.
- Dispute is also sent to wallet-backend for synchronized processing.

### List company disputes

 - [GET /disputes](https://lumo.redocly.app/apis/disputes/listdisputes.md): Returns company dispute history (newest first).

Resolution fields:
- resolvedAt is set when dispute is resolved.
- resolution is set on resolve (confirm, refund, partial_refund).
- refundAmount is set only for partial_refund; for confirm/refund it is null.

Disputes can be resolved by admin flow or automatically from wallet callback final status.

## Company Wallet

Company deposit wallet, balances, and deposit history.

### Get company deposit wallet

 - [GET /wallets](https://lumo.redocly.app/apis/company-wallet/getcompanywallet.md): Returns company TRON wallet address for incoming USDT (TRC-20).
Wallet is auto-created on first request if absent.

### Get wallet balance view

 - [GET /wallets/balance](https://lumo.redocly.app/apis/company-wallet/getcompanywalletbalance.md): Returns company balance view.
usdtBalance reflects company balance used by platform accounting.

### List company deposits

 - [GET /wallets/deposits](https://lumo.redocly.app/apis/company-wallet/listcompanydeposits.md): Deposit status lifecycle:
- new
- fee_charged
- aml_pending / aml_passed / aml_failed
- forwarding
- completed / failed

Company deposit sweep target is B2B_TREASURY_ADDRESS.
Processing fee is retained from incoming deposit amount (not debited from company balance).

## User Wallets

Per-user wallet management and user deposit history.

### Create user wallet

 - [POST /user-wallets](https://lumo.redocly.app/apis/user-wallets/createuserwallet.md): Creates or returns wallet for given externalId within company scope.

### List user wallets

 - [GET /user-wallets](https://lumo.redocly.app/apis/user-wallets/listuserwallets.md)

### List blocked user wallets

 - [GET /user-wallets/blocked](https://lumo.redocly.app/apis/user-wallets/listblockeduserwallets.md)

### Block user wallet

 - [POST /user-wallets/{walletId}/block](https://lumo.redocly.app/apis/user-wallets/blockuserwallet.md)

### Replace user wallet

 - [POST /user-wallets/{walletId}/replace](https://lumo.redocly.app/apis/user-wallets/replaceuserwallet.md): Blocks old wallet and creates a new one for the same external user.

### List user-wallet deposits

 - [GET /user-wallets/deposits](https://lumo.redocly.app/apis/user-wallets/listuserwalletdeposits.md)