Link Bank Account

Pull deposits from a linked U.S. bank account with ACH Pull.

ACH Pull lets a Customer fund an on-ramp transfer from a linked U.S. bank account. They link it once, then use it for each transfer.

How It Works

From linking the account to the USDC payout:

  • The Customer links a bank account in a widget. Harbor saves it with an ID that starts with clbacc_.
  • You get an ACH_PULL quote.
  • You create the transfer with the clbacc_ ID and the quote_id.
  • Harbor emails the account holder to approve the payment, then debits the account.
  • When the funds clear (T+2), Harbor sends the USDC. See Settlement and Payment Lock Time.

Eligibility

ACH Pull works for individual and business Customers. It's only available to US-based Applications. Your business location and registered address must be in a state where OwlPay holds a Money Transmitter License (MTL).

Before a Customer can link a bank account:

  1. Your Application has the ACH_PULL payment method enabled.
  2. The Customer has completed KYC or KYB verification (status: VERIFIED).
  3. The Customer has completed bank compliance onboarding (status: ONBOARDED).
  4. The bank account is a U.S. checking or savings account.

Example: ACH Pull

These steps link a bank account, then use it to create a transfer.

Connect the Bank Account

POST /api/v1/customers/{customer_uuid}/bank-connections/widget-url

Generate a widget URL for the Customer, and send them to it.

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v1/customers/{{CUSTOMER_UUID}}/bank-connections/widget-url' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--data-raw '{
    "redirect_url": {
        "success": "https://yourapp.com/bank-connected"
    }
}'

redirect_url.success is optional. Harbor sends the Customer there after they connect: a web link or an app deep link. If the connection fails or the Customer cancels, they stay in the widget.

{
    "data": {
        "widget_url": "https://link-sandbox.owlpay.com/bank_link/.../dashboard?payload=..."
    }
}

Open the widget_url in a redirect or an iframe. The Customer sees these screens:

1. Select the bank.

The Customer searches for their bank.

In Sandbox, search for MX Bank. Don't choose Connect with account numbers

The bank connection widget, Select your institution

2. Sign in.

The Customer enters their bank credentials.

In Sandbox, use mxuser and any password.

The bank connection widget, Enter your credentials

3. Select the account.

For example, Checking or Savings.

The bank connection widget, Account selection

4. Finish.

The widget shows Success, and the connection is CONNECTED.

The bank connection widget, Success

If the Customer already linked a bank, the widget shows it first, with a Search more institutions button.

List the Linked Accounts

GET /api/v1/customers/{customer_uuid}/linked-bank-accounts

Get the Customer's linked accounts:

curl --location --request GET 'https://harbor-sandbox.owlpay.com/api/v1/customers/{{CUSTOMER_UUID}}/linked-bank-accounts' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'
{
    "data": [
        {
            "id": "clbacc_45b93a4affca4bc2818dc189264b6e07",
            "name": "Checking",
            "type": "CHECKING",
            "last4_digits": "0685",
            "institution_name": "mxbank",
            "connection_status": "CONNECTED"
        }
    ]
}
  • id: the linked bank account's ID, starting with clbacc_. Send it as linked_bank_account_id when you create an ACH Pull transfer.
  • name: the account name.
  • type: CHECKING or SAVINGS.
  • last4_digits: the last 4 digits of the account number.
  • institution_name: the bank's name.
  • connection_status: for example CONNECTED.

Get a Quote

POST /api/v2/transfers/quotes

Get a quote for the rate, the fees and the amount.

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": {
        "amount": "100.00",
        "asset": "USD",
        "type": "individual",
        "country": "US"
    },
    "destination": {
        "asset": "USDC",
        "type": "individual",
        "chain": "stellar"
    }
}'

The response has a quote for each payment method. Pick the one where payment_method is ACH_PULL.

{
    "data": [
        {
            "id": "quote_f03AirZ3ZY...KBtFQfZtPDYv",
            "payment_method": "ACH_PULL",
            "source_amount": "100.00",
            "source_currency": "USD",
            "destination_amount": "100.000000",
            "destination_currency": "USDC",
            "destination_chain": "stellar",
            "exchange_rate": "1.00000000",
            "fees": [
                {
                    "type": "HARBOR_FEE",
                    "amount": "1.700000",
                    "currency": "USDC"
                }
            ],
            "quote_expire_date": "2026-03-21T09:30:00+00:00"
        }
    ]
}

Its id is the quote_id you need next.

Create the Transfer

POST /api/v2/transfers

Use the clbacc_ ID in source.payment_instrument.linked_bank_account_id and the quote_id:

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 '{
    "on_behalf_of": "{{CUSTOMER_UUID}}",
    "quote_id": "{{QUOTE_ID}}",
    "application_transfer_uuid": "{{YOUR_ORDER_ID}}",
    "source": {
        "payment_instrument": {
            "linked_bank_account_id": "clbacc_45b93a4affca4bc2818dc189264b6e07"
        }
    },
    "destination": {
        "beneficiary_info": {
            "...": "Fill according to quote requirements"
        },
        "payout_instrument": {
            "address": "0x1234567890abcdef1234567890abcdef12345678"
        },
        "transfer_purpose": "SALARY",
        "is_self_transfer": true
    }
}'

All of these are required:

  • on_behalf_of: the Customer's UUID.
  • quote_id: the quote's id.
  • application_transfer_uuid: your order ID. Harbor also uses it to detect repeats.
  • source.payment_instrument.linked_bank_account_id: the id of the linked bank account (clbacc_...). For ACH Pull only. For a debit card, use linked_card_id.
  • destination: where the USDC goes, with the payout address and beneficiary details.

Harbor returns 201 Created with the Transfer object, in pending_customer_transfer_start.

Approve the Payment

After the transfer is created, Harbor emails the account holder a "Payment Authorization Request". Harbor debits the account only after they approve.

The Payment Authorization Request email for ACH Pull
  • The link works for 24 hours. If the link expires, the transfer is expired. If the account holder declines, it is cancelled.
📘

Harbor sends this email in Production only.

Get One Linked Account

GET /api/v1/customers/{customer_uuid}/linked-bank-accounts/{linked_bank_account_id}

curl --location --request GET 'https://harbor-sandbox.owlpay.com/api/v1/customers/{{CUSTOMER_UUID}}/linked-bank-accounts/{{LINKED_BANK_ACCOUNT_ID}}' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'
{
    "data": {
        "id": "clbacc_45b93a4affca4bc2818dc189264b6e07",
        "name": "Checking",
        "type": "CHECKING",
        "last4_digits": "0685",
        "institution_name": "mxbank",
        "connection_status": "CONNECTED"
    }
}

Transfer Status

After you create the transfer, it moves through these statuses:

  • pending_customer_transfer_start: created, waiting for the account holder to approve.
  • pending_customer_transfer_start with sub_status awaiting_settlement: approved, and Harbor waits for the bank to confirm the pull.
  • pending_harbor: the bank confirmed the pull. Harbor waits for the funds to settle (T+2).
  • pending_external: the USDC is sent to the blockchain.
  • completed: done.

If the USDC goes to an internal wallet, the transfer is completed as soon as the bank confirms the pull, and the funds stay locked until they settle. See Settlement and Payment Lock Time.

A transfer can also be on_hold (compliance check), reject (the pull failed), expired (the approval link expired) or cancelled (the account holder declined).

Listen to the status webhooks. See Transfer Lifecycle.

Errors

Creating the transfer can fail with these errors:

StatusReason
422The bank account's balance is too low for the transfer amount.
422The Customer doesn't exist, hasn't completed bank compliance onboarding, or isn't eligible for the service.
422The bank account is blocked.
422The bank connection isn't CONNECTED. The Customer must reconnect the account.
422The Customer can't start transfers, or the quote's source type doesn't match the Customer.
400The quote has expired.
400The amount is over a payment method limit: per transaction, daily, weekly or monthly.
403Your Application isn't allowed to create transfers. Contact OwlPay Support.
409Another transfer is being created for this Customer. Try again.

Complete Flow Diagram

sequenceDiagram
    autonumber
    participant PSP as Your Application
    participant Harbor as Harbor API
    participant Bank as Bank / Institution
    participant User as Account Holder

    Note over PSP, User: Connect the bank account
    PSP->>Harbor: POST /customers/{uuid}/bank-connections/widget-url
    Harbor-->>PSP: {widget_url}
    PSP->>User: Redirect to widget
    User->>Bank: Authenticate & authorize in widget
    Bank-->>Harbor: Account linked
    Harbor->>Harbor: Sync account info

    Note over PSP, User: List the linked accounts
    PSP->>Harbor: GET /customers/{uuid}/linked-bank-accounts
    Harbor-->>PSP: [{id: "clbacc_...", name, type, ...}]

    Note over PSP, User: Get a quote
    PSP->>Harbor: POST /v2/transfers/quotes
    Harbor-->>PSP: [{payment_method: "ACH_PULL", id, ...}]

    Note over PSP, User: Create the transfer
    PSP->>Harbor: POST /v2/transfers (with clbacc_ ID + quote_id)
    Harbor->>Harbor: Validate account balance

    alt Insufficient balance
        Harbor-->>PSP: 422 Insufficient balance
    else Balance OK
        Harbor->>Bank: Create deposit order (ACH_PULL)
        Bank-->>Harbor: Order created
        Harbor-->>PSP: 201 Created (Transfer object)
        Harbor->>User: Email to approve the payment
        User-->>Harbor: Approve
    end

Notes

  • Sandbox doesn't send emails. In Production, the account holder gets an approval email, and a confirmation with a receipt when the transfer completes. Tell your Customers to expect both.
  • Harbor asks for approval by email because some banks don't ask the account holder themselves. The email warns them of the debit and keeps a record of their authorization, which helps in a chargeback.

Did this page help you?