Deposit and withdraw

Move money between a linked bank account and your Natural wallet. A deposit pulls funds in, a withdrawal pushes funds out. Both settle asynchronously.

Link a bank account in the dashboard first. Natural connects it through Plaid and returns an eac_ id you pass on every deposit and withdrawal. Working with a customer’s bank account instead? See Link a customer’s bank account.

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.

import uuid
from naturalpay import Natural

client = Natural()
deposit = client.transfers.initiate_deposit(
    amount=50_000,
    currency="USD",
    external_account_id="eac_550e8400e29b41d4a716446655440000",
    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_550e8400e29b41d4a716446655440000",
  description: "Wallet top-up",
  idempotencyKey: crypto.randomUUID(),
});
console.log(deposit.data.id);

natural transfers initiateDeposit \
  --amount 50000 \
  --currency USD \
  --external-account-id eac_550e8400e29b41d4a716446655440000 \
  --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_550e8400e29b41d4a716446655440000",
        "description": "Wallet top-up"
      }
    }
  }'

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.

withdrawal = client.transfers.initiate_withdrawal(
    amount=12_500,
    currency="USD",
    external_account_id="eac_550e8400e29b41d4a716446655440000",
    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_550e8400e29b41d4a716446655440000",
  description: "Payout transfer",
  idempotencyKey: crypto.randomUUID(),
});
console.log(withdrawal.data.id);

natural transfers initiateWithdrawal \
  --amount 12500 \
  --currency USD \
  --external-account-id eac_550e8400e29b41d4a716446655440000 \
  --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_550e8400e29b41d4a716446655440000",
        "description": "Payout transfer"
      }
    }
  }'

Confirm the balance

Deposits and withdrawals settle over a few business days, so the balance change is not immediate. Read the wallet to confirm a deposit landed before you spend against it, or that a withdrawal left. See 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