Transfer Lifecycle

How a transfer's status changes after you create it, and when it expires.

After you create a transfer, its status changes as Harbor processes it. Follow the changes by retrieving the transfer, or subscribe to the transfer.status.* webhook events.

Transfer Status

The current status is in the transfer's status field. Some statuses also have a sub_status with more detail, otherwise it's null. For example, an on-ramp transfer waiting for the Customer's wire:

{
    "data": {
        "uuid": "transfer_19nl6HpytqmSjZN5KFVGJ1tQdxfy1XfLtxAv7vCe",
        "object": "transfer",
        "status": "pending_customer_transfer_start",
        "sub_status": null,
        "type": "on-ramp",
        ...,
        "created_at": "2026-10-06T01:29:06+00:00",
        "updated_at": "2026-10-06T01:29:08+00:00"
    }
}

For what each status means, see Status Definitions.

Status Flow

The transfer's status from creation to the result.

On-ramp

%%{init: {"flowchart": {"curve": "monotoneY"}, "state": {"curve": "monotoneY", "useMaxWidth": false}}}%%
stateDiagram-v2
    [*] --> pending_customer_transfer_start: Transfer created
    pending_customer_transfer_start --> aml: Funds received
    pending_customer_transfer_start --> expired: Not paid in time
    pending_customer_transfer_start --> reject
    aml --> pending_harbor: Cleared
    aml --> on_hold: Held for review
    on_hold --> pending_harbor: Approved
    on_hold --> request_for_information: More info needed
    on_hold --> reject
    request_for_information --> pending_harbor: Approved
    request_for_information --> reject
    pending_harbor --> completed: Payout sent
    pending_harbor --> refunded: Payout failed
    reject --> refunded: Funds returned
    state "AML check" as aml

    classDef check fill:#f3f4f6,stroke:#9ca3af,stroke-dasharray:4 3,color:#374151
    class aml check
    classDef success fill:#d1fae5,stroke:#059669,color:#065f46
    class completed success
    classDef failure fill:#fee2e2,stroke:#dc2626,color:#991b1b
    class expired, refunded, reject failure
    classDef warning fill:#fef3c7,stroke:#d97706,color:#92400e
    class request_for_information warning

Off-ramp and on-chain

%%{init: {"flowchart": {"curve": "monotoneY"}, "state": {"curve": "monotoneY", "useMaxWidth": false}}}%%
stateDiagram-v2
    [*] --> pending_customer_transfer_start: Transfer created
    pending_customer_transfer_start --> pending_external: Funds received
    pending_customer_transfer_start --> pending_card_binding: No card yet
    pending_customer_transfer_start --> expired: Not paid in time
    pending_customer_transfer_start --> reject
    pending_external --> aml: transaction confirmed
    pending_card_binding --> aml: Card added
    aml --> pending_harbor: Cleared
    aml --> on_hold: Held for review
    on_hold --> pending_harbor: Approved
    on_hold --> request_for_information: More info needed
    on_hold --> reject
    request_for_information --> pending_harbor: Approved
    request_for_information --> reject
    pending_harbor --> completed: Payout sent
    pending_harbor --> refunded: Payout failed
    reject --> refunded: Funds returned
    state "AML check" as aml

    classDef check fill:#f3f4f6,stroke:#9ca3af,stroke-dasharray:4 3,color:#374151
    class aml check
    classDef success fill:#d1fae5,stroke:#059669,color:#065f46
    class completed success
    classDef failure fill:#fee2e2,stroke:#dc2626,color:#991b1b
    class expired, refunded, reject failure
    classDef warning fill:#fef3c7,stroke:#d97706,color:#92400e
    class request_for_information warning
  • AML check: every transfer is checked, including the bank account details and the blockchain addresses. The transfer only shows on_hold when the check holds it for review. The AML check box in the diagram is a step, not a status.
  • Debit card and ACH pull: the AML check runs before the funds are pulled, so on_hold comes before the payment.
  • Debit card payout without a card (off-ramp): the transfer waits in pending_card_binding until the recipient adds a card. See Pay First, Bind Later.

Transfer Expiration

If Harbor doesn't receive the funds in time, the transfer expires. Its status changes to expired, and the transfer.status.expired webhook event is sent.

  • Paid in fiat (on-ramp): expires 3 to 4 days after it's created.
  • Paid in stablecoins (off-ramp, on-chain): expires at the time in crypto_pay_in_expired_at.
{
    "data": {
        "uuid": "transfer_A2voLGf6qn0tqInXa761zX4AFQoKfoDDAr8jg9S9",
        "status": "expired",
        "type": "off-ramp",
        ...,
        "crypto_pay_in_expired_at": "2026-09-16T10:09:03+00:00",
        "created_at": "2026-09-16T09:19:14+00:00",
        "updated_at": "2026-09-16T10:23:42+00:00"
    }
}


Notes

  • Fiat transfers are checked for expiration once a day, at 00:00 UTC. That's why they expire between 3 and 4 days after they're created.
  • The transfer's deadline is 10 minutes earlier than the one on the quote. For example, if the quote says 10:30, the transfer expires at 10:20. Use the transfer's crypto_pay_in_expired_at, not the quote.
  • Transfers can't be edited or deleted. If you created a transfer with the wrong details, don't fund it. It expires on its own. Then create a new quote and a new transfer with the correct details.
  • Funds received: source_received becomes true when the funds arrive. For crypto, that's when the transfer enters pending_external. For fiat, it's true by pending_harbor.
  • Rejected transfers: funds that already arrived are returned by OwlPay Support, and the transfer then moves from reject to refunded. A card payment is only released or never pulled, so it stays reject. A transfer rejected for sanctions reasons isn't refunded. To receive a crypto refund without delay, send refund_address when you create the transfer.

Did this page help you?