Deposit Accounts

Give a verified Customer a dedicated USD bank account that converts deposits to USDC automatically.

Dedicated USD bank accounts for verified Customers, converted to USDC automatically.

ActionEndpoint
Create a deposit accountPOST /api/v1/customers/{customer_uuid}/deposit_accounts
Retrieve a deposit accountGET /api/v1/deposit_accounts/{deposit_account_id}
List deposit accountsGET /api/v1/customers/{customer_uuid}/deposit_accounts
Update a deposit accountPATCH /api/v1/deposit_accounts/{deposit_account_id}
Simulate a payment (Sandbox)POST /api/v1/deposit_accounts/{deposit_account_id}/simulate_payment

How It Works

A Deposit Account is a dedicated virtual USD bank account for one verified Customer. When money arrives by wire or ACH Push, Harbor converts it to USDC and sends it to the destination you set. The account is reusable, and the payer doesn't need a reference.

Harbor doesn't hold a fiat balance. Every deposit is converted and sent on.

  • You create a deposit account for a verified Customer. It starts as provisioning.
  • When it's active, it returns the bank details, deposit_instructions.
  • The payer sends USD by wire or ACH Push to those details.
  • Harbor creates an on-ramp transfer, converts the USD to USDC, and sends it to the destination.

The account stays active for future deposits, until you disable it.

Use Cases

Common uses for a deposit account.

  • B2B pay-in: US businesses or merchants settle in fiat. The payer deposits into the dedicated account, and the platform receives USDC on-chain.
  • Payroll and regular payments: one account per employee. The company sends a wire or ACH, and Harbor converts it to USDC and sends it to the employee's wallet.
  • Recurring wallet funding: users get their own account and routing number. They can set up recurring transfers from their bank app to fund a wallet with USDC.
  • Brokerage and exchanges: users send fiat from their bank, and it becomes USDC in their trading account without a checkout flow.

For one-off payments, see Deposit Accounts vs. Quote-Based Transfers.

Eligibility

Which Customers can get a deposit account.

  • Businesses: any verified business. A business has no level.
  • Individuals: Level 2 or Level 3. Level 1 can't, because it only allows debit card.
  • Location: verified US Customers. For other countries, contact your Account Manager.
  • Applications with delegated KYC: not available.

For levels, see Customer Levels.

Create Deposit Account

What to send when you create the account.

POST /api/v1/customers/{customer_uuid}/deposit_accounts

  • source_country: US.
  • destination: where the USDC goes, a blockchain address or a Harbor wallet. USDC is the only asset.
  • destination.transfer_purpose: the reason for the deposits. See Transfer Purpose.
  • commission (optional): your fee, taken from each deposit. See Commission.
  • application_reference_id (optional): your own reference.

Set transfer_purpose to TRANSFER_TO_OWN_ACCOUNT and is_self_transfer to true. Don't send beneficiary_info. Harbor uses the Customer's verified identity, and rejects the request if you send it.

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v1/customers/{{CUSTOMER_UUID}}/deposit_accounts' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{Idempotency-Key}}' \
--data-raw '{
    "source_country": "US",
    "destination": {
        "type": "external_address",
        "asset": "USDC",
        "chain": "ethereum",
        "address": "0x76da4165da3d87b0dfcfeb867a31a0d7ab9884a5",
        "is_self_transfer": true,
        "transfer_purpose": "TRANSFER_TO_OWN_ACCOUNT",
        "beneficiary_receiving_wallet_type": "non_custodial",
        "beneficiary_institution_name": "Self-hosted wallet"
    }
}'

The response is 202, and the status is provisioning. The account becomes active within a few seconds.

Deposit Account Instructions

How to know when the bank details are ready.

  • Subscribe to deposit_account.activated and deposit_account.failed, or to deposit_account.*. See Subscribable Events.
  • Or retrieve the account until the status is active.

GET /api/v1/deposit_accounts/{deposit_account_id}

{
    "data": {
        "id": "depacc_1234567890",
        "object": "customer_deposit_account",
        "customer_id": "cus_1234567890",
        "source_country": "US",
        "status": "active",
        "deposit_instructions": {
            "bank_name": "Cross River Bank",
            "bank_address": "Cross River Bank, 885 Teaneck Rd, Teaneck, NJ 07666",
            "account_number": "318890158138",
            "routing_number": "021214891",
            "account_holder_name": "Acme US Inc"
        },
        "commission": { "percentage": 0, "amount": 0 }
    }
}

The payer sends the wire or ACH Push to these details. The beneficiary name is the account_holder_name, which is the Customer's legal name.

Deposit Account Transfers

What happens when a deposit arrives.

  • Transfer: Harbor creates an on-ramp transfer, then runs the compliance checks. The transfer.deposit.created webhook has the transfer, and its origin.customer_deposit_account_id is the deposit account.
  • Payout: the USDC goes to the destination, a blockchain address or a Harbor wallet, as an on-chain transfer. The receipt has the transaction_hash. See Transfer Status.
  • Find the account later: GET /api/v2/transfers/{transfer_uuid} has meta_data.deposit_account_uuid.
  • Payer: the payer's name doesn't need to match the Customer. A third party can pay in.
  • Timing: a wire usually arrives in minutes to a few hours on banking days. ACH Push takes 1 to 3 business days to post.
  • Micro-deposits: an ACH Push under USD 1.00 isn't converted. It's an account check. See Micro-Deposit Verification.

To follow the payment details, call:

GET /api/v2/transfers/{transfer_uuid}/payments

Deposit Account Transfer Status

A deposit transfer is created after the money arrives, so its status flow differs from a regular on-ramp transfer.

  • No waiting for payment: it never has pending_customer_transfer_start or expired, because the payment is already received.
  • Starts on hold: it starts as on_hold while Harbor runs the compliance checks. A low-risk deposit usually clears within a couple of minutes, and a flagged one waits for a review. In Sandbox, the checks are skipped and it moves on at once.
  • More information: request_for_information means Harbor needs a liveness check from the Customer, or documents. See Transfer RFI.
  • No sub-status: the sub_status stays null.
  • Payout: on Ethereum, Arbitrum, Polygon, Base, Optimism, Avalanche and Arc, the transfer goes through pending_external while the payout is confirmed. On Solana and Stellar, it goes straight to completed.
%%{init: {"flowchart": {"curve": "monotoneY"}, "state": {"curve": "monotoneY", "useMaxWidth": false}}}%%
stateDiagram-v2
    state "Deposit received" as deposit
    [*] --> deposit
    deposit --> on_hold: Transfer created
    on_hold --> pending_harbor: Approved
    on_hold --> request_for_information: More info needed
    request_for_information --> on_hold: Liveness check done
    request_for_information --> pending_harbor: Approved
    on_hold --> reject: Declined
    request_for_information --> reject: Declined
    reject --> refunded: USD returned
    pending_harbor --> pending_external: EVM chains
    pending_harbor --> completed: Solana, Stellar
    pending_external --> completed
    classDef success fill:#d1fae5,stroke:#059669,color:#065f46
    class completed success
    classDef failure fill:#fee2e2,stroke:#dc2626,color:#991b1b
    class reject,refunded failure
    classDef warning fill:#fef3c7,stroke:#d97706,color:#92400e
    class on_hold,request_for_information warning
    classDef step fill:#f3f4f6,stroke:#9ca3af,stroke-dasharray:4 4,color:#4b5563
    class deposit step

For what each status means, see Status Definitions.

Deposit Account Refunds

What happens when a deposit can't be converted.

  • Who handles it: OwlPay Support handles every refund. You can't request one through the API.
  • Where it goes: the USD goes back to the payer's bank account, not to a wallet.
  • When: a declined deposit becomes reject, then refunded once the USD is returned.

How long a refund takes depends on the payment method:

Payment methodTime
WIRESame day or the next business day for a full refund. Otherwise 1 to 3 business days.
ACH_PUSH1 to 3 business days, usually 2

To follow a refund, call:

GET /api/v2/transfers/{transfer_uuid}/refunds

{
    "data": [
        {
            "id": 1,
            "refund_type": "full",
            "status": "completed",
            "currency": "USD",
            "amount": "1000.00",
            "bank_name": "Bank of America",
            "account_holder_name": "John Doe",
            "tracking_number": "20260909MMQFMPU8000123",
            "omad": "20260909B1QGC03R000456",
            "reason": "Declined by compliance",
            "requested_at": "2026-09-08T00:00:00+00:00",
            "completed_at": "2026-09-09T00:00:00+00:00"
        }
    ]
}

A deposit to a disabled or deleted account creates no transfer. OwlPay Support returns the money to the payer.

Update Deposit Account

How to change the destination, or close the account.

PATCH /api/v1/deposit_accounts/{deposit_account_id}

Send a new destination. It only works while the account is active. For example, to send the USDC to Arbitrum instead of Ethereum:

curl --location --request PATCH 'https://harbor-sandbox.owlpay.com/api/v1/deposit_accounts/{{DEPOSIT_ACCOUNT_ID}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--data-raw '{
    "destination": {
        "type": "external_address",
        "asset": "USDC",
        "chain": "arbitrum",
        "address": "0x567890abcdef1234567890abcdef1234567890ab",
        "is_self_transfer": true,
        "transfer_purpose": "TRANSFER_TO_OWN_ACCOUNT",
        "beneficiary_receiving_wallet_type": "non_custodial",
        "beneficiary_institution_name": "Self-hosted wallet"
    }
}'

The response is the updated account. A deposit uses the destination that was active when it arrived.

Sandbox Testing

How to try a deposit without a real payment.

POST /api/v1/deposit_accounts/{deposit_account_id}/simulate_payment

{
    "amount": 1000,
    "method": "WIRE",
    "sender_name": "John Doe"
}

method is WIRE or ACH_PUSH. The response is 202, and Harbor creates the transfer as for a real deposit.

  • Webhooks: the transfer sends transfer.deposit.created, transfer.status.on_hold and transfer.status.pending_harbor, about a second apart. Each has the origin of the deposit account.
  • Finish the transfer: use Simulate Transfer Status.
  • Micro-deposit: an ACH_PUSH under USD 1.00 isn't a deposit. No transfer is created, and Harbor sends bank_account.micro_deposit.received. See Micro-Deposit Verification.

Deposit Account Fees

What a deposit account costs.

  • Commission: the commission you set on the account comes out of each deposit.
  • Harbor fee: billed on the monthly statement, as for any on-ramp transfer.
  • Account fees: a one-time setup fee per account, and a monthly maintenance fee for each account. Both are billed on the monthly statement, not taken from the deposit, and they are set in your agreement. A month's maintenance fee isn't prorated, including the month you disable the account.

Before you can create a deposit account, your Account Manager sets up the account fees. Until then, the request returns error 9805.

Errors

What the errors mean.

CodeMeaning
9805No deposit account fee is set for your application. Ask your Account Manager.
2005The request is invalid. For example, beneficiary_info is missing or not allowed, or the account isn't active. Check errors.
2001The Customer or the deposit account doesn't exist.

For the full list, see Error Codes.


Notes

  • Limits: the Customer's limits apply to deposits. See Transfer Limits.
  • Compliance: for a payer who isn't the Customer, and a deposit of USD 3,000 or more, the Travel Rule applies. Harbor uses the beneficiary details you gave when you created the account.
  • Holds and returns: a deposit can be put on hold for compliance. If it's rejected, the USD goes back to the sender. A wire return takes about a day, and an ACH return 2 to 3 business days.
  • ACH returns after payout: if the payer's bank returns an ACH Push after the USDC was sent, the USDC can't be taken back. OwlPay Support follows up with you.
  • Deactivated Customers: their deposit accounts are disabled. A deposit that still arrives creates a transfer that stays on_hold, and no USDC is sent.
  • Number of accounts: there is no limit on the accounts per Customer.

Did this page help you?