Docs
GitHubDiscord

The Top-up object

To top up your Zoneless balance, you send USDC to your platform's Solana wallet. Once the funds are detected on the blockchain, a top-up object is created and your balance is increased. You can retrieve individual top-ups, as well as list all top-ups. Top-ups are identified by a unique, random ID.

Stripe API equivalent
Create a top-up
POST /v1/topups
Update a top-up
POST /v1/topups/:id
Retrieve a top-up
GET /v1/topups/:id
List all top-ups
GET /v1/topups
Cancel a top-up
POST /v1/topups/:id/cancel
Check for deposits
POST /v1/topups/check-deposits

Attributes

id string

Unique identifier for the object. Zoneless top-up IDs are prefixed with tu_z_.

object string

String representing the object's type. Objects of the same type share the same value.

amount integer

Amount transferred in the smallest currency unit. For USDC, this is cents (e.g., 100 = $1 USDC).

balance_transactionnullable string

ID of the balance transaction that describes the impact of this top-up on your account balance. May not be specified depending on status of top-up.

created timestamp

Time at which the object was created. Measured in seconds since the Unix epoch.

currency string

Three-letter currency code, in lowercase. For Zoneless, this is typically usdc.

Difference from Stripe: Uses usdc instead of fiat currency codes like usd.

descriptionnullable string

An arbitrary string attached to the object. Often useful for displaying to users.

expected_availability_datenullable timestamp

Date the funds are expected to arrive in your Zoneless account. May not be specified depending on status of top-up.

Difference from Stripe: USDC deposits on Solana are typically available immediately after blockchain confirmation, unlike traditional bank transfers.

failure_codenullable string

Error code explaining reason for top-up failure if available.

failure_messagenullable string

Message to user further explaining reason for top-up failure if available.

livemode boolean

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadata object

Set of key-value pairs that you can attach to an object. For blockchain deposits, this automatically includes blockchain_tx, network, and sender_address.

sourcenullable object

Information about the funding source for this top-up.

Difference from Stripe: Zoneless uses a simplified source object with type crypto_deposit for blockchain deposits.

statement_descriptornullable string

Extra information about a top-up. Limited to 15 ASCII characters.

Difference from Stripe: Unlike bank transfers, Solana USDC transactions do not display statement descriptors. This field is retained for API compatibility.

status enum

The status of the top-up.

Possible enum values
canceledThe top-up was canceled before funds arrived.
failedThe top-up failed to process.
pendingThe top-up is waiting for funds to arrive.
reversedThe top-up was reversed.
succeededFunds have arrived and are available.
transfer_groupnullable string

A string that identifies this top-up as part of a group.

More attributes

THE TOP-UP OBJECT
{
  "id": "tu_z_1NG6yj2eZvKYlo2C1FOBiHya",
  "object": "topup",
  "amount": 200000,
  "balance_transaction": "txn_z_1NG6yjLkdIwHu7ixNCZvFdgB",
  "created": 1704067200,
  "currency": "usdc",
  "description": "Deposit from 8xK2Nv3F...",
  "expected_availability_date": 1704067200,
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
    "blockchain_tx": "5xK9...abc123",
    "network": "solana",
    "sender_address": "8xK2Nv3F..."
  },
  "platform_account": "acct_z_Platform123abc",
  "source": {
    "id": "src_z_1NG6yjLkdIwHu7ixNCZvFdgC",
    "object": "source",
    "type": "crypto_deposit",
    "metadata": {}
  },
  "statement_descriptor": null,
  "status": "succeeded",
  "transfer_group": null,
  "account": "acct_z_Platform123abc",
  "arrival_date": 1704067200
}

Create a top-up

Creates a new top-up record in pending status. In practice, most top-ups are created automatically when the check-deposits endpoint detects incoming USDC transfers to your platform wallet.

ENDPOINTS
POST /v1/topups

Parameters

amount integer Required

A positive integer representing how much to transfer in the smallest currency unit. For USDC, this is cents (e.g., 100 = $1 USDC).

currency string Required

Three-letter currency code, in lowercase. For Zoneless, use usdc.

Difference from Stripe: Use usdc instead of fiat currencies.

description string

An arbitrary string attached to the object. Often useful for displaying to users.

metadata object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them.

More attributes

Returns

Returns a Top-up object if the call succeeds.

POST/v1/topups
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const topup = await zoneless.topups.create({
  amount: 200000,
  currency: 'usdc',
  description: 'Platform balance top-up',
});
RESPONSE
{
  "id": "tu_z_1NG6yj2eZvKYlo2C1FOBiHya",
  "object": "topup",
  "amount": 200000,
  "balance_transaction": null,
  "created": 1704067200,
  "currency": "usdc",
  "description": "Platform balance top-up",
  "expected_availability_date": 1704067200,
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {},
  "platform_account": "acct_z_Platform123abc",
  "source": null,
  "statement_descriptor": null,
  "status": "pending",
  "transfer_group": null,
  "account": "acct_z_Platform123abc",
  "arrival_date": null
}

Update a top-up

Updates the metadata of a top-up. Other top-up details are not editable by design.

ENDPOINTS
POST /v1/topups/:id

Parameters

description string

An arbitrary string attached to the object. Often useful for displaying to users.

metadata object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

Returns

Returns the updated Top-up object if the call succeeds. If the top-up ID does not exist, this call raises an error.

POST/v1/topups/:id
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const topup = await zoneless.topups.update(
  'tu_z_1NG6yj2eZvKYlo2C1FOBiHya',
  {
    description: 'Q1 2024 operating funds',
    metadata: {
      order_id: '6735',
    },
  }
);
RESPONSE
{
  "id": "tu_z_1NG6yj2eZvKYlo2C1FOBiHya",
  "object": "topup",
  "amount": 200000,
  "balance_transaction": "txn_z_1NG6yjLkdIwHu7ixNCZvFdgB",
  "created": 1704067200,
  "currency": "usdc",
  "description": "Q1 2024 operating funds",
  "expected_availability_date": 1704067200,
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
    "blockchain_tx": "5xK9...abc123",
    "network": "solana",
    "sender_address": "8xK2Nv3F...",
    "order_id": "6735"
  },
  "platform_account": "acct_z_Platform123abc",
  "source": {
    "id": "src_z_1NG6yjLkdIwHu7ixNCZvFdgC",
    "object": "source",
    "type": "crypto_deposit",
    "metadata": {}
  },
  "statement_descriptor": null,
  "status": "succeeded",
  "transfer_group": null,
  "account": "acct_z_Platform123abc",
  "arrival_date": 1704067200
}

Retrieve a top-up

Retrieves the details of a top-up that has previously been created. Supply the unique top-up ID that was returned from your previous request, and Zoneless will return the corresponding top-up information.

ENDPOINTS
GET /v1/topups/:id

Parameters

No parameters.

Returns

Returns a Top-up object if a valid identifier was provided, and raises an error otherwise.

GET/v1/topups/:id
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const topup = await zoneless.topups.retrieve(
  'tu_z_1NG6yj2eZvKYlo2C1FOBiHya'
);
RESPONSE
{
  "id": "tu_z_1NG6yj2eZvKYlo2C1FOBiHya",
  "object": "topup",
  "amount": 200000,
  "balance_transaction": "txn_z_1NG6yjLkdIwHu7ixNCZvFdgB",
  "created": 1704067200,
  "currency": "usdc",
  "description": "Deposit from 8xK2Nv3F...",
  "expected_availability_date": 1704067200,
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
    "blockchain_tx": "5xK9...abc123",
    "network": "solana",
    "sender_address": "8xK2Nv3F..."
  },
  "platform_account": "acct_z_Platform123abc",
  "source": {
    "id": "src_z_1NG6yjLkdIwHu7ixNCZvFdgC",
    "object": "source",
    "type": "crypto_deposit",
    "metadata": {}
  },
  "statement_descriptor": null,
  "status": "succeeded",
  "transfer_group": null,
  "account": "acct_z_Platform123abc",
  "arrival_date": 1704067200
}

List all top-ups

Returns a list of top-ups. The top-ups are returned in sorted order, with the most recently created top-ups appearing first.

ENDPOINTS
GET /v1/topups

Parameters

status enum

Only return top-ups that have the given status.

Possible enum values
canceled
failed
pending
reversed
succeeded

More attributes

Returns

A dictionary with a data property that contains an array of up to limit top-ups. If no more top-ups are available, the resulting array will be empty.

GET/v1/topups
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const topups = await zoneless.topups.list({
  limit: 3,
});
RESPONSE
{
  "object": "list",
  "url": "/v1/topups",
  "has_more": false,
  "data": [
    {
      "id": "tu_z_1NG6yj2eZvKYlo2C1FOBiHya",
      "object": "topup",
      "amount": 200000,
      "balance_transaction": "txn_z_1NG6yjLkdIwHu7ixNCZvFdgB",
      "created": 1704067200,
      "currency": "usdc",
      "description": "Deposit from 8xK2Nv3F...",
      "expected_availability_date": 1704067200,
      "failure_code": null,
      "failure_message": null,
      "livemode": false,
      "metadata": {
        "blockchain_tx": "5xK9...abc123",
        "network": "solana",
        "sender_address": "8xK2Nv3F..."
      },
      "platform_account": "acct_z_Platform123abc",
      "source": {
        "id": "src_z_1NG6yjLkdIwHu7ixNCZvFdgC",
        "object": "source",
        "type": "crypto_deposit",
        "metadata": {}
      },
      "statement_descriptor": null,
      "status": "succeeded",
      "transfer_group": null,
      "account": "acct_z_Platform123abc",
      "arrival_date": 1704067200
    }
  ]
}

Cancel a top-up

Cancels a top-up. Only pending top-ups can be canceled.

ENDPOINTS
POST /v1/topups/:id/cancel

Parameters

No parameters.

Returns

Returns the canceled Top-up object. If the top-up is already canceled or can't be canceled, an error is returned.

POST/v1/topups/:id/cancel
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const topup = await zoneless.topups.cancel(
  'tu_z_1NG6yj2eZvKYlo2C1FOBiHya'
);
RESPONSE
{
  "id": "tu_z_1NG6yj2eZvKYlo2C1FOBiHya",
  "object": "topup",
  "amount": 200000,
  "balance_transaction": null,
  "created": 1704067200,
  "currency": "usdc",
  "description": "Platform balance top-up",
  "expected_availability_date": 1704067200,
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {},
  "platform_account": "acct_z_Platform123abc",
  "source": null,
  "statement_descriptor": null,
  "status": "canceled",
  "transfer_group": null,
  "account": "acct_z_Platform123abc",
  "arrival_date": null
}

Check for deposits

Checks the Solana blockchain for new incoming USDC deposits to your platform wallet. This endpoint queries the blockchain for recent USDC transfers and automatically creates top-up records for any new deposits found.

ENDPOINTS
POST /v1/topups/check-deposits

This is the recommended way to detect deposits after a user sends funds. The endpoint checks for new USDC transfers to your platform wallet and creates top-up records with status succeeded for any confirmed transactions.

Parameters

No parameters.

Returns

Returns a result object containing the number of deposits processed, any errors encountered, and an array of newly created Top-up objects.

Response attributes

object string

String representing the object's type. Always check_deposits_result.

processed integer

Number of new deposits successfully processed.

errors integer

Number of errors encountered during processing.

topups array of objects

Array of newly created Top-up objects for the detected deposits.

message string

A human-readable message describing the result.

POST/v1/topups/check-deposits
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const result = await zoneless.topups.checkDeposits();

console.log(`Processed ${result.processed} deposits`);
for (const topup of result.topups) {
  console.log(`New top-up: ${topup.id} - ${topup.amount} USDC`);
}
RESPONSE
{
  "object": "check_deposits_result",
  "processed": 1,
  "errors": 0,
  "topups": [
    {
      "id": "tu_z_1NG6yj2eZvKYlo2C1FOBiHya",
      "object": "topup",
      "amount": 200000,
      "balance_transaction": "txn_z_1NG6yjLkdIwHu7ixNCZvFdgB",
      "created": 1704067200,
      "currency": "usdc",
      "description": "Deposit from 8xK2Nv3F...",
      "expected_availability_date": 1704067200,
      "failure_code": null,
      "failure_message": null,
      "livemode": false,
      "metadata": {
        "blockchain_tx": "5xK9...abc123",
        "network": "solana",
        "sender_address": "8xK2Nv3F...",
        "explorer_url": "https://explorer.solana.com/tx/5xK9...abc123"
      },
      "platform_account": "acct_z_Platform123abc",
      "source": {
        "id": "src_z_1NG6yjLkdIwHu7ixNCZvFdgC",
        "object": "source",
        "type": "crypto_deposit",
        "metadata": {}
      },
      "statement_descriptor": null,
      "status": "succeeded",
      "transfer_group": null,
      "account": "acct_z_Platform123abc",
      "arrival_date": 1704067200
    }
  ],
  "message": "Processed 1 new deposits"
}