Transfer between wallets - Natural Docs

Move money instantly between two of your wallets. For the transfer lifecycle, read the Transfers overview.

Move funds

A transfer (trf_*) moves money between two wallets (wal_*) in the same party, landing in the same call; read status on the response. Create one with POST /transfers/internal. Internal transfers need more than one wallet on the party; see Create and manage wallets. An agent can move money into the Vault but not out of it.

import uuid
from naturalpay import Natural

client = Natural()
transfer = client.transfers.initiate_internal(
    amount=5_000,
    source_wallet_id="wal_019cd1798d714ce765e0486a417c23dc",
    dest_wallet_id="wal_019cd1798d72cf01303c7c04148c9b8d",
    description="Sweep to Vault",
    idempotency_key=str(uuid.uuid4()),
)
print(transfer.data.id)

import Natural from "@naturalpay/sdk";

const client = new Natural();
const transfer = await client.transfers.initiateInternal({
  amount: 5_000,
  sourceWalletId: "wal_019cd1798d714ce765e0486a417c23dc",
  destWalletId: "wal_019cd1798d72cf01303c7c04148c9b8d",
  description: "Sweep to Vault",
  idempotencyKey: crypto.randomUUID(),
});
console.log(transfer.data.id);

natural transfers initiate-internal \
  --amount 5000 \
  --source-wallet-id wal_019cd1798d714ce765e0486a417c23dc \
  --dest-wallet-id wal_019cd1798d72cf01303c7c04148c9b8d \
  --description "Sweep to Vault" \
  --idempotency-key "$(uuidgen)"

Move $50 from my operating wallet to my Vault.

curl -X POST https://api.natural.com/transfers/internal \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "amount": 5000,
        "sourceWalletId": "wal_019cd1798d714ce765e0486a417c23dc",
        "destWalletId": "wal_019cd1798d72cf01303c7c04148c9b8d",
        "description": "Sweep to Vault"
      }
    }
  }'

The response carries the transfer (trf_*) and its status: 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.