Nixo REST API · v1

Nixo API – Overview & first call

The Nixo API lets you move money across borders, create accounts, and listen to real-time payout events. This page covers authentication, environments, and your first payout call.

Sandbox & production environments

Secret keys per environment

Designed for global transfers

Base URLs: https://api.sandbox.nixo.top · https://api.nixo.top


  1
  # List your recent payouts in sandbox


  2
  curl -X GET "https://api.sandbox.nixo.top/v1/payouts?limit=5" \


  3
    -H "Authorization: Bearer <YOUR_SANDBOX_SECRET_KEY>" \


  4
    -H "Nixo-Version: 2025-01-01"


  1
  // npm install @nixo/finance


  2
  import { NixoClient } from '@nixo/finance';


  3
  const client = new NixoClient({


  4
    apiKey: process.env.NIXO_SANDBOX_KEY,


  5
    environment: 'sandbox',


  6
  });


  7
  const payouts = await client.payouts.list({ limit: 5 });


  8
  console.log(payouts.data[0]);


  1
  # pip install nixo-finance


  2
  from nixo import NixoClient


  3
  client = NixoClient(


  4
      api_key="<YOUR_SANDBOX_SECRET_KEY>",


  5
      environment="sandbox",


  6
  )


  7
  payouts = client.payouts.list(limit=5)


  8
  print(payouts["data"][0])

Use your sandbox secret key for all examples on this page. Production keys should only be used on secure backend servers, never in client-side code.

Authentication

Nixo uses secret API keys and bearer tokens to authenticate requests. All requests must be made over HTTPS and include an Authorization header.

Header	Required	Example value	Description
`Authorization`	Yes	`Bearer sk_sandbox_123...`	Your secret API key. Use sandbox keys for testing.
`Nixo-Version`	Recommended	`2025-01-01`	Pin requests to an API version for predictable responses.
`Idempotency-Key`	Recommended	`request-uuid-123`	Unique string to safely retry POST requests.

Never expose secret keys in mobile apps, browsers, or public repositories. Rotate keys regularly from the Nixo dashboard.

Your first payout

Let’s create a sandbox payout from your business account to a recipient bank account. In production, the same call moves real money.


  1
  POST /v1/payouts # Create payout


  2
  {


  3
    "amount": 250.00,


  4
    "currency": "USD",


  5
    "destination_country": "MA",


  6
    "recipient": {


  7
      "full_name": "Test User",


  8
      "account_iban": "MA640001234567890123456789"


  9
    },


  10
    "reference": "invoice_9485",


  11
    "metadata": { "source": "demo-docs" }


  12
  }

If successful, you’ll receive a JSON response with a payout id, initial status (for example "processing"), and timestamps. You can track status via the Payouts API or via webhooks.

Payouts API

The Payouts API lets you create, list, and track cross-border payouts. You’ll typically use it together with webhooks for status updates.

Endpoint	Method	Description
`POST /v1/payouts`	`POST`	Create a new payout.
`GET /v1/payouts`	`GET`	List payouts with pagination and filters.
`GET /v1/payouts/{id}`	`GET`	Retrieve a single payout by ID.

Use Idempotency-Key when creating payouts. If your integration retries the same request, Nixo will safely return the original payout instead of creating a duplicate.

Accounts & balances

Nixo accounts represent end customers or internal wallets. Balances are tracked per currency and can be used as funding sources for payouts.

Endpoint	Method	Description
`POST /v1/accounts`	`POST`	Create a customer or business account.
`GET /v1/accounts/{id}`	`GET`	Retrieve account details and KYC state.
`GET /v1/accounts/{id}/balances`	`GET`	List balances for a given account.

For most integrations, you’ll create at least one “operating” account that receives inflows and funds payouts initiated via the Payouts API.

Webhooks

Webhooks let Nixo notify your backend when important events occur, such as payout status changes or balance updates.

Event type	When it fires
`payout.created`	Right after a payout is accepted for processing.
`payout.succeeded`	Funds have been delivered to the recipient.
`payout.failed`	The payout could not be completed (for example, invalid account).
`balance.updated`	Account balances changed due to payouts or incoming transfers.

Webhook requests include a signature header (for example, Nixo-Signature). You should verify this signature using the webhook secret from your dashboard to ensure requests are from Nixo.

Error handling

Nixo uses standard HTTP status codes and returns JSON error bodies with a code, a human-readable message, and an optional field.

Status	Type	Example
`400`	Validation error	`invalid_request`
`401`	Auth error	`invalid_api_key`
`403`	Permission error	`permission_denied`
`429`	Rate limit	`rate_limit_exceeded`
`500+`	Server	`internal_error`


  1
  {


  2
    "error": {


  3
      "code": "invalid_request",


  4
      "message": "amount must be greater than 0",


  5
      "field": "amount"


  6
    }


  7
  }

We recommend treating 5xx and network failures as retriable errors, using exponential backoff and Idempotency-Key for POST calls.