Deposit and withdraw

Pull money from a linked bank account (eac_*) into a wallet (wal_*) as a transfer (trf_*), or push it back out. For the transfer lifecycle, read the Transfers overview. Natural handles the payment rails, so you can use whichever fits. Any connected agent can move money with an API call, and every transfer is observable and fully auditable.

Link a bank account in the dashboard first. Natural returns an eac_* id you pass on every deposit and withdrawal. The account must be verified and its connection active; otherwise the call returns 409 external_account_not_verified or external_account_connection_login_required.

Deposit into a wallet

Pull money from the bank into a wallet with POST /transfers/deposit. Funds land in your default wallet unless you name another. The minimum deposit is 100 ($1.00), and deposits are capped per day by your tier (deposit_tier_daily_pull_limit_exceeded).

import uuid
from naturalpay import Natural

client = Natural()
deposit = client.transfers.initiate_deposit(
    amount=50_000,
    currency="USD",
    external_account_id="eac_019cd1798d75c7ec27e4218aeac1d282",
    description="Wallet top-up",
    idempotency_key=str(uuid.uuid4()),
)
print(deposit.data.id)

import Natural from "@naturalpay/sdk";

const client = new Natural();
const deposit = await client.transfers.initiateDeposit({
  amount: 50_000,
  currency: "USD",
  externalAccountId: "eac_019cd1798d75c7ec27e4218aeac1d282",
  description: "Wallet top-up",
  idempotencyKey: crypto.randomUUID(),
});
console.log(deposit.data.id);

natural transfers initiate-deposit \
  --amount 50000 \
  --currency USD \
  --external-account-id eac_019cd1798d75c7ec27e4218aeac1d282 \
  --description "Wallet top-up" \
  --idempotency-key "$(uuidgen)"

Deposit $500 into my wallet from my linked bank account.

curl -X POST https://api.natural.com/transfers/deposit \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "amount": 50000,
        "currency": "USD",
        "externalAccountId": "eac_019cd1798d75c7ec27e4218aeac1d282",
        "description": "Wallet top-up"
      }
    }
  }'

The response carries the transfer (trf_*) in PROCESSING: A transfer moves CREATED to PROCESSING to COMPLETED. It can pause at IN_REVIEW during an approval hold. It ends at FAILED, RETURNED, CANCELED, or APPROVAL_DENIED.

Withdraw to a bank account

Push money from a wallet to the bank with POST /transfers/withdraw. Natural pulls from your default wallet unless you name another, and the wallet needs enough available balance to cover it (otherwise 409 insufficient_funds). Withdrawals go out over ACH by default; pass method: "instant" for a realtime withdrawal where your account has access, otherwise the call returns 403 instant_withdrawals_not_enabled.

withdrawal = client.transfers.initiate_withdrawal(
    amount=12_500,
    currency="USD",
    external_account_id="eac_019cd1798d75c7ec27e4218aeac1d282",
    description="Payout transfer",
    idempotency_key=str(uuid.uuid4()),
)
print(withdrawal.data.id)

const withdrawal = await client.transfers.initiateWithdrawal({
  amount: 12_500,
  currency: "USD",
  externalAccountId: "eac_019cd1798d75c7ec27e4218aeac1d282",
  description: "Payout transfer",
  idempotencyKey: crypto.randomUUID(),
});
console.log(withdrawal.data.id);

natural transfers initiate-withdrawal \
  --amount 12500 \
  --currency USD \
  --external-account-id eac_019cd1798d75c7ec27e4218aeac1d282 \
  --description "Payout transfer" \
  --idempotency-key "$(uuidgen)"

Withdraw $125 from my wallet to my linked bank account.

curl -X POST https://api.natural.com/transfers/withdraw \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "amount": 12500,
        "currency": "USD",
        "externalAccountId": "eac_019cd1798d75c7ec27e4218aeac1d282",
        "description": "Payout transfer"
      }
    }
  }'

The response carries the transfer (trf_*) in PROCESSING:

Confirm the balance

Deposits and withdrawals settle asynchronously, so the balance change is not immediate. Read the transfer with GET /transfers/{transferId}: status moves PROCESSING to COMPLETED, and expectedAvailableAt tells you when the funds are usable. Then read the wallet to confirm a deposit landed before you spend against it, or that a withdrawal left. See Create and manage wallets for how balance.available differs from balance.total.

Overview

Common use cases

Guides

Deposit into a wallet

Withdraw to a bank account

Confirm the balance

​Deposit into a wallet

​Withdraw to a bank account

​Confirm the balance

Deposit into a wallet

Withdraw to a bank account

Confirm the balance