> ## Documentation Index
> Fetch the complete documentation index at: https://developers.ingopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Create a user, complete KYC verification, and issue a routable bank account.

This guide walks through the core Banking Platform onboarding flow: authenticating your requests, creating a user entity, submitting for KYC verification, and issuing a routable bank account once the entity is verified. No accounts or money movement are available until an entity clears verification — understanding this gate is the most important first step.

<Info>
  You'll need your **API key**, **HMAC username**, and **HMAC secret** to follow this guide. These are provisioned by your Ingo integration manager at onboarding. See [Authentication](/docs/banking/authentication) for the full signing guide.
</Info>

<Note>
  **IngoPay + Banking work together.** Inbound and outbound transactions — funding a sub-merchant's account, issuing disbursements — are handled through the IngoPay API. The Banking Platform manages entity onboarding, account issuance, internal book transfers, and ledger reporting. Both APIs use the same HMAC-SHA512 signing.
</Note>

***

## Environments

| Environment | Base URL                                            |
| ----------- | --------------------------------------------------- |
| Sandbox     | `https://api.sdev.banking.ingopayments.tech/api/v4` |
| Production  | `https://api.banking.ingopayments.tech/api/v4`      |

All examples in this guide use the sandbox base URL. Replace with the production URL when you are ready to go live.

***

## Steps

<AccordionGroup>
  <Accordion title="Step 1 — Authenticate your requests">
    Every Banking Platform request requires two things: your **API key** and an **HMAC-SHA512 signature**. The API key identifies your program; the signature proves the request body hasn't been tampered with. Both are required on every call — a valid API key alone will not work.

    Pass your API key in the request body alongside your other fields:

    ```json theme={null}
    {
      "api_key": "YOUR_API_KEY",
      ...
    }
    ```

    Then sign the request using HMAC-SHA512. The signing process is identical to the IngoPay API — see [Authentication](/docs/banking/authentication) for the full step-by-step guide.

    <Warning>
      Requests that pass the API key but fail signature verification are rejected at the gateway before reaching the API.
    </Warning>
  </Accordion>

  <Accordion title="Step 2 — Create a user">
    Create an individual user entity. This establishes the entity in your program and returns a `user_id` you'll use in all subsequent calls. The entity is created with `kyc_status: "not_started"` — no accounts or transactions are available yet.

    ```http theme={null}
    POST /api/v4/user/create HTTP/1.1
    Host: api.sdev.banking.ingopayments.tech
    Authorization: hmac username="test", algorithm="hmac-sha512", headers="request-line x-date content-type content-sha512 content-length", signature="..."
    X-Date: Fri, 17 Jan 2020 19:59:29 GMT
    Content-sha512: HpXfYk7qDatRNVlGHQOv3ELyAVd+JCdUcpHB5PMnu08=
    Content-Length: 215
    Content-Type: application/json

    {
      "api_key": "YOUR_API_KEY",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com",
      "phone_number": "5555550100",
      "address_one": "100 Main Street",
      "city": "Anytown",
      "state": "TX",
      "postal_code": "75001",
      "country": "US"
    }
    ```

    Successful response:

    ```json theme={null}
    {
      "status": "success",
      "message": "operation completed",
      "data": {
        "user_id": "user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef",
        "kyc_status": "not_started"
      }
    }
    ```

    Store the `user_id` — you'll need it for every subsequent call.
  </Accordion>

  <Accordion title="Step 3 — Submit for KYC verification">
    Submit the user for identity verification. Ingo routes the request to a third-party verification provider. In most cases verification completes same-day. In some cases, Ingo may reach out to your team to request additional documentation or corrections before the entity can be cleared.

    ```http theme={null}
    POST /api/v4/user/send-verification-request HTTP/1.1
    Host: api.sdev.banking.ingopayments.tech
    Authorization: hmac username="test", algorithm="hmac-sha512", ...
    Content-Type: application/json

    {
      "api_key": "YOUR_API_KEY",
      "user_id": "user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef",
      "ssn": "XXXXXXXXX",
      "date_of_birth": "1985-06-15"
    }
    ```

    A successful submission returns an updated `kyc_status`:

    ```json theme={null}
    {
      "status": "success",
      "message": "operation completed",
      "data": {
        "user_id": "user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef",
        "kyc_status": "in_review"
      }
    }
    ```
  </Accordion>

  <Accordion title="Step 4 — Check verification status">
    Poll for the verification result, or listen for the `user.kyc.success` / `user.kyc.failed` webhook. Do not proceed to account issuance until `kyc_status` is `"verified"`.

    ```http theme={null}
    POST /api/v4/user/check-verification-request HTTP/1.1
    Host: api.sdev.banking.ingopayments.tech
    Authorization: hmac username="test", algorithm="hmac-sha512", ...
    Content-Type: application/json

    {
      "api_key": "YOUR_API_KEY",
      "user_id": "user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef"
    }
    ```

    Response once verified:

    ```json theme={null}
    {
      "status": "success",
      "message": "operation completed",
      "data": {
        "user_id": "user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef",
        "kyc_status": "verified"
      }
    }
    ```

    | `kyc_status`  | Meaning                                                |
    | ------------- | ------------------------------------------------------ |
    | `not_started` | Verification not yet submitted                         |
    | `in_review`   | Submitted, awaiting result                             |
    | `verified`    | Confirmed — entity can receive accounts                |
    | `failed`      | Verification failed — contact your integration manager |

    <Note>
      Prefer webhooks over polling in production. Configure your endpoint with your Ingo integration manager and handle `user.kyc.success` to avoid unnecessary polling.
    </Note>
  </Accordion>

  <Accordion title="Step 5 — Issue a routable bank account">
    Once `kyc_status` is `"verified"`, issue a routable bank account. The account receives real account and routing numbers capable of accepting external ACH transfers and wires.

    ```http theme={null}
    POST /api/v4/business/routable-bank-accounts/issue HTTP/1.1
    Host: api.sdev.banking.ingopayments.tech
    Authorization: hmac username="test", algorithm="hmac-sha512", ...
    Content-Type: application/json

    {
      "api_key": "YOUR_API_KEY",
      "user_id": "user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef"
    }
    ```

    Successful response:

    ```json theme={null}
    {
      "status": "success",
      "message": "operation completed",
      "data": {
        "routable_bank_account_id": "rbac-2b1c0e44-4f2d-9a11-7b23-cc90d1ef8f3a",
        "account_number": "XXXXXXXXXX",
        "routing_number": "XXXXXXXXX",
        "user_id": "user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef"
      }
    }
    ```

    <Warning>
      Attempting to issue an account before `kyc_status` is `"verified"` returns an `INVALID_STATE` error. Always confirm verification before proceeding.
    </Warning>
  </Accordion>
</AccordionGroup>

***

## What's next

<CardGroup cols={2}>
  <Card title="Business Onboarding" icon="building" href="/docs/banking/onboarding/create-business">
    The business KYB flow — create a business, add owners, upload documents, and submit for verification.
  </Card>

  <Card title="Internal Transfers" icon="arrows-right-left" href="/docs/banking/money/book-transfer">
    Move funds between entities within your program using book transfers.
  </Card>

  <Card title="Authentication" icon="lock" href="/docs/banking/authentication">
    Full two-layer auth guide — API key placement and HMAC-SHA512 signing.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/docs/banking/webhooks/overview">
    Real-time event notifications for KYC/KYB, account issuance, and transaction updates.
  </Card>
</CardGroup>