Skip to main content
Most issues can be resolved by reading the error response carefully, checking this documentation, and running through the self-help checklist below. When you do need to contact us, we want to help you quickly — and the information in this guide helps us do that.

​
Support Channels

Email Support

baas-support@unionbank.ngGeneral technical support, integration questions, and quota increase requests. Response within 1 business day.

Self-Service Portal

sandbox.api.unionbank.ngManage API keys, view webhook delivery history, review your KYB status, and submit production access requests — without contacting support.

Documentation

ubn.onecluster.coFull API reference, integration guides, tutorials, and this page. Search is available in the top bar.
For production incidents — a live outage, a payment stuck in PENDING, or a security concern — do not use the general support email. Email baas-incidents@unionbank.ng directly and prefix your subject line with P1: (service is down) or P2: (service is degraded). Incident emails are monitored outside business hours.

​
Before You Email Support

Most integration issues have a fast self-serve resolution. Run through this checklist before sending an email — in our experience, it resolves around 70% of reported issues.
Is the API returning a healthy status?
curl https://sandbox.api.unionbank.ng/health
# Expected: {"status": "healthy", "timestamp": "..."}
If the health endpoint is not returning healthy, there may be a platform incident in progress. Check the status page at sandbox.api.unionbank.ng/status before investigating your own integration.
Is your API key correct and not revoked?
Are you using the right key for the right environment?
A sandbox key will be rejected by the production API, and vice versa. Log in to the portal and confirm the key you are using is active and matches the environment (sandbox or production) you are calling.If you recently rotated your key, confirm that your deployed application is using the new key, not the old one.
Are you calling the correct base URL for your key type?
EnvironmentBase URL
Sandboxhttps://sandbox.api.unionbank.ng
Productionhttps://api.unionbank.ng
A common error is copying the sandbox URL into production configuration or vice versa.
Is your X-Signature header computed correctly?
Payment and KYC requests require an HMAC-SHA256 signature in the X-Signature header. If you receive a 401 Unauthorized on a signed endpoint, verify:
  • You are signing the exact request body that will be sent (not a reformatted or re-serialised version).
  • You are using your signing secret, not your API key.
  • The signature is hex-encoded, not base64.
  • You are not including extra whitespace or a trailing newline in the body before signing.
See the API Reference — Authentication page for the exact signing algorithm and a worked example.
Have you exceeded your rate limit? Check the X-Quota-Remaining header in your last response.
If X-Quota-Remaining is 0, you have exhausted your billing period quota and will receive 402 responses until the reset date shown in X-Quota-Reset.If you are receiving 429 Too Many Requests, you have hit the per-minute rate limit for that endpoint. Wait for Retry-After seconds and retry. See Rate Limits and Quotas for full details.

​
What to Include in a Support Request

When you do email support, include the following information in your first message. We cannot investigate without it — and missing information means a back-and-forth that delays your resolution.
1

Your Partner ID

Your Partner ID is shown in the portal under your account settings. It looks like PRT-0001. This is how we look up your account.
2

The X-Correlation-ID from the failed request

Every API response includes an X-Correlation-ID header. This is a unique identifier for that specific request in our logs. With this ID, we can find the exact request, the internal processing trace, and any error details — even if you only received a generic error message.If you do not have this header, include the timestamp of the request (as precise as possible, including timezone) and the endpoint you called.
3

The endpoint and request details

The full endpoint URL you called (e.g. POST /api/v1/payments/transfer), what you sent in the request body (redact any sensitive values like account numbers if needed), and the full response you received including the HTTP status code.
4

The error code and message

From the response body — the type, title, status, and detail fields. If you received a code field inside the error, include that too. See API Reference — Errors for the full list of error codes.
5

Your environment

Sandbox or production. We investigate them separately.
Template you can copy: 
Partner ID: PRT-XXXX
Environment: Sandbox / Production
Endpoint: POST /api/v1/payments/transfer
X-Correlation-ID: [value from response header]
Timestamp: 2026-03-25T14:32:00+01:00

Error received:
  HTTP Status: 422
  type: "https://errors.api.unionbank.ng/validation-error"
  title: "Validation Error"
  detail: "amount must be greater than 0"

What I expected to happen:
[describe the expected behaviour]

What happened instead:
[describe what actually happened]

​
Common Issues and Quick Fixes

Most likely cause: The API key is incorrect, revoked, or being sent in the wrong header format.The correct header format is:
Authorization: ApiKey YOUR_KEY_HERE
Note the ApiKey prefix — not Bearer, not Basic. Check that your code is building this header exactly.
Most likely cause: Missing or incorrect X-Signature header.Payment and KYC endpoints require HMAC-SHA256 request signing in addition to the API key. The API key authenticates who you are; the signature authenticates that the request body has not been tampered with. See API Reference — Authentication.
Most likely cause: A required field is missing or in the wrong format.Check the detail field in the error response — it names the specific field that failed validation. Common issues:
  • amount must be a positive integer in kobo (not naira). ₦100 is 10000.
  • bank_code must be a 3-digit string (e.g. "058", not 58).
  • account_number must be exactly 10 digits.
  • idempotency_key must be unique per transaction — reusing a key from a previous transaction will return the original response.
Checklist:
  1. Is your endpoint URL correct in the portal? Paste it into a browser to confirm it loads.
  2. Is your endpoint returning 2xx within 10 seconds? If it times out, the delivery is marked failed and retried.
  3. Are you testing locally? You need ngrok or a similar tunnel to receive webhooks on a local machine. See the Sandbox Guide.
  4. Check the webhook delivery history in the portal. It shows every attempted delivery, the HTTP status code your endpoint returned, and whether retries are scheduled.
Transfers via NIP should complete within 30 seconds. If a transfer remains PENDING for longer:
  1. Check the NIP network status at sandbox.api.unionbank.ng/status.
  2. Poll GET /api/v1/payments/{reference} for up to 5 minutes before treating it as a failure.
  3. If still PENDING after 5 minutes in production, email baas-incidents@unionbank.ng with the X-Correlation-ID and payment reference.
In the sandbox, transfers complete instantly. A stuck PENDING in the sandbox usually means the account number used is not a valid test account. Use 0123456789 / bank code 058 for reliable test transfers.
In the sandbox, BVN verification only returns a successful match for numbers starting with 222 (e.g. 22212345678). Any other number returns not found. This is intentional — it lets you test both your happy path and your error handling. See the Sandbox Guide for all test data values.

​
Escalation

PriorityCriteriaContactSubject Line Format
P1Complete service outage — production API returning 5xx, no payments processingbaas-incidents@unionbank.ngP1: [brief description]
P2Significant degradation — some endpoints failing, payment delays, webhook backlogbaas-incidents@unionbank.ngP2: [brief description]
P3General technical issue, integration question, non-urgent bugbaas-support@unionbank.ngStandard subject
P1 and P2 emails are monitored 24/7. P3 emails are handled during business hours (Monday to Friday, 8 AM to 6 PM WAT) with a target response time of 1 business day.