The Transfer object

A Transfer object is created when you move funds between Zoneless accounts as part of Connect. Transfers allow platforms to send funds to their connected accounts.

Stripe API equivalent

Create a transfer

POST /v1/transfers

Update a transfer

POST /v1/transfers/:id

Retrieve a transfer

GET /v1/transfers/:id

List all transfers

GET /v1/transfers

Attributes

id string

Unique identifier for the object. Zoneless transfer IDs are prefixed with tr_z_.

object string

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

amount integer

Amount in cents to be transferred.

amount_reversed integer

Amount in cents reversed (can be less than the amount attribute on the transfer if a partial reversal was issued).

balance_transactionnullable string

Balance transaction that describes the impact of this transfer on your account balance.

created timestamp

Time that this record of the transfer was first created. Measured in seconds since the Unix epoch.

currency string

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

Difference from Stripe: Zoneless uses usdc instead of fiat currencies like usd. The amount is still specified in cents (1/100 of a USDC).

descriptionnullable string

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

destination string

ID of the connected account the transfer was sent to.

destination_paymentnullable string

The ID of the payment that the destination account received for the transfer.

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. This can be useful for storing additional information about the object in a structured format.

reversals object

A list of reversals that have been applied to the transfer.

Note: Transfer reversals are not currently implemented in Zoneless. This field is included for API compatibility.

reversed boolean

Whether the transfer has been fully reversed. If the transfer is only partially reversed, this attribute will still be false.

source_transactionnullable string

ID of the charge that was used to fund the transfer. If null, the transfer was funded from the available balance.

source_type enum

The source balance this transfer came from.

Difference from Stripe: Stripe supports card, bank_account, and fpx source types. Zoneless only uses wallet for USDC transfers. The other values are accepted by the API for migration compatibility but should not be used.

Possible enum values

walletFunds from the platform's USDC wallet balance. This is the only functional source type in Zoneless.

transfer_groupnullable string

A string that identifies this transaction as part of a group. Useful for grouping transfers related to the same order or transaction.

More attributes

THE TRANSFER OBJECT

{
  "id": "tr_z_1MiN3gLkdIwHu7ixNCZvFdgA",
  "object": "transfer",
  "amount": 40000,
  "amount_reversed": 0,
  "balance_transaction": "txn_z_1MiN3gLkdIwHu7ixxapQrznl",
  "created": 1678043844,
  "currency": "usdc",
  "description": null,
  "destination": "acct_z_1MTfjCQ9PRzxEwkZ",
  "destination_payment": "py_z_1MiN3gQ9PRzxEwkZWTPGNq9o",
  "livemode": false,
  "metadata": {},
  "platform_account": "acct_z_Platform123abc",
  "reversals": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/transfers/tr_z_1MiN3gLkdIwHu7ixNCZvFdgA/reversals"
  },
  "reversed": false,
  "source_transaction": null,
  "source_type": "wallet",
  "transfer_group": "ORDER_95"
}

Create a transfer

To send funds from your platform account to a connected account, create a new transfer. Your platform balance must have sufficient funds to cover the transfer amount, or you'll receive an "Insufficient Funds" error.

ENDPOINTS

POST /v1/transfers

Parameters

amount integer Required

A positive integer in cents representing how much to transfer.

currency string Required

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

Difference from Stripe: Use usdc instead of fiat currencies.

destination string Required

The ID of a connected Zoneless account. The destination account must belong to your platform.

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 Transfer object if there were no initial errors with the transfer creation (e.g., insufficient funds).

POST/v1/transfers

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

const transfer = await zoneless.transfers.create({
  amount: 40000,
  currency: 'usdc',
  destination: 'acct_z_1MTfjCQ9PRzxEwkZ',
  transfer_group: 'ORDER_95',
});

RESPONSE

{
  "id": "tr_z_1MiN3gLkdIwHu7ixNCZvFdgA",
  "object": "transfer",
  "amount": 40000,
  "amount_reversed": 0,
  "balance_transaction": "txn_z_1MiN3gLkdIwHu7ixxapQrznl",
  "created": 1678043844,
  "currency": "usdc",
  "description": null,
  "destination": "acct_z_1MTfjCQ9PRzxEwkZ",
  "destination_payment": "py_z_1MiN3gQ9PRzxEwkZWTPGNq9o",
  "livemode": false,
  "metadata": {},
  "platform_account": "acct_z_Platform123abc",
  "reversals": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/transfers/tr_z_1MiN3gLkdIwHu7ixNCZvFdgA/reversals"
  },
  "reversed": false,
  "source_transaction": null,
  "source_type": "wallet",
  "transfer_group": "ORDER_95"
}

Update a transfer

Updates the specified transfer by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

ENDPOINTS

POST /v1/transfers/:id

Parameters

description string

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

metadata object

Returns

Returns the Transfer object if the update succeeded. This call will raise an error if update parameters are invalid.

POST/v1/transfers/:id

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

const transfer = await zoneless.transfers.update(
  'tr_z_1MiN3gLkdIwHu7ixNCZvFdgA',
  {
    metadata: {
      order_id: '6735',
    },
  }
);

RESPONSE

{
  "id": "tr_z_1MiN3gLkdIwHu7ixNCZvFdgA",
  "object": "transfer",
  "amount": 40000,
  "amount_reversed": 0,
  "balance_transaction": "txn_z_1MiN3gLkdIwHu7ixxapQrznl",
  "created": 1678043844,
  "currency": "usdc",
  "description": null,
  "destination": "acct_z_1MTfjCQ9PRzxEwkZ",
  "destination_payment": "py_z_1MiN3gQ9PRzxEwkZWTPGNq9o",
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "platform_account": "acct_z_Platform123abc",
  "reversals": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/transfers/tr_z_1MiN3gLkdIwHu7ixNCZvFdgA/reversals"
  },
  "reversed": false,
  "source_transaction": null,
  "source_type": "wallet",
  "transfer_group": "ORDER_95"
}

Retrieve a transfer

Retrieves the details of an existing transfer. Supply the unique transfer ID from either a transfer creation request or the transfer list, and Zoneless will return the corresponding transfer information.

ENDPOINTS

GET /v1/transfers/:id

Parameters

No parameters.

Returns

Returns a Transfer object if a valid identifier was provided, and raises an error otherwise.

GET/v1/transfers/:id

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

const transfer = await zoneless.transfers.retrieve(
  'tr_z_1MiN3gLkdIwHu7ixNCZvFdgA'
);

RESPONSE

{
  "id": "tr_z_1MiN3gLkdIwHu7ixNCZvFdgA",
  "object": "transfer",
  "amount": 40000,
  "amount_reversed": 0,
  "balance_transaction": "txn_z_1MiN3gLkdIwHu7ixxapQrznl",
  "created": 1678043844,
  "currency": "usdc",
  "description": null,
  "destination": "acct_z_1MTfjCQ9PRzxEwkZ",
  "destination_payment": "py_z_1MiN3gQ9PRzxEwkZWTPGNq9o",
  "livemode": false,
  "metadata": {},
  "platform_account": "acct_z_Platform123abc",
  "reversals": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/transfers/tr_z_1MiN3gLkdIwHu7ixNCZvFdgA/reversals"
  },
  "reversed": false,
  "source_transaction": null,
  "source_type": "wallet",
  "transfer_group": "ORDER_95"
}

List all transfers

Returns a list of existing transfers sent to connected accounts. The transfers are returned in sorted order, with the most recently created transfers appearing first.

ENDPOINTS

GET /v1/transfers

Parameters

destination string

Only return transfers for the destination specified by this account ID.

transfer_group string

Only return transfers with the specified transfer group.

More attributes

Returns

A dictionary with a data property that contains an array of up to limit transfers, starting after transfer starting_after. Each entry in the array is a separate Transfer object. If no more transfers are available, the resulting array will be empty.

GET/v1/transfers

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

const transfers = await zoneless.transfers.list({
  limit: 3,
});

RESPONSE

{
  "object": "list",
  "url": "/v1/transfers",
  "has_more": false,
  "data": [
    {
      "id": "tr_z_1MiN3gLkdIwHu7ixNCZvFdgA",
      "object": "transfer",
      "amount": 40000,
      "amount_reversed": 0,
      "balance_transaction": "txn_z_1MiN3gLkdIwHu7ixxapQrznl",
      "created": 1678043844,
      "currency": "usdc",
      "description": null,
      "destination": "acct_z_1MTfjCQ9PRzxEwkZ",
      "destination_payment": "py_z_1MiN3gQ9PRzxEwkZWTPGNq9o",
      "livemode": false,
      "metadata": {},
      "platform_account": "acct_z_Platform123abc",
      "reversals": {
        "object": "list",
        "data": [],
        "has_more": false,
        "url": "/v1/transfers/tr_z_1MiN3gLkdIwHu7ixNCZvFdgA/reversals"
      },
      "reversed": false,
      "source_transaction": null,
      "source_type": "wallet",
      "transfer_group": "ORDER_95"
    }
  ]
}