Skip to content
Last updated

Transfers Guide

This guide explains how to move funds with the Customer API. It covers:

  • Internal book transfers between bank accounts
  • USDC transfers to cryptocurrency addresses

Prerequisites

  • A Meow account with enabled bank accounts
  • API key permissions:
    • Book transfers: accounts:read and transfers:book:write
    • USDC transfers: accounts:read, accounts:payment-networks, and transfers:usdc:write
  • A cryptocurrency contact for USDC transfers (see Cryptocurrency Contact Management Guide)

Authentication Overview

The headers you send depend on the type of API key:

  • Entity API keys scope all requests to a single entity. No x-entity-id header is required and you can only move funds between accounts that belong to that entity.
  • Global API keys can access multiple entities, but every request must include an x-entity-id header that identifies the source entity for the request. Use GET /v1/api-keys/accessible-entities to discover which entities you can access. When booking transfers, the destination account can belong to any other entity you have access to, as long as the accounts remain compatible.

Tip: Regardless of the key type, book transfers can only be created between accounts that share the same bankProductType.

Book Transfers

Book transfers move funds internally between two accounts you control. The source account is chosen by the path parameter, and the destination is provided in the request body.

Workflow with Entity API Keys

  1. List accounts to find eligible source and destination accounts:

    curl -X GET "https://api.meow.com/v1/accounts" \
  -H "x-api-key: YOUR_ENTITY_API_KEY"

    Record each account’s accountId and bankProductType. You must choose a destination account with the same bankProductType as the source.

  2. Create the book transfer:

    curl -X POST "https://api.meow.com/v1/accounts/{source_account_id}/book" \
  -H "x-api-key: YOUR_ENTITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "250.00",
    "to_account_id": "63fe8c62-58db-4a48-a42d-625b79a7f3fe",
    "idempotency_key": "book-transfer-20240318-001",
    "description": "Move excess cash to interest account"
  }'

    Replace {source_account_id} and to_account_id with the account IDs you gathered. The idempotency_key must be unique per transfer attempt.

    Example response:

    {
  "id": "bt_9f0a6c32",
  "amount": "250.00",
  "description": "Move excess cash to interest account",
  "created_time": 1718132817,
  "transfer_type": "BOOK",
  "to_account_id": "63fe8c62-58db-4a48-a42d-625b79a7f3fe"
}

Workflow with Global API Keys

  1. Discover accessible entities:

    curl -X GET "https://api.meow.com/v1/api-keys/accessible-entities" \
  -H "x-api-key: YOUR_GLOBAL_API_KEY"

    Use the returned IDs to decide which entity you are operating on.

  2. List accounts for a specific entity:

    curl -X GET "https://api.meow.com/v1/accounts" \
  -H "x-api-key: YOUR_GLOBAL_API_KEY" \
  -H "x-entity-id: ENTITY_ID"

    Locate source accounts within the selected entity that share the same bankProductType as potential destination accounts. Repeat this call for each entity you have access to so you can identify compatible cross-entity pairs.

  3. Create the book transfer using the source entity header:

    curl -X POST "https://api.meow.com/v1/accounts/{source_account_id}/book" \
  -H "x-api-key: YOUR_GLOBAL_API_KEY" \
  -H "x-entity-id: ENTITY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500.00",
    "to_account_id": "9de5402c-493d-419e-afce-87d2c02e8d09",
    "idempotency_key": "bt-entity-456-20240318",
    "description": "Sweep to payroll"
  }'

    The x-entity-id value must match the source account’s entity. As long as you have access, the destination account can belong to a different entity that shares the same bankProductType.

Book Transfer Tips

  • Pick a fresh idempotency_key for each attempt so retries do not create duplicate transfers.
  • Verify both accounts are active, denominated in the same currency, and share a bankProductType even when they belong to different entities.
  • Transfers fail if the destination account’s bankProductType differs from the source.
  • API-based transfers are blocked when Security Policy Spend controls are enabled for the entity; adjust the policy or rely on the dashboard instead.

USDC Transfers

USDC transfers send funds from a checking account to a cryptocurrency contact.

Step 1: List Accounts

curl -X GET "https://api.meow.com/v1/accounts" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-entity-id: ENTITY_ID_IF_GLOBAL"

Example response:

{
  "accounts": [
    {
      "depositAccount": {
        "accountId": "acct_123456789",
        "accountType": "CHECKING",
        "productName": "Business Checking",
        "bankProductType": "Grasshopper",
        "status": "OPEN",
        "currency": {
          "currencyCode": "USD"
        },
        "accountNumberDisplay": "1234"
      }
    }
  ]
}

Step 2: Verify USDC Support

curl -X GET "https://api.meow.com/v1/accounts/{account_id}/payment-networks" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-entity-id: ENTITY_ID_IF_GLOBAL"

Look for payment networks with "type": "USDC" and "transferOut": true to confirm the account can originate USDC transfers on the listed blockchains.

Step 3: Create the USDC Transaction

curl -X POST "https://api.meow.com/v1/accounts/{account_id}/usdc" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-entity-id: ENTITY_ID_IF_GLOBAL" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "static_memo_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "internal_note": "Payment for treats",
    "emails": ["simba@tiger.com"]
  }'

Example response:

{
  "id": "tx_987654321",
  "status": "processing",
  "amount": "100.00",
  "internal_note": "Payment for treats",
  "created_time": 1634567890,
  "transaction_type": "USDC",
  "destination_address": "0x1234567890abcdef1234567890abcdef12345678",
  "destination_payment_rail": "ethereum",
  "destination_address_nickname": "Vendor Wallet"
}

Transaction Status

Possible statuses after submission:

  • pending – Awaiting processing
  • processing – In progress
  • sent – Successfully transmitted to the blockchain
  • error – Encountered an issue
  • canceled – Canceled by the user or system
  • void – Reversed before settlement

Best Practices

  • Verify recipients: Confirm cryptocurrency addresses and contact static memos before initiating transfers.
  • Use meaningful references: Populate description (book transfers) or internal_note (USDC transfers) with reconciliation-friendly values.
  • Start small: Send a nominal amount when onboarding a new recipient.
  • Protect secrets: Keep API keys and transaction data out of unsecured channels.
  • Monitor statuses: Follow up with support if a transfer remains in error.

Support

If you need help or have questions:

  • Email: support@meow.com
  • Support Portal: https://support.meow.com
  • API Status: https://status.meow.com
Previous page
Next page