Status Definitions
Customer Status
The status field on the Customer object shows where the Customer is in the onboarding and verification process.
| Status | Description |
|---|---|
| unfinished | The Customer is created, but their information isn't submitted yet. |
| finished | The Customer started the hosted form, but hasn't submitted it yet. Harbor updates this status about once an hour, so you may not see it before verifying. |
| verifying | Under verification. |
| verified | Verified and active. |
| rejected | The onboarding application is rejected due to errors in the submitted form or files (e.g. invalid formatting, illegible documents). The customer is allowed to modify the incorrect fields on their onboarding form and resubmit it for review. |
| declined | Application rejected, resubmission not allowed. |
| deactivated | Previously usable but later suspended. |
Customer State
The state field is a higher-level, customer-facing status derived from the underlying internal customer status. Providing the state field in the Customer object makes it much easier to understand the current onboarding and integration status at a glance. It simplifies integration by grouping internal status details into actionable states.
| State | Mapped from status | Description |
|---|---|---|
| not_started | unfinished | KYC has not been started yet. |
| in_progress | finished | Customer has filled out the form but has not yet submitted it for verification. |
| pending_review | verifying | Submitted and awaiting review. |
| verified | verified | Approved and able to transact. |
| update_required | rejected, or any status with an open RFI | Customer action is required before proceeding. |
| declined | declined | Permanently rejected; resubmission not allowed. |
| suspended | deactivated | Previously verified but now blocked. |
Onboarding Status
When you onboard through the API, the onboarding has its own status, next to the Customer's. See Onboarding Lifecycle.
| Status | Description |
|---|---|
| processing | Harbor received the information and is preparing it. The Customer is unfinished, or still rejected after a correction. |
| submitted | The information is in review. The Customer is verifying. |
| action_required | Something needs to be corrected. The Customer is usually rejected. Correct it and resend it with PATCH. See Fix Onboarding Errors. |
| verified | The onboarding is approved. The Customer is verified. |
| declined | The onboarding is declined. This is final. The Customer is declined. |
| failed | The onboarding couldn't be processed because of an error on Harbor's side. Resend it with PATCH. |
Transfer Status
The status field on the Transfer object shows where the transfer is in its lifecycle, from waiting for the Customer's funds to completion.
| Status | Description |
|---|---|
| pending_customer_transfer_start | The customer has not yet initiated their transfer to the instruction. |
| pending_external | Deposit/withdrawal has been submitted to an external network but is not yet confirmed. Waiting for another external crypto network or a bank transfer to complete. On an off-ramp, Harbor detected the customer's payment and is waiting for the network to confirm it. |
| pending_card_binding | Debit card payouts only. Harbor is waiting for the recipient to add their card. See Pay First, Bind Later. |
| pending_harbor | Deposit/withdrawal is being processed internally by Harbor. This can also be used when Harbor must verify KYC information prior to deposit/withdrawal. |
| on_hold | Transfer is on hold for additional compliance checks (e.g. AML verification). This may occur before or after funds are received. For example, on-ramp transfers paid by Debit Card or ACH Pull are reviewed before the funds are pulled. Once cleared, the transfer resumes. |
| request_for_information | Harbor needs more information before the transfer can continue. The Customer provides it on the rfi_link page or through the API. See Transfer RFI. |
| completed | Deposit/withdrawal fully completed. |
| refunded | The deposit/withdrawal is fully refunded. |
| expired | Funds were never received, and the transfer is considered abandoned by the customer. |
| cancelled | Deposit/withdrawal was cancelled by the customer. |
| reject | The transfer has been rejected. |
| error | Catch-all for any error not enumerated above. |
Transfer Sub-Status
The sub_status field provides a more granular state explanation within a primary status. This is particularly useful for tracking transactions that are undergoing multi-step clearing or bank settlement processes (such as ACH Pull or Debit Card transfers).
| Sub-Status | Associated Status | Description |
|---|---|---|
| awaiting_settlement | pending_customer_transfer_start | Harbor started the pull from the customer's ACH bank account or Debit Card, and is waiting for the bank to confirm it. |
| cpn_rfi | request_for_information | The off-ramp payment network needs more information. See Transfer RFI. |
| cpn_rfi_submitted | request_for_information | The answers to a cpn_rfi were submitted and are being reviewed. |
Notes
- Rejected and RFI: a
rejectedCustomer has errors in the form or the files. The Customer corrects the fields and resubmits the whole application. An RFI is a request for more information or documents when the form is valid. The Customer provides only what is requested. Thestatusdoesn't change, and thestatechanges toupdate_required. See Onboarding RFI. - State and status: the mapping isn't one-to-one. A Customer with an open RFI has the
stateupdate_required, whatever thestatus. For example, averifiedCustomer showsupdate_requireduntil the requested information is provided. awaiting_settlement: when a Customer pays by ACH Pull or Debit Card, the transferstatusispending_customer_transfer_startand thesub_statusisawaiting_settlementuntil the bank confirms the pull. Then thestatusbecomespending_harborwhile the funds settle. ACH Pull settles in 2 US business days (T+2), and Debit Card in 1 US business day (T+1). See Settlement and Payment Lock Time.
Updated about 14 hours ago