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.

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

Products

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