On-Ramp (Deposit)
Convert USD to USDC and send it to a wallet.
An on-ramp converts fiat to stablecoins. The Customer pays in USD, and Harbor sends USDC to the recipient's wallet.
On-ramp is only available to Customers in the US. See On-Ramp Coverage.
How It Works
- You get a quote for USD to USDC. It returns an option for each payment method the Customer can use.
- You create the transfer. The wallet that receives the USDC goes in
destination.payout_instrument:- address: any wallet address.
- wallet_uuid: a Harbor wallet.
- The Customer pays in USD:
- Domestic Wire or RTP: they send the USD to the bank account in
transfer_instructions. - Debit Card or ACH Pull: Harbor pulls the USD from their linked card or bank account.
- Domestic Wire or RTP: they send the USD to the bank account in
- When the USD arrives, Harbor sends the USDC to the wallet.
sequenceDiagram
participant App as Your App
participant Harbor
participant Customer
participant Wallet as Recipient's Wallet
App->>Harbor: POST /api/v2/transfers/quotes
Harbor-->>App: Quotes, one per payment method
App->>Harbor: GET /api/v2/transfers/quotes/{quote_id}/requirements
Harbor-->>App: Transfer requirements
App->>Harbor: POST /api/v2/transfers
Harbor-->>App: Transfer with transfer_instructions
Customer->>Harbor: Wires USD using transfer_instructions
Harbor->>Wallet: Sends USDC
Example: Domestic Wire
This example sends 100 USDC on the Ethereum network to Sam Rivera, paid by domestic wire.
Get a Quote
Quote USD to USDC on behalf of the Customer:
curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v2/transfers/quotes' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--data-raw '{
"on_behalf_of": "{{CUSTOMER_UUID}}",
"source": {
"country": "US",
"asset": "USD",
"type": "individual"
},
"destination": {
"chain": "ethereum",
"asset": "USDC",
"amount": 100,
"type": "individual"
}
}'The response returns a quote for each payment method the Customer can use. For this example, we use the DOMESTIC_WIRE quote. Save its id:
{
"data": [
...,
{
"id": "quote_OMM5uWofyueuhTzwv8xIKgKbrbzzChTsdf9pYBqE",
"payment_method": "DOMESTIC_WIRE",
"source_amount": "100.00",
"source_currency": "USD",
"destination_amount": "100.000000",
"destination_currency": "USDC",
"destination_chain": "ethereum",
"exchange_rate": "1.00000000",
"quote_expire_date": "2026-10-06T09:08:19+00:00",
...
}
]
}For all the quote fields, see Quotes.
Get the Requirements
curl --location --request GET 'https://harbor-sandbox.owlpay.com/api/v2/transfers/quotes/{{QUOTE_ID}}/requirements' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'For a domestic wire, the requirements only ask for destination, the recipient and their wallet:
beneficiary_info: the recipient's name and address.payout_instrument.address: the wallet that receives the USDC.transfer_purposeandis_self_transfer.beneficiary_receiving_wallet_typeandbeneficiary_institution_name: the wallet type and provider.
The fields change by route, so always build your request from the requirements. See Transfer Requirements.
Create the Transfer
curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v2/transfers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{Idempotency-Key}}' \
--data-raw '{
"quote_id": "{{QUOTE_ID}}",
"on_behalf_of": "{{CUSTOMER_UUID}}",
"application_transfer_uuid": "{{APPLICATION_TRANSFER_UUID}}",
"destination": {
"beneficiary_info": {
"beneficiary_name": "Sam Rivera",
"beneficiary_address": {
"street": "123 Main St",
"city": "Austin",
"state_province": "TX",
"postal_code": "78701",
"country": "US"
}
},
"payout_instrument": {
"address": "0x76da4165da3d87b0dfcfeb867a31a0d7ab9884a5"
},
"transfer_purpose": "FAMILY_MAINTENANCE",
"is_self_transfer": false,
"beneficiary_receiving_wallet_type": "non_custodial",
"beneficiary_institution_name": "Self-hosted wallet"
}
}'{
"data": {
"uuid": "transfer_VjLJanYIWFniwezQDa5Z4Xi3lhPw0lM63qOw9PyS",
"object": "transfer",
"status": "pending_customer_transfer_start",
"sub_status": null,
"type": "on-ramp",
"settlement_strategy": "immediate",
"source_received": false,
"on_behalf_of": "cus_2XxcIyUQbPNzMAdyJ7NFjolt8t5zBEvqr402fjqK",
"source": {
"payment_method": "DOMESTIC_WIRE",
"payment_method_label": "Domestic Wire",
"asset": "USD",
"amount": "100.00000000"
},
"destination": {
"asset": "USDC",
"amount": "100.00000000",
"chain": "ethereum",
"payout_instrument": {
"chain": "ethereum",
"address": "0x76da4165da3d87b0dfcfeb867a31a0d7ab9884a5"
},
"is_self_transfer": false,
"transfer_purpose": "FAMILY_MAINTENANCE",
"beneficiary_receiving_wallet_type": "non_custodial",
"beneficiary_institution_name": "Self-hosted wallet"
},
"application_transfer_uuid": "order-1001",
"transfer_instructions": {
"account_number": "123456789012",
"routing_number": "021214891",
"bank_name": "Cross River Bank",
"bank_address": "Cross River Bank, 885 Teaneck Rd, Teaneck, NJ 07666",
"account_holder_name": "Sample Customer",
"narrative": "1234567890"
},
"commission": {
"percentage": "0",
"amount": "0"
},
"fees": [
{
"type": "HARBOR_FEE",
"amount": "1.714575",
"currency": "USDC",
"charge_from": "OwlPay Harbor",
"payer": "Your Company LLC"
},
{
"type": "COMMISSION_FEE",
"amount": "0.000000",
"currency": "USDC",
"charge_from": "Your Company LLC",
"payer": "customer"
}
],
"receipt": {
"initial_asset": "USD",
"initial_amount": "100.00000000",
"commission_fee": "0.00000000",
"harbor_fee": "1.71",
"final_asset": "USDC",
"final_amount": "100.00000000",
"exchange_rate": "1.00000000",
"transaction_hash": null,
"tracking_number_status": null
},
"meta_data": null,
"crypto_pay_in_expired_at": null,
"created_at": "2026-10-06T08:08:31+00:00",
"updated_at": "2026-10-06T08:08:31+00:00"
}
}The transfer starts as pending_customer_transfer_start: Harbor is waiting for the Customer's funds.
Send the Funds
The Customer sends a wire to the bank account in transfer_instructions:
- Amount:
source.amount, here 100.00 USD. - Account:
account_number,routing_number,bank_nameandaccount_holder_name. - Reference: include the
narrativein the wire, so Harbor can match the funds to this transfer.
When the funds arrive, Harbor sends the USDC to the recipient's wallet and the transfer moves to completed. Follow the status by retrieving the transfer or with webhooks. See Transfer Lifecycle.
Confirm the Payout
When the transfer is completed, receipt.transaction_hash has the transaction on the blockchain that received the USDC. Look it up in a block explorer for that blockchain to confirm the payout:
{
"data": {
"uuid": "transfer_cZm1GY2BaNFY6UPx9gyk83DneEUlpyC2cVFf1Euc",
"status": "completed",
...,
"receipt": {
...,
"initial_asset": "USD",
"initial_amount": "100.00000000",
"final_asset": "USDC",
"final_amount": "100.00000000",
"transaction_hash": "0x9f2c1b7a4e8d3f605a1c2b9d7e4f8a30c6b5d1e2f3a49b8c7d6e5f4a3b2c1d0e"
}
}
}{
"data": {
"uuid": "transfer_cZm1GY2BaNFY6UPx9gyk83DneEUlpyC2cVFf1Euc",
"status": "completed",
...,
"receipt": {
...,
"initial_asset": "USD",
"initial_amount": "100.00000000",
"final_asset": "USDC",
"final_amount": "100.00000000",
"transaction_hash": "3SSMAknpVAe5f4WQun9dS3u3wCNnSwn7XQdVtUJ1frb8QDGd6mZovMmsKL6UEHPBXqu8JpewRwnvRNJK3XfvTqCi"
}
}
}The transfer.status.completed webhook has the same receipt.
Refunds
OwlPay Support handles every on-ramp refund. The funds go back to where they came from, the bank account or card that paid. They can't go to a wallet, so on-ramp has no refund_address.
- You can't request a refund through the API. Contact OwlPay Support with the transfer.
- The full amount is returned. Banks along the way can deduct their own fees.
How long a refund takes depends on the payment method:
| Payment method | Time |
|---|---|
DOMESTIC_WIRE | 1 to 3 business days |
ACH_PULL | 3 to 5 business days |
RTP | About 1 business day |
DEBIT_CARD | 1 to 3 business days for a release, 3 to 5 for a refund |
To follow a refund, call:
GET /api/v2/transfers/{transfer_uuid}/refunds
{
"data": [
{
"id": 1,
"transfer_id": 123,
"application_id": 45,
"refund_type": "full",
"status": "completed",
"currency": "USD",
"amount": "1000.00",
"chain": null,
"address": null,
"bank_name": "Bank of America",
"bank_address": "123 Main St, New York, NY",
"account_number": "1234567890",
"routing_number": "021214891",
"account_holder_name": "John Doe",
"narrative": "transfer_1234567890 refund",
"tracking_number": "20260909MMQFMPU8000123",
"omad": "20260909B1QGC03R000456",
"reversal_rail_payment_id": "rail_abc123",
"reason": "Third party payment",
"requested_at": "2026-09-08T00:00:00+00:00",
"processed_at": "2026-09-08T01:00:00+00:00",
"completed_at": "2026-09-09T00:00:00+00:00",
"created_at": "2026-09-08T00:00:00+00:00",
"updated_at": "2026-09-09T00:00:00+00:00"
}
]
}Each refund has its refund_type (full or partial), amount and status. The refund is final when its status is completed.
When the full amount is refunded, the transfer moves to refunded and Harbor sends the transfer.status.refunded webhook. A partial refund has no webhook.
Notes
- In Sandbox,
DEBIT_CARDandACH_PULLtransfers move through their statuses automatically. ForDOMESTIC_WIREandRTP, simulate the next statuses. See Simulate Transfer Status. - On-ramp only delivers USDC. USDT isn't supported yet: a quote for USDT returns error
2005. - To check whether the Customer's bank supports RTP, send its routing number to
POST /api/v2/transfers/rtp/check. The response'ssupportedistrueorfalse. - If the funds don't arrive within 3 to 4 days, the transfer expires. See Transfer Lifecycle.
- Overfunded: the transfer goes ahead and pays out the quoted amount only. The extra isn't refunded automatically. Contact OwlPay Support.
- Underfunded: the transfer waits in
pending_customer_transfer_start. Send the rest to the same account to continue. If it expires, contact OwlPay Support for a refund. - Overfunding and underfunding don't apply to
ACH_PULLorDEBIT_CARD, which take the exact amount.
Updated about 14 hours ago