Quickstart: Your First API Call in 5 Minutes

This guide assumes nothing. If you’ve never called an API before, that’s fine. We’ll explain every step and every term as we go.

By the end of this guide you’ll have:

A registered sandbox account
A working API key
Made a real API call and seen a real response

Let’s go.

Step 1: Create your account

Go to ubn-ui.onecluster.co/auth/signup and fill in the registration form. What you’ll need:

Field	What to enter	Notes
Company name	Your registered business name	Must match your CAC certificate exactly
Email address	A corporate email (e.g. you@yourcompany.ng)	Free email services like Gmail will be rejected
Password	A strong password	Minimum 8 characters, at least one number and one symbol
Phone number	Your Nigerian mobile number	Format: +2348012345678
UBN account number	Your Union Bank account number	This links your partner account to your bank account
Terms & NDPR consent	Check both boxes	NDPR is Nigeria’s data protection law. You agree to handle customer data responsibly

The sandbox is completely free and uses no real money. You aren’t signing up for a paid service at this stage.

Once you submit the form, two things happen immediately:

Your account is created with the status PENDING_EMAIL_VERIFICATION
We send a one-time password (OTP) to the email address you provided

Keep the page open. You’ll need it in the next step.

Step 2: Verify your email

Check your inbox for an email from noreply@unionbank.ng. It contains a 6-digit OTP code (OTP stands for One-Time Password: a short code that expires after a few minutes and can only be used once, like a ticket with a time limit). Enter that code on the verification screen to confirm your email address. If the code doesn’t arrive within 2 minutes:

Check your spam or junk folder first. Automated emails sometimes land there. If it’s not there, click “Resend code” on the verification screen. Each new code invalidates the previous one.

If the code has expired: OTP codes expire after 10 minutes. If yours has expired, click “Resend code” to get a fresh one. Once your email is verified, your account status moves to PENDING_KYB_REVIEW. This means your documents are with our onboarding team for review. In sandbox, the review is fast, often within a few hours during business hours.

KYB stands for Know Your Business. It’s the process of verifying that your company is real and legitimate. Think of it as the due diligence a bank does before opening a business account. We explain it in full on the Onboarding: KYB Documents page.

Step 3: Get your sandbox API key

Once your account is approved, log in to the sandbox portal at ubn-ui.onecluster.co. Navigate to Settings → API Keys and click Generate sandbox key. You’ll see a key that looks like this:

ubn_sb_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

What is an API key? Think of an API key like a password for your application. Just as your email password proves that you are logging in to your email, an API key proves that your application is making a request to our API. Every request you send must include this key so we know it’s coming from you.

Copy your API key and store it somewhere safe immediately, like a password manager or your application’s environment variables. We only show the full key once. If you lose it, you’ll need to generate a new one and update all your code.Never paste your API key into a public place: not in a GitHub repo, not in a Slack message, not in a forum post. Anyone who has your key can make API calls on your behalf.

Sandbox keys always start with ubn_sb_. Production keys start with ubn_pk_. That makes it easy to tell them apart at a glance.

Step 4: Make your first API call

Now the fun part. You’re going to call the /health endpoint. It’s a simple check that confirms the API is online and your connection is working. What is curl? curl is a command-line tool for making web requests. Think of it like a web browser, except instead of showing you a webpage, it shows you the raw data the server sends back. It comes pre-installed on Mac, Linux, and Windows 10+. To check if you have it, open your terminal and type curl --version. What is a terminal? A terminal (also called a command prompt, shell, or console) is a text-based window where you type commands. On Mac, search for “Terminal” in Spotlight. On Windows, search for “Command Prompt” or “PowerShell”.

Option A: Using curl (command line)

Open your terminal, paste the command below, and replace ubn_sb_your_key_here with the actual key you generated in Step 3:

curl https://api-partner.onecluster.co/health \
  -H "Authorization: ApiKey ubn_sb_your_key_here"

The -H flag adds a header to your request. A header is extra information you attach to a request. In this case, you’re attaching your API key so the server knows who is asking.

Option B: Using JavaScript (fetch)

If you prefer JavaScript, paste this into your browser’s developer console or a Node.js script:

const apiKey = "ubn_sb_your_key_here"; // Replace with your actual key

const response = await fetch("https://api-partner.onecluster.co/health", {
  method: "GET",
  headers: {
    "Authorization": `ApiKey ${apiKey}`
  }
});

const data = await response.json();
console.log(data);

The response you should see

If everything is working, the /health endpoint responds with the text:

Healthy

The /health endpoint returns a plain-text response of Healthy. For detailed system status, call the /status endpoint instead. It returns a JSON breakdown:

{
  "status": "healthy",
  "gatewayVersion": "1.0.0",
  "downstreamBankingApi": "healthy"
}

Let’s read the /status response together:

"status": "healthy": The API gateway (the front door of the system) is online and accepting requests.
"gatewayVersion": "1.0.0": The version of the software running the gateway. Useful to know when reading release notes.
"downstreamBankingApi": "healthy": The connection between the gateway and Union Bank’s core banking system is working. If this said "degraded", payments might be slow. If it said "unhealthy", no transactions would be processing.

You just made your first successful API call. Welcome to UBN BaaS.

Step 5: What’s next

Open a Virtual Account

Create a real Nigerian bank account number for a customer or use case. This is usually the first thing partners build.

Send a Payment

Transfer money to any Nigerian bank account. Includes idempotency, retries, and real-time status updates.

Set Up Collections

Receive money from customers with dedicated collection accounts. Perfect for marketplaces and savings apps.

Verify an Identity

Check BVN, NIN, and CAC numbers to confirm your customers are who they say they are.

Having trouble?

I got a 401 Unauthorized error

This means your API key wasn’t recognised. Check:

Did you replace ubn_sb_your_key_here with your actual key?
Is there a typo or extra space in the key?
Is the header format exactly Authorization: ApiKey your_key_here (with a space between ApiKey and the key itself)?
Did you generate a sandbox key (starts with ubn_sb_)? Production keys won’t work in the sandbox environment.

I got a connection error or 'could not resolve host'

This is usually a network issue. Check:

Are you connected to the internet?
Is your company firewall blocking outbound HTTPS requests to api-partner.onecluster.co? Ask your IT team to whitelist this domain on port 443.
Try opening https://api-partner.onecluster.co/health in your web browser. If that fails too, the issue is your network, not your code.

I never received my verification email

Check your spam and junk folders.
Make sure you used a corporate email address. Gmail, Yahoo, and Outlook personal accounts are rejected at registration.
Wait 2 minutes and click “Resend code”.
If the email still doesn’t arrive after resending, contact baas-support@unionbank.ng with your registered email address and company name.

My account is stuck on PENDING_KYB_REVIEW

KYB (business document) review happens during business hours (Monday to Friday, 8am to 5pm WAT). If it’s been more than 1 business day since you submitted your documents, email baas-support@unionbank.ng. Include your Partner ID (shown in your dashboard) so we can locate your account quickly.

curl is not installed on my computer

On Mac: Open Terminal and type brew install curl (requires Homebrew).On Windows: curl is included with Windows 10 build 1803 and later. Open Command Prompt and type curl --version to check. If it’s not found, download it from curl.se/windows.On Linux: Run sudo apt install curl (Ubuntu/Debian) or sudo yum install curl (CentOS/RHEL).Alternatively, use the JavaScript example above. It runs in any browser.

I see a response but it doesn't match what you showed

If the status shows "degraded" or "unhealthy", there may be a temporary issue with one of our systems. Check api-partner.onecluster.co/status for a full breakdown, or visit our status page linked in the top navigation bar.

Still stuck? Email baas-support@unionbank.ng. Include the error message you received and the command or code you ran.

Getting Started

Onboarding

Products

Security & Compliance

Resources

Quickstart: Your First API Call in 5 Minutes

Step 1: Create your account

Step 2: Verify your email

Step 3: Get your sandbox API key

Step 4: Make your first API call

Option A: Using curl (command line)

Option B: Using JavaScript (fetch)

The response you should see

Step 5: What’s next

Open a Virtual Account

Send a Payment

Set Up Collections

Verify an Identity

Having trouble?

​Step 1: Create your account

​Step 2: Verify your email

​Step 3: Get your sandbox API key

​Step 4: Make your first API call

​Option A: Using curl (command line)

​Option B: Using JavaScript (fetch)

​The response you should see

​Step 5: What’s next

Open a Virtual Account

Send a Payment

Set Up Collections

Verify an Identity

​Having trouble?

Step 1: Create your account

Step 2: Verify your email

Step 3: Get your sandbox API key

Step 4: Make your first API call

Option A: Using curl (command line)

Option B: Using JavaScript (fetch)

The response you should see

Step 5: What’s next

Having trouble?