Production API

Nivisco Payment API Documentation

Secure POST-only JSON gateway for authentication, users, wallets, cards, one-off charges, and recurring billing.

POST https://xtobora.com Content-Type: application/json Auth: business_id + api_key

Request Envelope

All actions inherit these fields

JSON

{
  "business_id": "BUS-12345",
  "api_key": "<64-char-hex>",
  "action": "<see catalog>",
  "...": "action-specific payload"
}

Portal

Docs

Full production documentation, endpoints, request/response shapes, and error handling.

Open Docs

Resources

SDK

Official client libraries, install instructions, and usage examples for rapid integration.

View SDK

Tools

API Live Test

Try live requests against TEST/LIVE with your business_id and api_key—no code required.

Start Testing

Start fast

Quickstart

PHP (cURL)

function callNivisco($action, $payload = []) {
  $url = 'https://xtobora.com';
  $body = array_merge([
    'business_id' => 'BUS-12345',
    'api_key'     => '<api_key>',
    'action'      => $action
  ], $payload);

  $ch = curl_init($url);
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($body, JSON_UNESCAPED_SLASHES)
  ]);

  $response = curl_exec($ch);
  if ($response === false) {
    throw new Exception('cURL error: ' . curl_error($ch));
  }
  $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($status < 200 || $status >= 300) {
    throw new Exception('HTTP ' . $status . ': ' . $response);
  }
  return json_decode($response, true);
}

try {
  $res = callNivisco('validate_business');
  print_r($res);
} catch (Exception $e) {
  error_log($e->getMessage());
}

Conventions

API Standards

Transport

HTTPS only. All operations are POST with application/json bodies.
Requests with other methods return 405 Method Not Allowed.
No auth headers: include business_id and api_key in the JSON envelope.

Idempotency & Retries

Network-safe to retry on HTTP 5xx. We guarantee idempotent semantics for actions with a server-side generated identifier.
Client may send idempotency_key (string ≤ 64) to dedupe within 24h per business.
Timeout recommendation: 30s. Use exponential backoff starting at 250ms.

Pagination & Filtering

Use page (1-based) and limit (≤100). Response includes total.
Date filters expect ISO8601 (from_date, to_date) in UTC.

Security

Rotate keys regularly (change_api_key). Store server-side only.
All gateway secrets are encrypted at rest.
PII minimization: only store required user fields.

Overview

Action Catalog

Action	Category	Description
`validate_business`	Authentication	Confirm business credentials.
`get_business_info`	Authentication	Fetch business profile details.
`register_business`	Business	Create a new business (admin).
`modify_business`	Business	Update name/email (domain-locked).
`change_api_key`	Business	Rotate API key.
`add_stripe_credentials`	Credentials	Store Stripe keys for TEST/LIVE.
`modify_stripe_credentials`	Credentials	Update Stripe secrets.
`add_authorize_credentials`	Credentials	Store Authorize.Net keys.
`modify_authorize_credentials`	Credentials	Update Authorize.Net secrets.
`validate_user`	Users	Validate user belongs to the business.
`get_user_info`	Users	Get user profile.
`get_all_users`	Users	List active users.
`update_user`	Users	Change name/email.
`create_user`	Users	Create user + wallet.
`get_stripe_public_key`	Keys	Return Stripe publishable key.
`get_user_cards`	Cards	List saved cards (Stripe/Authorize).
`get_user_primary_card`	Cards	Primary card per gateway.
`create_stripe_customer`	Cards	Create Stripe customer+card from token.
`create_authorize_customer`	Cards	Create Authorize.Net customer+card.
`charge_customer`	Payments	Charge primary stored card.
`fund_customer`	Payments	Charge and credit wallet.
`get_payment_records`	Payments	Paginated gateway history.
`get_user_wallet`	Wallet	Get wallet balance.
`get_wallet_history`	Wallet	Wallet transactions.
`charge_wallet`	Wallet	Debit wallet.
`add_wallet_funds`	Wallet	Credit wallet.
`create_recurring`	Recurring	Create subscription/job schedule.
`update_recurring`	Recurring	Modify job fields.
`pause_recurring`	Recurring	Pause a job.
`resume_recurring`	Recurring	Resume a job.
`cancel_recurring`	Recurring	Cancel a job.
`list_recurring`	Recurring	List jobs.
`get_recurring_logs`	Recurring	Execution logs.

Authentication

Credential Validation

All requests require valid business_id and api_key. Missing/invalid credentials → 401.

`validate_business` POST

Validate credentials.

{
  "action": "validate_business",
  "business_id": "BUS-12345",
  "api_key": "..."
}

{
  "success": true,
  "business": {"business_id": "BUS-12345"}
}

`get_business_info` POST

Return business profile metadata.

{
  "action": "get_business_info",
  "business_id": "BUS-12345",
  "api_key": "..."
}

{
  "success": true,
  "business": {
    "business_id": "BUS-12345",
    "name": "Sample Coffee",
    "email": "owner@example.com",
    "domain": "samplecoffee.com",
    "created_at": "2024-02-01 12:00:00"
  }
}

Business

Business Management

`register_business`

Admin-only. Email domain of new_business.email must match new_business.domain.

{
  "action": "register_business",
  "business_id": "ADMIN-BUSINESS",
  "api_key": "...",
  "new_business": {
    "name": "Northwind Coffee",
    "email": "owner@northwindcoffee.com",
    "domain": "northwindcoffee.com"
  }
}

{
  "success": true,
  "message": "Business registered successfully",
  "business_id": "2a0c5c52-6e6d-4c5a-8a58-4d5d7f818abc",
  "api_key": "0a8f2d...",
  "domain": "northwindcoffee.com"
}

`modify_business`

{
  "action": "modify_business",
  "business_id": "BUS-12345",
  "api_key": "...",
  "updates": {"name": "Houston Coffee Roasters", "email": "accounts@houstoncoffee.com"}
}

{
  "success": true,
  "message": "Business updated successfully",
  "business_id": "BUS-12345",
  "updated_fields": ["name","email"]
}

`change_api_key`

{"action":"change_api_key","business_id":"BUS-12345","api_key":"..."}

{
  "success": true,
  "message": "API key rotated successfully",
  "business_id": "BUS-12345",
  "api_key": "4dbcec..."
}

Gateway Credentials

Payment Provider Configuration

`add_stripe_credentials` / `modify_stripe_credentials`

{
  "action": "add_stripe_credentials",
  "business_id": "BUS-12345",
  "api_key": "...",
  "credentials": {
    "env": "TEST",
    "stripe_secret_key": "sk_test_...",
    "stripe_public_key": "pk_test_...",
    "stripe_webhook_secret": "whsec_...",
    "account_id": "acct_..."
  }
}

{
  "success": true,
  "message": "Stripe credentials saved",
  "env": "TEST"
}

`add_authorize_credentials` / `modify_authorize_credentials`

{
  "action": "add_authorize_credentials",
  "business_id": "BUS-12345",
  "api_key": "...",
  "credentials": {
    "env": "LIVE",
    "api_login_id": "7y33L5",
    "transaction_key": "55A4A25E2CD6567FB39",
    "signature_key": "D7D0F6753ED..."
  }
}

{
  "success": true,
  "message": "Authorize.Net credentials saved",
  "env": "LIVE"
}

Users

User Directory

`validate_user`

{"action":"validate_user","business_id":"BUS-12345","api_key":"...","user_id":"USR-5678"}

{"success":true,"user":{"user_id":"USR-5678","active":true}}

`get_user_info`

{"action":"get_user_info","business_id":"BUS-12345","api_key":"...","user_id":"USR-5678"}

{"success":true,"user":{"user_id":"USR-5678","name":"Alicia Gomez","email":"alicia@example.com","created_at":"2024-02-10 10:02:00"}}

`get_all_users`

{"action":"get_all_users","business_id":"BUS-12345","api_key":"...","page":1,"limit":25}

{"success":true,"count":1,"total":1,"users":[{"user_id":"USR-5678","name":"Alicia Gomez","email":"alicia@example.com"}]}

`update_user`

{"action":"update_user","business_id":"BUS-12345","api_key":"...","user_id":"USR-5678","updates":{"name":"Alicia G."}}

{"success":true,"message":"User updated","updated_fields":["name"]}

`create_user`

{"action":"create_user","business_id":"BUS-12345","api_key":"...","user":{"name":"Alicia Gomez","email":"alicia@example.com"}}

{"success":true,"user":{"user_id":"USR-5678"},"wallet":{"wallet_id":"WAL-3456"}}

Cards

Card Management

`get_user_cards`

{"action":"get_user_cards","business_id":"BUS-12345","api_key":"...","user_id":"USR-5678"}

{"success":true,"cards":[{"gateway":"stripe","brand":"visa","last4":"4242","exp_month":12,"exp_year":2026}]}

`get_user_primary_card`

{"action":"get_user_primary_card","business_id":"BUS-12345","api_key":"...","user_id":"USR-5678"}

{"success":true,"card":{"gateway":"stripe","last4":"4242","exp_month":12,"exp_year":2026}}

`create_stripe_customer`

{"action":"create_stripe_customer","business_id":"BUS-12345","api_key":"...","user_id":"USR-5678","payment_method_token":"pm_123","set_as_primary":true}

{"success":true,"customer_id":"cus_123","card":{"last4":"4242","brand":"visa"}}

`create_authorize_customer`

{"action":"create_authorize_customer","business_id":"BUS-12345","api_key":"...","user_id":"USR-5678","payment_profile":{"card_number":"4111111111111111","exp_month":12,"exp_year":2026,"postal_code":"77001"}}

{"success":true,"customer_profile_id":"123456","payment_profile_id":"654321"}

Payments

Charging Customers

`charge_customer`

{"action":"charge_customer","business_id":"BUS-12345","api_key":"...","user_id":"USR-5678","amount":25.50,"currency":"usd","description":"Single latte"}

{"success":true,"transaction_id":"pi_123","amount":25.50,"currency":"usd","status":"succeeded"}

`fund_customer`

{"action":"fund_customer","business_id":"BUS-12345","api_key":"...","user_id":"USR-5678","amount":50.00,"currency":"usd","description":"Wallet funding"}

{"success":true,"transaction_id":"ch_123","wallet":{"wallet_id":"WAL-3456","balance":150.00}}

`get_payment_records`

{"action":"get_payment_records","business_id":"BUS-12345","api_key":"...","page":1,"limit":25}

{"success":true,"count":1,"total":1,"payments":[{"transaction_id":"pi_123","amount":25.50,"status":"succeeded","created_at":"2024-02-20 14:20:00"}]}

Wallet

Wallet Operations

`get_user_wallet`

{"success":true,"wallet":{"wallet_id":"WAL-3456","user_id":"USR-5678","currency":"usd","balance":115.50,"updated_at":"2024-02-20 14:20:00"}}

`get_wallet_history`

{"success":true,"count":1,"transactions":[{"transaction_id":"WTX-999","type":"credit","amount":40,"source":"stripe","reason":"wallet_fund","description":"Stripe wallet funding","created_at":"2024-02-20 14:20:00"}]}

`charge_wallet`

{"success":true,"wallet_id":"WAL-3456","new_balance":75.50,"type":"debit","source":"system","reason":"business_charge","message":"Wallet updated successfully"}

`add_wallet_funds`

{"success":true,"wallet_id":"WAL-3456","new_balance":155.50,"type":"credit","source":"manual","reason":"manual_credit","message":"Wallet updated successfully"}

Recurring

Subscription Scheduling

`create_recurring`

{"action":"create_recurring","business_id":"BUS-12345","api_key":"...","user_id":"USR-5678","amount":25.00,"interval_type":"month","interval_value":1,"source":"stripe","description":"Monthly latte","start_at":"2024-03-01T08:00:00","timezone":"America/Chicago"}

{"success":true,"message":"Recurring job created successfully","recurring_id":"REC-123","next_run":"2024-04-01 13:00:00","timezone":"America/Chicago"}

`update_recurring`

{"action":"update_recurring","business_id":"BUS-12345","api_key":"...","recurring_id":"REC-123","amount":27.00,"status":"active"}

{"success":true,"message":"Recurring job updated"}

pause_recurring

{"success":true,"message":"Recurring job set to paused"}

resume_recurring

{"success":true,"message":"Recurring job set to active"}

cancel_recurring

{"success":true,"message":"Recurring job set to cancelled"}

`list_recurring` / `get_recurring_logs`

{"success":true,"count":1,"recurring":[{"recurring_id":"REC-123","amount":25,"currency":"usd","interval_type":"month","interval_value":1,"status":"active","next_run":"2024-04-01 13:00:00","last_run":null,"executed_cycles":0,"description":"Monthly latte"}]}

{"success":true,"count":1,"logs":[{"log_id":"LOG-1","status":"succeeded","message":"Charge completed","attempted_at":"2024-03-01 13:00:03","transaction_id":"pi_123"}]}

Errors

Shared Error Responses

Transport & Parsing

405 {"success":false,"error":"Method Not Allowed"} – not POST.
400 {"success":false,"error":"Invalid JSON"} – malformed body.
400 {"success":false,"error":"Missing required fields: business_id and api_key"}

Authentication & Runtime

401 {"success":false,"error":"Invalid business credentials"}
500 {"success":false,"error":"Internal server error","details":"..."}

Nivisco Payment API Documentation

Docs

SDK

API Live Test

Quickstart

API Standards

Transport

Idempotency & Retries

Pagination & Filtering

Security

Action Catalog

Credential Validation

validate_business POST

get_business_info POST

Business Management

register_business

modify_business

change_api_key

Payment Provider Configuration

add_stripe_credentials / modify_stripe_credentials

add_authorize_credentials / modify_authorize_credentials

User Directory

validate_user

get_user_info

get_all_users

update_user

create_user