DEVELOPERS

API reference

Every SMetaGateway REST endpoint, generated from the OpenAPI 3.1 contract. Use bearer API keys from your server; amounts are decimal strings.

Base URL: https://smg.sabco24.com/api/v1
Version: 0.2.0 · OpenAPI 3.1

Open Swagger UI OpenAPI JSON

Endpoints

All operations grouped by resource.

Method	Path	Description	Auth
System
GET	`/health`	Check service health and gateway mode.	Public
GET	`/config`	Read public client configuration, including the captcha site key.	Public
Authentication
POST	`/auth/register`	Register a merchant and start an owner session.	Public
POST	`/auth/login`	Sign in and start an owner session.	Public
POST	`/auth/logout`	End the current owner session.	Public
Account
GET	`/me`	Get the merchant account, wallets, invoices, keys, webhooks and statistics.	Owner session
PATCH	`/me`	Update the merchant display name.	Owner session
Wallets
GET	`/wallets`	List registered receiving addresses.	API key or session
POST	`/wallets`	Register a checksummed TRON receiving address (ownership unverified).	Owner session
Invoices
GET	`/invoices`	List the latest 500 invoices.	API key or session
POST	`/invoices`	Create an invoice and reserve a unique exact payable amount for 90 days.	API key or session
GET	`/invoices/{id}`	Retrieve one invoice belonging to this merchant.	API key or session
Checkout
GET	`/checkout/{token}`	Read payer-safe checkout details by checkout token.	Public
API keys
POST	`/api-keys`	Create an API key with an optional expiry; the secret is shown once.	Owner session
POST	`/api-keys/{id}/roll`	Replace an API key with a new secret of the same name and lifetime.	Owner session
DELETE	`/api-keys/{id}`	Revoke an API key immediately.	Owner session
Ledger
GET	`/ledger.csv`	Export the full operational ledger as CSV.	API key or session
Webhooks
POST	`/webhooks`	Register a public HTTPS webhook endpoint; the signing secret is shown once.	Owner session
DELETE	`/webhooks/{id}`	Disable an endpoint and cancel its pending deliveries.	Owner session
POST	`/webhooks/{id}/test`	Send a signed webhook.test event.	Owner session
POST	`/webhooks/deliveries/{id}/retry`	Retry a failed or pending webhook delivery.	Owner session
Support
POST	`/support/contact`	Send a message to support without an account.	Public
GET	`/support/tickets`	List your support tickets.	Owner session
POST	`/support/tickets`	Open a support ticket.	Owner session
GET	`/support/tickets/{id}`	Read one of your tickets with its messages.	Owner session
POST	`/support/tickets/{id}/messages`	Reply to your ticket; a closed ticket reopens.	Owner session
POST	`/support/tickets/{id}/close`	Close your ticket.	Owner session
GET	`/support/inbox`	Support team: list every ticket, open tickets first.	Owner session
GET	`/support/inbox/{id}`	Support team: read a ticket with contact details.	Owner session
POST	`/support/inbox/{id}/messages`	Support team: reply to a merchant ticket.	Owner session
POST	`/support/inbox/{id}/status`	Support team: set a ticket status.	Owner session

System

GET`/api/v1/health`

Public

Check service health and gateway mode.

Returns: 200 application/json

Field	Type	Required	Description
`status`	`"ok"`	No
`mode`	`"live"`	No	Invoices are confirmed from verified TRON mainnet transfers.
`live_payments_enabled`	`true`	No

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X GET "https://smg.sabco24.com/api/v1/health"

GET`/api/v1/config`

Public

Read public client configuration, including the captcha site key.

captcha is null when Cloudflare Turnstile is not configured; otherwise send captcha_token with sign-in, registration and contact requests.

Returns: 200 application/json

Field	Type	Required	Description
`captcha`	`object`	Yes

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X GET "https://smg.sabco24.com/api/v1/config"

Authentication

POST`/api/v1/auth/register`

Public

Request body

Field	Type	Required	Description
`email`	`string (email)`	Yes
`password`	`string (password)`	Yes	length 12–128
`captcha_token`	`string`	No	Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use. — length 0–2048
`name`	`string`	No	length 0–100

Returns: 201 application/json

Field	Type	Required	Description
`merchant`	`Merchant`	No

Responses

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Captcha verification is temporarily unavailable

Example request

curl -X POST "https://smg.sabco24.com/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example Store","email":"merchant@example.com","password":"a-long-unique-passphrase"}'

POST`/api/v1/auth/login`

Public

Request body

Field	Type	Required	Description
`email`	`string (email)`	Yes
`password`	`string (password)`	Yes	length 10–128
`captcha_token`	`string`	No	Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use. — length 0–2048

Returns: 200 application/json

Field	Type	Required	Description
`merchant`	`Merchant`	No

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Captcha verification is temporarily unavailable

Example request

curl -X POST "https://smg.sabco24.com/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"merchant@example.com","password":"a-long-unique-passphrase"}'

POST`/api/v1/auth/logout`

Public

End the current owner session.

Returns: 200 application/json

Field	Type	Required	Description
`success`	`true`	Yes

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X POST "https://smg.sabco24.com/api/v1/auth/logout" \
  -H "Content-Type: application/json" \
  -d '{}'

Account

GET`/api/v1/me`

Owner session

Get the merchant account, wallets, invoices, keys, webhooks and statistics.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Returns: 200 Dashboard

Field	Type	Required
`merchant`	`Merchant`	Yes
`wallets`	`Wallet[]`	Yes
`invoices`	`Invoice[]`	Yes
`events`	`Event[]`	Yes
`api_keys`	`ApiKey[]`	Yes
`webhooks`	`Webhook[]`	Yes
`deliveries`	`Delivery[]`	Yes
`stats`	`object`	Yes

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X GET "https://smg.sabco24.com/api/v1/me" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

PATCH`/api/v1/me`

Owner session

Update the merchant display name.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Request body

Field	Type	Required	Description
`name`	`string`	Yes	length 1–100

Returns: 200 Dashboard

Field	Type	Required
`merchant`	`Merchant`	Yes
`wallets`	`Wallet[]`	Yes
`invoices`	`Invoice[]`	Yes
`events`	`Event[]`	Yes
`api_keys`	`ApiKey[]`	Yes
`webhooks`	`Webhook[]`	Yes
`deliveries`	`Delivery[]`	Yes
`stats`	`object`	Yes

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X PATCH "https://smg.sabco24.com/api/v1/me" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'

Wallets

GET`/api/v1/wallets`

API key or session

List registered receiving addresses.

Returns: 200 application/json

Field	Type	Required	Description
`wallets`	`Wallet[]`	No

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X GET "https://smg.sabco24.com/api/v1/wallets" \
  -H "Authorization: Bearer $SMETA_API_KEY"

POST`/api/v1/wallets`

Owner session

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Request body

Field	Type	Required	Description
`label`	`string`	Yes	length 1–80
`address`	`string`	Yes	pattern ^T[1-9A-HJ-NP-Za-km-z]{33}$

Returns: 200 application/json

Field	Type	Required	Description
`wallet`	`Wallet`	No

Responses

200Existing address
201Registered
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X POST "https://smg.sabco24.com/api/v1/wallets" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"label":"Main business wallet","address":"T_YOUR_PUBLIC_TRON_ADDRESS"}'

Invoices

GET`/api/v1/invoices`

API key or session

List the latest 500 invoices.

Returns: 200 application/json

Field	Type	Required	Description
`invoices`	`Invoice[]`	No

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X GET "https://smg.sabco24.com/api/v1/invoices" \
  -H "Authorization: Bearer $SMETA_API_KEY"

POST`/api/v1/invoices`

API key or session

Create an invoice and reserve a unique exact payable amount for 90 days.

Amount allocation is global for (network, token contract, receiving address, final payable micro-units), including merchants sharing an address. Reservations outlive invoice expiry. Historical amount reuse is assigned review status. The invoice is confirmed only when a verified TRON transfer of exactly payable_amount reaches wallet_address between creation and expiry.

Required headers

Field	Type	Required	Description
`Idempotency-Key`	`string`	Yes	Unique key per invoice attempt; reuse it when retrying.

Request body `CreateInvoice`

Field	Type	Required	Description
`merchant_order_id`	`string`	Yes	Unique per merchant. Reuse the original idempotency key for retries. — length 1–120
`amount`	`string`	Yes	Base price in USDT; minimum 0.000001, maximum 1000000000. The server adds a disclosed identification adjustment. — pattern ^(0\|[1-9][0-9]{0,9})(\.[0-9]{1,6})?$ · e.g. "49.95"
`wallet_id`	`string`	Yes	ID of a wallet registered to this merchant. — length 1–100
`description`	`string`	No	length 1–1000
`metadata`	`object`	No	JSON object, at most 16 KiB when serialized. Keep customer secrets out of metadata.
`expires_in_minutes`	`integer`	No	range 1–1440 · default 20

Returns: 200 InvoiceEnvelope

Field	Type	Required	Description
`invoice`	`Invoice`	Yes
`idempotent_replay`	`boolean`	No

Responses

200Identical idempotent replay
201Invoice allocated
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X POST "https://smg.sabco24.com/api/v1/invoices" \
  -H "Authorization: Bearer $SMETA_API_KEY" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{"merchant_order_id":"1001","amount":"49.95","wallet_id":"WALLET_ID","description":"Example order","expires_in_minutes":20}'

GET`/api/v1/invoices/{id}`

API key or session

Retrieve one invoice belonging to this merchant.

Path parameters

Field	Type	Required	Description
`id`	`string`	Yes	Invoice ID

Returns: 200 application/json

Field	Type	Required	Description
`invoice`	`Invoice`	No

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X GET "https://smg.sabco24.com/api/v1/invoices/ID" \
  -H "Authorization: Bearer $SMETA_API_KEY"

Checkout

GET`/api/v1/checkout/{token}`

Public

Read payer-safe checkout details by checkout token.

Path parameters

Field	Type	Required	Description
`token`	`string`	Yes	Checkout capability token from checkout_url

Returns: 200 application/json

Field	Type	Required	Description
`invoice`	`CheckoutInvoice`	No

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X GET "https://smg.sabco24.com/api/v1/checkout/TOKEN"

API keys

POST`/api/v1/api-keys`

Owner session

Create an API key with an optional expiry; the secret is shown once.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Request body

Field	Type	Required	Description
`name`	`string`	Yes	length 1–80
`expires_in_days`	`integer \| null`	No	Days until the key expires. Omit or send null for a key that never expires. — range 1–3650 · e.g. 90

Returns: 201 application/json

Field	Type	Required
`api_key`	`ApiKey & object`	No
`secret`	`string`	No
`warning`	`string`	No

Responses

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X POST "https://smg.sabco24.com/api/v1/api-keys" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'

POST`/api/v1/api-keys/{id}/roll`

Owner session

Replace an API key with a new secret of the same name and lifetime.

The old key is revoked in the same transaction. The new secret is shown once.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Path parameters

Field	Type	Required	Description
`id`	`string`	Yes	API key ID

Returns: 201 application/json

Field	Type	Required
`api_key`	`ApiKey & object`	No
`secret`	`string`	No
`warning`	`string`	No
`replaced_key_id`	`string`	No

Responses

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X POST "https://smg.sabco24.com/api/v1/api-keys/ID/roll" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE`/api/v1/api-keys/{id}`

Owner session

Revoke an API key immediately.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Path parameters

Field	Type	Required	Description
`id`	`string`	Yes	API key ID

Returns: 200 application/json

Field	Type	Required	Description
`success`	`true`	Yes

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X DELETE "https://smg.sabco24.com/api/v1/api-keys/ID" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

Ledger

GET`/api/v1/ledger.csv`

API key or session

Export the full operational ledger as CSV.

Returns: 200 text/csv

Responses

200CSV includes separate base, adjustment and payable columns; not a statutory accounting report.
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X GET "https://smg.sabco24.com/api/v1/ledger.csv" \
  -H "Authorization: Bearer $SMETA_API_KEY"

Webhooks

POST`/api/v1/webhooks`

Owner session

Port 443 only. Local/private targets, IP literals, credentials, URL fragments and redirects are rejected. DNS is resolved and checked again at delivery time.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Request body

Field	Type	Required	Description
`url`	`string (uri)`	Yes	length 0–2048

Returns: 201 application/json

Field	Type	Required	Description
`webhook`	`Webhook & object`	No
`secret`	`string`	No

Responses

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X POST "https://smg.sabco24.com/api/v1/webhooks" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://merchant.example.com/hooks/smeta"}'

DELETE`/api/v1/webhooks/{id}`

Owner session

Disable an endpoint and cancel its pending deliveries.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Path parameters

Field	Type	Required	Description
`id`	`string`	Yes	Webhook ID

Returns: 200 application/json

Field	Type	Required	Description
`success`	`true`	Yes

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X DELETE "https://smg.sabco24.com/api/v1/webhooks/ID" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

POST`/api/v1/webhooks/{id}/test`

Owner session

Send a signed webhook.test event.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Path parameters

Field	Type	Required	Description
`id`	`string`	Yes	Webhook ID

Returns: 200 application/json

Field	Type	Required	Description
`event`	`Event`	No
`deliveries`	`Delivery[]`	No

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X POST "https://smg.sabco24.com/api/v1/webhooks/ID/test" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{}'

POST`/api/v1/webhooks/deliveries/{id}/retry`

Owner session

Retry a failed or pending webhook delivery.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Path parameters

Field	Type	Required	Description
`id`	`string`	Yes	Delivery ID

Returns: 200 application/json

Field	Type	Required	Description
`delivery`	`Delivery`	No

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X POST "https://smg.sabco24.com/api/v1/webhooks/deliveries/ID/retry" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{}'

POST`https://your-server.example/hooks/smeta`

Receive a signed gateway event at your configured URL

Verify HMAC-SHA256(secret, timestamp + "." + original raw body). The signature header is sha256=<lowercase hex>. Reject timestamps outside your five-minute window and deduplicate event IDs. Each retry is freshly signed. GET the saved invoice with your server key and reconcile it before fulfilling once. invoice.confirmed includes the matched on-chain transaction.

Required headers

X-SMeta-Event-IdX-SMeta-TimestampX-SMeta-Signature

Responses

200Persisted successfully or already processed. Any 2xx acknowledges delivery.
400Invalid event
401Invalid or stale signature
503Temporary failure; retry delivery

Support

POST`/api/v1/support/contact`

Public

Send a message to support without an account.

Creates a ticket that the support team answers by email. Only the reference is returned.

Request body

Field	Type	Required	Description
`name`	`string`	Yes	length 1–100
`email`	`string (email)`	Yes	length 0–254
`subject`	`string`	Yes	length 1–150
`category`	`"general" \| "payments" \| "technical" \| "account" \| "other"`	No	default "general"
`message`	`string`	Yes	length 1–5000
`captcha_token`	`string`	No	Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use. — length 0–2048

Returns: 201 application/json

Field	Type	Required	Description
`ticket`	`object`	No

Responses

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Captcha verification is temporarily unavailable

Example request

curl -X POST "https://smg.sabco24.com/api/v1/support/contact" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","email":"jane@example.com","subject":"Question about pricing","category":"general","message":"Do you charge per invoice?","captcha_token":"TURNSTILE_RESPONSE_TOKEN"}'

GET`/api/v1/support/tickets`

Owner session

List your support tickets.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Returns: 200 application/json

Field	Type	Required	Description
`tickets`	`SupportTicket[]`	No

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X GET "https://smg.sabco24.com/api/v1/support/tickets" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

POST`/api/v1/support/tickets`

Owner session

Open a support ticket.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Request body

Field	Type	Required	Description
`subject`	`string`	Yes	length 1–150
`category`	`"general" \| "payments" \| "technical" \| "account" \| "other"`	No	default "general"
`message`	`string`	Yes	length 1–5000

Returns: 201 SupportThread

Field	Type	Required	Description
`ticket`	`SupportTicket`	Yes
`messages`	`SupportMessage[]`	Yes

Responses

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X POST "https://smg.sabco24.com/api/v1/support/tickets" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Webhook signature fails","category":"technical","message":"Deliveries return 401 since yesterday."}'

GET`/api/v1/support/tickets/{id}`

Owner session

Read one of your tickets with its messages.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Path parameters

Field	Type	Required	Description
`id`	`string`	Yes	Ticket ID

Returns: 200 SupportThread

Field	Type	Required	Description
`ticket`	`SupportTicket`	Yes
`messages`	`SupportMessage[]`	Yes

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X GET "https://smg.sabco24.com/api/v1/support/tickets/ID" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

POST`/api/v1/support/tickets/{id}/messages`

Owner session

Reply to your ticket; a closed ticket reopens.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Path parameters

Field	Type	Required	Description
`id`	`string`	Yes	Ticket ID

Request body

Field	Type	Required	Description
`message`	`string`	Yes	length 1–5000

Returns: 201 SupportThread

Field	Type	Required	Description
`ticket`	`SupportTicket`	Yes
`messages`	`SupportMessage[]`	Yes

Responses

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X POST "https://smg.sabco24.com/api/v1/support/tickets/ID/messages" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"message":"string"}'

POST`/api/v1/support/tickets/{id}/close`

Owner session

Close your ticket.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Path parameters

Field	Type	Required	Description
`id`	`string`	Yes	Ticket ID

Returns: 200 SupportThread

Field	Type	Required	Description
`ticket`	`SupportTicket`	Yes
`messages`	`SupportMessage[]`	Yes

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X POST "https://smg.sabco24.com/api/v1/support/tickets/ID/close" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{}'

GET`/api/v1/support/inbox`

Owner session

Support team: list every ticket, open tickets first.

Requires a session for an account listed in SUPPORT_STAFF_EMAILS.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Returns: 200 application/json

Field	Type	Required	Description
`tickets`	`SupportTicket[]`	No

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X GET "https://smg.sabco24.com/api/v1/support/inbox" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

GET`/api/v1/support/inbox/{id}`

Owner session

Support team: read a ticket with contact details.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Path parameters

Field	Type	Required	Description
`id`	`string`	Yes	Ticket ID

Returns: 200 SupportThread

Field	Type	Required	Description
`ticket`	`SupportTicket`	Yes
`messages`	`SupportMessage[]`	Yes

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X GET "https://smg.sabco24.com/api/v1/support/inbox/ID" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

POST`/api/v1/support/inbox/{id}/messages`

Owner session

Support team: reply to a merchant ticket.

Contact-form tickets return 409 email_reply_required because the visitor has no account.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Path parameters

Field	Type	Required	Description
`id`	`string`	Yes	Ticket ID

Request body

Field	Type	Required	Description
`message`	`string`	Yes	length 1–5000

Returns: 201 SupportThread

Field	Type	Required	Description
`ticket`	`SupportTicket`	Yes
`messages`	`SupportMessage[]`	Yes

Responses

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X POST "https://smg.sabco24.com/api/v1/support/inbox/ID/messages" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"message":"string"}'

POST`/api/v1/support/inbox/{id}/status`

Owner session

Support team: set a ticket status.

Requires the dashboard owner session cookie; API keys are rejected for this operation.

Path parameters

Field	Type	Required	Description
`id`	`string`	Yes	Ticket ID

Request body

Field	Type	Required	Description
`status`	`"open" \| "answered" \| "closed"`	Yes

Returns: 200 SupportThread

Field	Type	Required	Description
`ticket`	`SupportTicket`	Yes
`messages`	`SupportMessage[]`	Yes

Responses

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

Example request

curl -X POST "https://smg.sabco24.com/api/v1/support/inbox/ID/status" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"status":"open"}'

Schemas

Objects returned and accepted by the API.

Error

Field	Type	Required	Description
`error`	`object`	Yes
`mode`	`"live"`	Yes	Invoices are confirmed from verified TRON mainnet transfers.

Merchant

Field	Type	Required	Description
`id`	`string`	Yes
`name`	`string`	Yes
`email`	`string (email)`	Yes
`mode`	`"live"`	Yes	Invoices are confirmed from verified TRON mainnet transfers.
`support_staff`	`boolean`	No	True when this account is listed in SUPPORT_STAFF_EMAILS and may use the support inbox.

SupportTicket

Field	Type	Required	Description
`id`	`string`	Yes
`reference`	`string`	Yes	Human-friendly reference such as SMG-1A2B3C4D5E.
`subject`	`string`	Yes
`category`	`"general" \| "payments" \| "technical" \| "account" \| "other"`	Yes	default "general"
`status`	`"open" \| "answered" \| "closed"`	Yes	open: waiting for support; answered: support replied; closed: resolved.
`source`	`"dashboard" \| "contact"`	Yes
`created_at`	`string (date-time)`	Yes
`updated_at`	`string (date-time)`	Yes
`name`	`string`	No	Support inbox only.
`email`	`string (email)`	No	Support inbox only.
`merchant_id`	`string \| null`	No	Support inbox only. Null for public contact messages.
`merchant_name`	`string \| null`	No	Support inbox only.

SupportMessage

Field	Type	Required
`id`	`string`	Yes
`author`	`"customer" \| "staff"`	Yes
`body`	`string`	Yes
`created_at`	`string (date-time)`	Yes

SupportThread

Field	Type	Required	Description
`ticket`	`SupportTicket`	Yes
`messages`	`SupportMessage[]`	Yes

Wallet

Field	Type	Required
`id`	`string`	Yes
`label`	`string`	Yes
`address`	`string`	Yes
`network`	`"tron-mainnet"`	Yes
`verified`	`false`	Yes
`verification_status`	`"unverified"`	Yes
`created_at`	`string (date-time)`	Yes

CheckoutInvoice

Field	Type	Required	Description
`id`	`string`	Yes
`base_amount`	`string`	Yes	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`adjustment`	`string`	Yes	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`payable_amount`	`string`	Yes	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`wallet_address`	`string`	Yes
`status`	`"pending" \| "confirmed" \| "expired" \| "review"`	Yes
`created_at`	`string (date-time)`	No
`expires_at`	`string (date-time)`	No
`reserved_until`	`string (date-time)`	No
`description`	`string`	No
`tx_hash`	`string \| null`	No	TRON transaction hash of the matched USDT transfer (64 hex characters).
`mode`	`"live"`	Yes	Invoices are confirmed from verified TRON mainnet transfers.
`network`	`"tron-mainnet"`	No
`token`	`"USDT"`	No
`token_contract`	`"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"`	No
`amount_reuse_review`	`boolean`	No
`merchant_name`	`string`	Yes	Merchant business display name.

Invoice

Field	Type	Required	Description
`id`	`string`	Yes
`base_amount`	`string`	Yes	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`adjustment`	`string`	Yes	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`payable_amount`	`string`	Yes	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`wallet_address`	`string`	Yes
`status`	`"pending" \| "confirmed" \| "expired" \| "review"`	Yes
`created_at`	`string (date-time)`	No
`expires_at`	`string (date-time)`	No
`reserved_until`	`string (date-time)`	No
`description`	`string`	No
`tx_hash`	`string \| null`	No	TRON transaction hash of the matched USDT transfer (64 hex characters).
`mode`	`"live"`	Yes	Invoices are confirmed from verified TRON mainnet transfers.
`network`	`"tron-mainnet"`	No
`token`	`"USDT"`	No
`token_contract`	`"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"`	No
`amount_reuse_review`	`boolean`	No
`checkout_url`	`string (uri)`	No
`checkout_token`	`string`	No	Capability token. Treat checkout URLs as confidential invoice links.
`merchant_order_id`	`string`	Yes
`wallet_id`	`string`	Yes
`metadata`	`object`	Yes

CreateInvoice

Field	Type	Required	Description
`merchant_order_id`	`string`	Yes	Unique per merchant. Reuse the original idempotency key for retries. — length 1–120
`amount`	`string`	Yes	Base price in USDT; minimum 0.000001, maximum 1000000000. The server adds a disclosed identification adjustment. — pattern ^(0\|[1-9][0-9]{0,9})(\.[0-9]{1,6})?$ · e.g. "49.95"
`wallet_id`	`string`	Yes	ID of a wallet registered to this merchant. — length 1–100
`description`	`string`	No	length 1–1000
`metadata`	`object`	No	JSON object, at most 16 KiB when serialized. Keep customer secrets out of metadata.
`expires_in_minutes`	`integer`	No	range 1–1440 · default 20

InvoiceEnvelope

Field	Type	Required	Description
`invoice`	`Invoice`	Yes
`idempotent_replay`	`boolean`	No

ApiKey

Field	Type	Required	Description
`id`	`string`	Yes
`name`	`string`	Yes
`prefix`	`string`	Yes	First characters of the secret, for identification only.
`mode`	`"live"`	Yes	Invoices are confirmed from verified TRON mainnet transfers.
`scopes`	`"invoices:read" \| "invoices:write" \| "ledger:read"[]`	Yes
`created_at`	`string (date-time)`	No
`last_used_at`	`string \| null (date-time)`	No
`revoked_at`	`string \| null (date-time)`	No
`expires_at`	`string \| null (date-time)`	No	Null when the key never expires.
`expired`	`boolean`	No

Webhook

Field	Type	Required
`id`	`string`	Yes
`url`	`string (uri)`	Yes
`created_at`	`string (date-time)`	No
`active`	`boolean`	Yes

Delivery

Field	Type	Required
`id`	`string`	Yes
`webhook_id`	`string`	Yes
`event_id`	`string`	Yes
`status`	`"pending" \| "sending" \| "delivered" \| "failed" \| "cancelled"`	Yes
`attempts`	`integer`	Yes
`next_attempt_at`	`string \| null (date-time)`	No
`last_error`	`string \| null`	No
`response_status`	`integer \| null`	No
`created_at`	`string (date-time)`	No
`delivered_at`	`string \| null (date-time)`	No

Event

Field	Type	Required	Description
`id`	`string`	Yes
`type`	`"invoice.created" \| "invoice.confirmed" \| "invoice.expired" \| "invoice.review" \| "webhook.test"`	Yes
`created_at`	`string (date-time)`	Yes
`mode`	`"live"`	Yes	Invoices are confirmed from verified TRON mainnet transfers.
`data`	`object`	Yes

ConfirmedEvent

Field	Type	Required	Description
`id`	`string`	Yes
`type`	`"invoice.confirmed"`	Yes
`created_at`	`string (date-time)`	Yes
`mode`	`"live"`	Yes	Invoices are confirmed from verified TRON mainnet transfers.
`data`	`object`	Yes

Dashboard

Field	Type	Required
`merchant`	`Merchant`	Yes
`wallets`	`Wallet[]`	Yes
`invoices`	`Invoice[]`	Yes
`events`	`Event[]`	Yes
`api_keys`	`ApiKey[]`	Yes
`webhooks`	`Webhook[]`	Yes
`deliveries`	`Delivery[]`	Yes
`stats`	`object`	Yes

Endpoints

System

Responses

Responses

Authentication

Request body

Responses

Request body

Responses

Responses

Account

Responses

Request body

Responses

Wallets

Responses

Request body

Responses

Invoices

Responses

Required headers

Request body CreateInvoice

Responses

Path parameters

Responses

Checkout

Path parameters

Responses

API keys

Request body

Responses

Path parameters

Responses

Path parameters

Responses

Ledger

Responses

Webhooks

Request body

Responses

Path parameters

Responses

Path parameters

Responses

Path parameters

Responses

Required headers

Responses

Support

Request body

Responses

Responses

Request body

Responses

Path parameters

Responses

Path parameters

Request body

Responses

Path parameters

Responses

Responses

Path parameters

Responses

Path parameters

Request body

Responses

Path parameters

Request body

Responses

Schemas

Request body `CreateInvoice`