Documentation API

Crypto payment integration: deposit wallets, callbacks (IPN), on-chain configuration (split). All content is self-contained in this file (HTML + CSS + JS).

General information

Item	Detail
Format	JSON — `Content-Type: application/json` for request bodies
Encodage	UTF-8
CORS	`Access-Control-Allow-Origin: *` with appropriate headers
Preflight	`OPTIONS` → `200` empty body

Base URL

Replace {BASE_URL} according to environment.

Environment	URL
Production	`https://nxtgatew.com`
Local (ex. MAMP)	`http://localhost:8888/nxtgatew`

API paths: POST {BASE_URL}/api/v1/wallets/create · GET {BASE_URL}/api/v1/wallets/check-config

Authentication

Each request must include:

Header	Required	Description
`X-API-Key`	Yes	API key (`merchant`, `psp`, or `admin`)
`X-API-Secret`	Yes	Matching API secret

Credentials are created at signup (merchant / PSP; admin possible for operations). Do not publish the secret. Accounts must be active with role merchant, psp, or admin — otherwise 401.

HTTP codes & errors

Typical error schema:

Example

{
  "success": false,
  "error": "Human-readable message explaining the issue"
}

Additional fields may include: hint, json_error_code, raw_input_preview, debug, etc.

Code	Meaning
200	Success (GET, OPTIONS)
201	Resource created (POST create wallet)
400	Invalid request (JSON, fields, network, URL, address)
401	Invalid API credentials or inactive account
403	Inactive merchant account (business rule)
404	Not found (missing wallet or not yours)
405	HTTP method not allowed
409	Conflict (e.g. address already in database)
429	Too many requests (other endpoints, e.g. cron)
500	Server error

POST Create deposit wallet

Platform-generated receive address, IPN callback, optional affiliates. On Ethereum / Polygon, split_config in the 201 response is only for admin API keys; merchants use GET check-config.

POST {BASE_URL}/api/v1/wallets/create

Key	Value
`Content-Type`	`application/json`
`X-API-Key`	Your API key
`X-API-Secret`	Your API secret

Field	Type	Req.	Description
`address`	string	Yes	Merchant wallet (destination after split). Format per `network`.
`callback`	string	Yes	IPN notification URL. Alias: `callback_url`.
`network`	string	No	`ethereum` \| `polygon` \| `tron` \| `solana` — default `ethereum`
`affiliate_address`	string	No	Affiliate address — with `affiliate_percent` ou `affiliate_percent_bps`
`subaff_address`	string	No	Sub-affiliate — with `subaff_percent` ou `subaff_percent_bps`
`affiliate_percent`	number	No	% of gross (e.g. `1` = 1%) — takes precedence over `affiliate_percent_bps`
`subaff_percent`	number	No	Same for sub-affiliate
`split_amounts_unit`	string	No	`bps` (default) or `percent`: if `percent`, `*_percent_bps` = % of gross, not bps
`affiliate_percent_bps`	int	No	Bps of gross (100 = 1%) unless `split_amounts_unit` = `percent`
`subaff_percent_bps`	int	No	Same for sub-affiliate
`ipn_token`	string	No	Your correlation token; otherwise generated (64 hex)

Formats: EVM 0x + 40 hex · Tron T + 34 chars · Solana base58 (32–44 chars)

Affiliate and sub-affiliate

Shares as % of gross amount (stored internally as bps). Example JSON fields:

JSON

"affiliate_address": "0x4B31D368067127D10C59e655b8B22937E35D1196",
"affiliate_percent": 1,
"subaff_address": "0x2222222222222222222222222222222222222222",
"subaff_percent": 0.5

HTTP	`error` (extrait)
400	`No JSON body provided`
400	`Invalid JSON input`
400	`Invalid network…`
400	`Missing required field: address` / `callback`
400	Invalid address / callback format
401	`Invalid API credentials`
403	`Merchant account is not active`
405	`Method not allowed. Use POST.`
409	`Wallet address already exists…`
500	`Failed to generate wallet` / DB / server

cURL

Shell

curl -X POST "https://nxtgatew.com/api/v1/wallets/create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -H "X-API-Secret: YOUR_SECRET" \
  -d '{
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "callback": "https://your-site.com/webhooks/nxtgatew",
    "network": "polygon",
    "affiliate_address": "0x4B31D368067127D10C59e655b8B22937E35D1196",
    "affiliate_percent": 1,
    "subaff_address": "0x2222222222222222222222222222222222222222",
    "subaff_percent": 0.5
  }'

Response — 201 Created

Body 201 Created

{
  "success": true,
  "data": {
    "address": "0x…",
    "ipn_token": "64_hex_chars_or_your_token",
    "network": "polygon",
    "callback_url": "https://your-site.com/webhooks/nxtgatew",
    "created_at": "2026-04-17 12:00:00",
    "affiliate_wallet_address": "0x4B31D368067127D10C59e655b8B22937E35D1196",
    "subaff_wallet_address": "0x2222222222222222222222222222222222222222",
    "platform_percent": 1,
    "affiliate_percent": 1,
    "subaff_percent": 0.5
  },
  "message": "Wallet created successfully"
}

Merchant / PSP response on EVM: no split_config. With admin API key, data.split_config may include mode, created, contract_address, error, check_url.

`data` field	Description
`address`	Generated address to give the payer
`ipn_token`	Keep to link / secure callbacks
`affiliate_wallet_address` / `subaff_wallet_address`	Omitted from JSON if not provided at creation
`platform_percent`	Platform share — % of gross only (no `*_bps` in JSON response)
`affiliate_percent` / `subaff_percent`	% of gross — omitted if no affiliate / sub-affiliate address at creation
`split_config`	`ethereum` / `polygon` and API role `admin` only; otherwise `GET check-config`

GET Verify split configuration

State of a deposit wallet you own: database + on-chain read (EVM if the server runs the verification script).

GET {BASE_URL}/api/v1/wallets/check-config?wallet_address=…&network=polygon

Key	Value
`X-API-Key`	Your API key
`X-API-Secret`	Your API secret

Content-Type optional on bodyless GET.

Parameter	Req.	Default	Description
`wallet_address`	Yes	—	Generated address (`data.address` from create)
`network`	No	`polygon`	Must match the wallet

HTTP	`error`
400	`Missing parameter: wallet_address`
401	`Invalid API credentials`
404	`Wallet not found or does not belong to your account`
405	`Method not allowed. Use GET.`
500	`Server error: …`

cURL

Shell

curl -G "https://nxtgatew.com/api/v1/wallets/check-config" \
  -H "X-API-Key: YOUR_KEY" \
  -H "X-API-Secret: YOUR_SECRET" \
  --data-urlencode "wallet_address=0xYourGeneratedAddress" \
  --data-urlencode "network=polygon"

Response — 200 OK

Body 200 OK

{
  "success": true,
  "data": {
    "wallet_address": "0x…",
    "network": "polygon",
    "database": {
      "merchant_wallet": "0x…",
      "affiliate_wallet": "0x4B31D368067127D10C59e655b8B22937E35D1196",
      "subaff_wallet": "0x2222222222222222222222222222222222222222",
      "platform_percent": 1,
      "affiliate_percent": 1,
      "subaff_percent": 0.5,
      "contract_address": "0x…",
      "status": "active",
      "created_at": "2026-04-17 12:00:00"
    },
    "on_chain": {
      "config_exists": true,
      "merchant_wallet": "0x…",
      "affiliate_wallet": "0x4B31D368067127D10C59e655b8B22937E35D1196",
      "subaff_wallet": "0x2222222222222222222222222222222222222222",
      "is_active": true
    },
    "match": true
  }
}

Champ	Description
`database.*`	Data stored in NxtGateW; `platform_percent` always; `affiliate_percent` / `subaff_percent` only if address is set in DB — no `*_bps`
`on_chain.config_exists`	Config read from chain
`match`	`true` if on-chain config + merchant address matches database

Basis points (bps)

10 000 bps = 100 %

bps	%
100	1 %
50	0.5%
1	0.01%

Platform fees and caps (platform + affiliates ≤ 100%) are enforced on-chain.

Best practices

HTTPS for callback in production.
Validate ipn_token (or signature) on each inbound webhook.
After create on EVM, use GET check-config to validate database vs on-chain (admins may also read split_config in the create response).
On 401, check headers, encoding, and merchant account status.

Summary

Method	Path	Purpose
POST	`/api/v1/wallets/create`	Create deposit address + callback / split
GET	`/api/v1/wallets/check-config`	Verify database + on-chain

Source reference: api/v1/wallets/create.php, api/v1/wallets/check-config.php