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:
  • 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.
  • 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_purpose and is_self_transfer.
  • beneficiary_receiving_wallet_type and beneficiary_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_name and account_holder_name.
  • Reference: include the narrative in 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"
        }
    }
}

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 methodTime
DOMESTIC_WIRE1 to 3 business days
ACH_PULL3 to 5 business days
RTPAbout 1 business day
DEBIT_CARD1 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_CARD and ACH_PULL transfers move through their statuses automatically. For DOMESTIC_WIRE and RTP, 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's supported is true or false.
  • 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_PULL or DEBIT_CARD, which take the exact amount.

Did this page help you?