AboutOwlPayOwlTing
Guides
Contact Us
Start typing to search…

On-ramp (Fiat to Stablecoin)

This guide provides an overview of how to facilitate on-ramp transactions (fiat to stablecoin) using the Harbor API, including customer registration, payment processing, required headers, and API request examples.

The Harbor on-ramp API allows you to securely facilitate fiat-to-stablecoin conversions, enabling you to manage the deposit and conversion process independently. Before initiating an on-ramp transaction, you must first create a customer using the Customers API. Once the customer is successfully registered, you can proceed with processing their fiat deposit and converting it to stablecoins. This API provides flexibility in handling on-ramp transactions, whether for individuals or businesses.

🛑

Requirements

The customer must agree to Harbor’s Terms of Service.
An Idempotency Key (X-Idempotency-Key) is required to prevent duplicate submissions.

API Request: On-Ramp (Fiat to Stablecoin)

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v1/transfer' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'Idempotency-Key: {{Idempotency-Key}}' \
--data-raw '{
    "commission": {
        "percentage": "0.01", // optional, allow: 0.01-100.00
        "amount": "1.00" // optional, should be greater than 0
    },
    "source": {
    		"on_behalf_of": "cus_1234567890", // optional, If destination.customer_crypto_address_id is not null, you must provide it.
        "asset": "USD", // required, default: USD
        "amount": "100.00" // required, should be greater than 0
    },
    "destination": {
        "asset": "USDC", // required, default: USDC
        "chain": "ethereum", // required, allowed: ethereum, arbitrum, polygon, avalanche, optimism
        "address": "0x4B20993Bc481177ec7E8f571ceCaE8A9e22C02db", // required, which should be a valid address for the chain
        "beneficiary_name": "John Doe" // required, when you are making this transfer on behalf of a customer.
    },
    "application_transfer_uuid": "{{YOUR_APPLICATION_TRANSFER_UUID}}" // required, which should be a unique identifier for the transfer within your application
}'

📘

What is the difference between submitting a customer pre-registration and non-pre-registration in destination?

If you submit the Transfer information directly instead of submitting the customer's pre-registered bank account or crypto address, Harbor may ask you to provide more information for this transaction.

customer pre-register is used to register the customer's own bank account / crypto address, while Transfer is used to transfer to other people on behalf of the customer.

If Transfer requires you to provide more information, the Transfer status will be changed to on_hold

⚠️

Warning

If you want to use a specific customer crypto address, include the customer_crypto_address_id field, and omit asset, chain, and address. Otherwise, you can specify the asset, blockchain network, and recipient address directly in the destination field.

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v1/transfer' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'Idempotency-Key: {{Idempotency-Key}}' \
--data-raw '{
    "commission": {
        "percentage": "0.01",
        "amount": "1.00",
    },
    "source": {
        "asset": "USD",
        "amount": "100.00",
    },
    "destination": {
        "asset": "USDC",
        "customer_crypto_address_id": "{{CUSTOMER_CRYPTO_ADDRESS_ID}}", // Optional, if you want to use a specific customer crypto address, you can provide the id here (If you input both, destination.address will be ignored)
    },
    "application_transfer_uuid": "{{YOUR_APPLICATION_TRANSFER_UUID}}"
}'

The endpoint will return a response as shown below.

{
    "data": {
        "status": "pending_customer_transfer_start",
        "source": {
            "on_behalf_of": "cus_yUlGOzdD8QZplB2Vh2biFYvl0iCCA58454kFpBNx",
            "asset": "USD",
            "amount": "100.00"
        },
        "destination": {
            "asset": "USDC",
            "chain": "ethereum",
            "address": "0x4B20993Bc481177ec7E8f571ceCaE8A9e22C02db",
            "address_memo": null,
            "beneficiary_name": null,
            "amount": "87.00"
        },
        "application_transfer_uuid": "MOCK_TEST_UUID",
        "transfer_instructions": {
            "account_number": "123456789012",
            "routing_number": "987654321",
            "bank_name": "FV Bank",
            "bank_address": "1234 Maple Lane, Springfield, IL 62704, USA",
            "account_holder_name": "OwlTing USA",
            "narrative": "1549310090"
        },
        "commission": {
            "percentage": "0.01",
            "amount": "1.00"
        },
        "receipt": {
            "initial_amount": "100.00",
            "commission_fee": "2.00",
            "harbor_fee": "11.00",
            "final_amount": "87.00",
            "transaction_hash": null
        },
        "created_at": "2025-02-18T12:27:32+00:00",
        "updated_at": "2025-02-18T12:27:32+00:00"
    }
}

Updated 10 days ago