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.
| Action | Endpoint |
|---|---|
| Create a deposit account | POST /api/v1/customers/{customer_uuid}/deposit_accounts |
| Retrieve a deposit account | GET /api/v1/deposit_accounts/{deposit_account_id} |
| List deposit accounts | GET /api/v1/customers/{customer_uuid}/deposit_accounts |
| Update a deposit account | PATCH /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 blockchainaddressor a Harborwallet. 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.activatedanddeposit_account.failed, or todeposit_account.*. See Subscribable Events. - Or retrieve the account until the
statusisactive.
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.createdwebhook has the transfer, and itsorigin.customer_deposit_account_idis 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}hasmeta_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_startorexpired, because the payment is already received. - Starts on hold: it starts as
on_holdwhile 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_informationmeans Harbor needs a liveness check from the Customer, or documents. See Transfer RFI. - No sub-status: the
sub_statusstaysnull. - Payout: on Ethereum, Arbitrum, Polygon, Base, Optimism, Avalanche and Arc, the transfer goes through
pending_externalwhile the payout is confirmed. On Solana and Stellar, it goes straight tocompleted.
%%{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, thenrefundedonce the USD is returned.
How long a refund takes depends on the payment method:
| Payment method | Time |
|---|---|
WIRE | Same day or the next business day for a full refund. Otherwise 1 to 3 business days. |
ACH_PUSH | 1 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.
Close the bank account. This can't be undone:
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 '{
"status": "disabled"
}'{
"data": {
"id": "depacc_1234567890",
"object": "customer_deposit_account",
"status": "disabled",
...
}
}- To start again, create a new deposit account.
- A deposit that still arrives isn't converted. No transfer is created, and OwlPay Support handles the return.
- After you disable it, you can't change the destination, and
simulate_paymentreturns422.
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_holdandtransfer.status.pending_harbor, about a second apart. Each has theoriginof the deposit account. - Finish the transfer: use Simulate Transfer Status.
- Micro-deposit: an
ACH_PUSHunder USD 1.00 isn't a deposit. No transfer is created, and Harbor sendsbank_account.micro_deposit.received. See Micro-Deposit Verification.
Deposit Account Fees
What a deposit account costs.
- Commission: the
commissionyou 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.
| Code | Meaning |
|---|---|
9805 | No deposit account fee is set for your application. Ask your Account Manager. |
2005 | The request is invalid. For example, beneficiary_info is missing or not allowed, or the account isn't active. Check errors. |
2001 | The 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.
Updated about 14 hours ago