Skip to main content
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.
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 for the full signing guide.
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.

​
Environments

EnvironmentBase URL
Sandboxhttps://api.sdev.banking.ingopayments.tech/api/v4
Productionhttps://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

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:
{
  "api_key": "YOUR_API_KEY",
  ...
}
Then sign the request using HMAC-SHA512. The signing process is identical to the IngoPay API — see Authentication for the full step-by-step guide.
Requests that pass the API key but fail signature verification are rejected at the gateway before reaching the API.
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.
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:
{
  "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.
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.
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:
{
  "status": "success",
  "message": "operation completed",
  "data": {
    "user_id": "user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef",
    "kyc_status": "in_review"
  }
}
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".
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:
{
  "status": "success",
  "message": "operation completed",
  "data": {
    "user_id": "user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef",
    "kyc_status": "verified"
  }
}
kyc_statusMeaning
not_startedVerification not yet submitted
in_reviewSubmitted, awaiting result
verifiedConfirmed — entity can receive accounts
failedVerification failed — contact your integration manager
Prefer webhooks over polling in production. Configure your endpoint with your Ingo integration manager and handle user.kyc.success to avoid unnecessary polling.
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.
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:
{
  "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"
  }
}
Attempting to issue an account before kyc_status is "verified" returns an INVALID_STATE error. Always confirm verification before proceeding.

​
What’s next

Business Onboarding

The business KYB flow — create a business, add owners, upload documents, and submit for verification.

Internal Transfers

Move funds between entities within your program using book transfers.

Authentication

Full two-layer auth guide — API key placement and HMAC-SHA512 signing.

Webhooks

Real-time event notifications for KYC/KYB, account issuance, and transaction updates.