# Onboarding Status

Check whether the user has completed the bank ramp's onboarding (KYC) and can start EUR deposits.

## Overview

Fiat pay-in and pay-out require the user to be onboarded with **The bank ramp**, Aurea's fiat partner. This endpoint returns what Aurea has stored for the user — it doesn't call the bank ramp. When the user has just come back from the hosted onboarding, call [Sync KYC Status](https://docs.aureahub.com/docs/payin-sync-status.md) instead, which pulls the latest state from the bank ramp.

A user has a separate bank ramp profile in sandbox and in production, each with its own onboarding, KYC status, IBANs and history. Pass `isTestnet=true` to read the sandbox profile; without it, or with `false`, you get the production profile. Use the same value as for the [onboarding session](https://docs.aureahub.com/docs/payin-session.md).

`canInitiateDeposit` is `true` only when `onboardingStatus` is `completed` and `kycStatus` is `approved`. A user who never started onboarding in that environment gets `not_started` for both statuses and no `customerId`. A user who opened the hosted page but was turned away on it reads the same way, and cannot be told apart — see [When the Bank Ramp Says No](https://docs.aureahub.com/docs/payin-session.md).

`verification` tells you what the user must do next — `nextStep` — and why: each region's verification, what the bank ramp asks for, and the agreements (see Verification below).

Your tenant must be connected to the bank ramp first — see [Bank Ramp Setup](https://docs.aureahub.com/docs/bank-setup.md).

## Payin Flow

1. **Onboarding Status** (this page) — is the user approved?
2. [**Onboarding Session**](https://docs.aureahub.com/docs/payin-session.md) — if not, send the user to the bank ramp's hosted KYC.
3. [**Sync KYC Status**](https://docs.aureahub.com/docs/payin-sync-status.md) — refresh the status when the user returns.
4. [**Initiate Deposit**](https://docs.aureahub.com/docs/payin-initiate.md) — a virtual IBAN for bank transfers. Card payments go through the [card onramp](https://docs.aureahub.com/docs/guide-card-onramp.md) instead.
5. [**Get Deposits**](https://docs.aureahub.com/docs/payin-deposits.md) — follow incoming bank transfers.

## Endpoint

### `GET /v1/ramp/bank/payin/onboarding-status`

Authentication: bearer token required.

Returns the user's bank ramp onboarding and KYC status in one environment, as stored by Aurea.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `isTestnet` | boolean | no | `true` for the sandbox profile; `false` or omitted for production. Any other value returns `400`. |

**Responses**

`200` OK

```json
{
  "customerId": "3f6c2a8e-5b1d-4e7a-9c3f-2d8e1b4a6c90",
  "noahCustomerId": "aurea_5d1f0c9b2e7a4c3d8f6b1a0e9c2d7b4f5a3e",
  "onboardingStatus": "completed",
  "kycStatus": "approved",
  "canInitiateDeposit": true,
  "message": "Customer is fully onboarded and can initiate deposits",
  "verification": {
    "status": "Approved",
    "customerType": "Individual",
    "regions": [
      { "entity": "Lt", "region": "EU", "status": "Approved", "rejection": null }
    ],
    "actionsRequired": [],
    "agreements": [
      { "name": "NoahTermsOfService", "version": 1, "accepted": true, "acceptedAt": "2026-09-17T09:12:41Z" },
      { "name": "NoahPrivacyPolicy", "version": 1, "accepted": true, "acceptedAt": "2026-09-17T09:12:41Z" }
    ],
    "nextStep": "approved"
  }
}
```

Values: `onboardingStatus` is `not_started`, `pending`, `in_progress`, `completed` or `failed`; `kycStatus` is `not_started`, `pending`, `approved` or `rejected`. `kycTier` is included when the bank ramp has assigned one.

## Verification

`verification` is what Aurea keeps from the bank ramp about the user's verification in that environment, from the bank ramp's `Customer` events and from [Sync KYC Status](https://docs.aureahub.com/docs/payin-sync-status.md). It never contains a reviewer's comment.

| Field | Description |
| --- | --- |
| status | the bank ramp's overall verification: `Pending`, `Approved` (at least one region approved) or `Declined` (final: The bank ramp offboarded the user). `null` before the bank ramp has said anything. It never moves back: an approved user stays approved unless the bank ramp declines them. |
| customerType | `Individual` or `Business`, once the bank ramp has said which; otherwise `null`. |
| regions | One entry per the bank ramp legal entity that verifies the user: `entity` (`Lt`, `Us`, `Ca`), `region` (`EU`, `US`, `CA`), `status` for that region, and `rejection` for a declined region — `retry` when the user may try again, `final` when not, otherwise `null`. Check the region you need: a user can be approved in one region and declined in another. |
| actionsRequired | What the bank ramp asks the user to do before the review continues, such as `DocumentReupload`, `ProofOfAddress`, `SelfieReupload` or `HighRiskInfo`. Empty when nothing is asked. The list can grow: show a generic message for a value you don't know. |
| agreements | The agreements the bank ramp last listed for the user: `name`, `version`, `accepted`, `acceptedAt`. |
| nextStep | What to do now: `start_onboarding` (no profile yet, or the bank ramp has said nothing) and `continue_onboarding` (the bank ramp asks for something, a region may retry, or an agreement is not accepted) — create an [onboarding session](https://docs.aureahub.com/docs/payin-session.md) and open it; `wait_for_review` — the bank ramp is reviewing; `approved` — nothing to do; `rejected` — the bank ramp declined the user for good. |

`kycStatus` and `onboardingStatus` follow the overall status and never move back either: Pending is `pending`/`pending`, Approved `approved`/`completed`, Declined `rejected`/`failed`.

## Implementation

```javascript
// Decide which fiat screen to show, in the environment the app runs in
async function getFiatEligibility(token, { sandbox = false } = {}) {
  const res = await fetch(`https://api.aureahub.com/v1/ramp/bank/payin/onboarding-status?isTestnet=${sandbox}`, {
    headers: { Authorization: `Bearer ${token}` }
  });
  if (!res.ok) throw new Error(`Onboarding status failed: ${res.status}`);

  const { canInitiateDeposit, verification } = await res.json();

  if (canInitiateDeposit) return { eligible: true, nextStep: verification.nextStep };
  switch (verification.nextStep) {
    case 'rejected':
      return { eligible: false, reason: 'kyc_rejected' };
    case 'start_onboarding':
    case 'continue_onboarding': // open a new onboarding session: The bank ramp shows what is missing
      return { eligible: false, reason: 'needs_onboarding', actions: verification.actionsRequired };
    default:
      return { eligible: false, reason: 'kyc_in_review' };
  }
}
```

---

Web version: https://docs.aureahub.com/#payin-status