Super-admin · reference

Ecobank relay

Checking…

Relay is noauth & temporary — production still needs Sikafon's own direct connection.

The path a call takes

Every operation follows the same four hops out and back. Our IP never touches Ecobank — the relay forwards from its whitelisted address.

Origin

Sikafon app

Web & mobile — verify, apply, agent, home.

Our API

Sikafon service

Maps KYC → the wrapper's wire fields.

Relay

bibiaaai.com

Whitelisted server. Forwards from an IP Ecobank's WAF trusts.

Bank

Ecobank core

Opens accounts, moves money, mints every reference.

← On the way back, every hop returns the same envelope: success + data.ecobank.header{ responsecode, responsemessage, requestId } + the payload. Our adapter reads the inner responsecode and classifies it with the same table the direct connection uses.

Why opening an account is two calls

The single most important operational detail — and the reason the reference number is load-bearing.

1 · Open — get the reference

open-account-api returns Ecobank's accountRefNo almost at once. The real accountNo is usually still empty — Ecobank verifies KYC asynchronously.

application → ecobank_pending

2 · Reconcile — resolve the number

A background sweep asks check-account-api with that reference. When Ecobank answers with the accountNo, we link it to the @handle.

application → opened

The reference is the only handle to a pending account. Capture it and the opening always resolves; lose it and there is nothing to reconcile by (we fall back to our own requestId). This never resubmits an opening — an ambiguous answer is frozen and re-checked, never retried.

The envelope & the codes

Every endpoint answers in this shape. The response below is an actual find-account reply from the relay.

{
  "success": true,
  "message": "Account retrieved successfully",
  "data": {
    "ecobank": {
      "header": {
        "requestId":       "478294620",
        "responsecode":    "000",
        "responsemessage": "SUCCESS"
      },
      "customername": "Ansuaa Jennifer "
    }
  }
}

000 · 001Success — account opened, money moved, name matched.

403Denied — a refusal, e.g. a selfie that did not match the card.

E11Pending — “CBA timeout, use status inquiry”. Freeze & reconcile, never resubmit.

(no code)Falls back to the wrapper's success flag + HTTP status.

transportLOCAL_TRANSPORT — no/garbled reply. Reconcile, not a silent fail.

The endpoints, field by field

All POST, all noauth. Six wrapper endpoints plus add-account (mapped, not yet surfaced). Empty values are sent as empty strings — shown, not hidden.

01/verify-card-apiPOSTmultipart/form-dataLiveverifyCard()

Selfie ↔ Ghana Card 1:1 identity match — runs before any account is opened. The only multipart call; the selfie rides as a file part.

▸ Sikafon sends

card_norequired

Ghana Card number

issue_daterequired

card issue date · YYYY-MM-DD

expiry_daterequired

card expiry date · YYYY-MM-DD

id_typeconstant

defaults to "Ghana Card"

first_namerequired

applicant first name

last_namerequired

applicant last name

live_selfierequired

selfie image · jpeg/png file

◂ Ecobank returns

header.responsecodeEcobank mints

000 = match · 403 = no match

header.responsemessageEcobank mints

the bank's words

header.requestIdEcobank mints

Ecobank request id

customernameEcobank mints

the name NIA/Ecobank holds for the card

↳ verified is taken from the outcome bucket, never guessed from a field — a transport failure reads as “could not verify”, not a denied match.

02/open-account-apiPOSTapplication/jsonLivecreateAccount()

Opens a REAL Ecobank account. Returns the reference at once; the account number resolves later (see the two-step below).

▸ Sikafon sends

first_namerequired

applicant first name

last_namerequired

applicant last name

middle_namesent empty ''

sent as "" when absent

phonenormalised

mobile — normalised 0244…→233…

emailsent empty ''

sent as "" when absent

sexnormalised

gender — M→MALE, F→FEMALE

addresssent empty ''

sent as "" when absent

card_idrequired

Ghana Card number

dobrequired

date of birth · YYYY-MM-DD

◂ Ecobank returns

accountRefNoEcobank mints

customer/account reference — comes back FIRST

accountNoEcobank mints

the real account number — usually EMPTY here, resolved later

header.responsecodeEcobank mints

bank verdict

header.requestIdEcobank mints

request id

↳ On accountRefNo the application becomes ecobank_pending; the number is filled in later by reconcile. Both empty ⇒ still pending, never failed.

03/check-account-apiPOSTapplication/jsonLive · resolvergetAccount()

“Sync account.” Give it the reference, it returns the real account number. This is how a pending opening turns into an opened one.

▸ Sikafon sends

account_numberrequired

the accountRefNo — a reference OR an account

◂ Ecobank returns

accountNoEcobank mints

the resolved real account number

statusderived

we derive ACTIVE / UNKNOWN from success

header.responsecode / responsemessageEcobank mints

bank verdict

↳ When accountNo comes back we link it to the @handle and flip the application to opened.

04/find-account-apiPOSTapplication/jsonRead-onlygetCustomerDetails() · nameInquiry()

Name lookup — the exact call that returned real “Ansuaa Jennifer”. Confirms who a number belongs to; moves nothing.

▸ Sikafon sends

account_numberrequired

account or reference number

◂ Ecobank returns

customernameEcobank mints

the account-holder name Ecobank holds

header.requestIdEcobank mints

request id

header.responsecode / responsemessageEcobank mints

bank verdict

↳ Surfaced two ways — full customer details, and a trimmed name inquiry for transfer name-checks.

05/new-transaction-apiPOSTapplication/jsonReal money · GHS 10 capcashIn() · withdrawal()

Moves REAL money — CASH_IN or CASH_OUT. Refused above the GHS 10 relay ceiling before it ever reaches the wire.

▸ Sikafon sends

amountrequired

the amount — capped at GHS 10

account_norequired

the customer account

phonenormalised

third-party (cash-in) / sender (cash-out) — normalised

senderphonenormalised

same number, normalised

sendernamesent empty ''

"" for cash-in · sender name for cash-out

transconstant

"CASH_IN" or "CASH_OUT"

◂ Ecobank returns

externalrefnoEcobank mints

the transaction reference

cbareferenceno · reference · requestIdEcobank mints

fallbacks when externalrefno is absent

header.responsecodeEcobank mints

E11 = timeout → PENDING, freeze & reconcile

↳ Receipt = refno + SUCCESS / PENDING / FAILED from the outcome bucket. An ambiguous code freezes as pending and is never resubmitted.

06/add-account-apiPOSTapplication/jsonMapped · not wiredaddExistingAccount()

Links an EXISTING Ecobank account to a customer. No card, no DOB — the account is already KYC'd. Coded in the adapter; no screen calls it yet.

▸ Sikafon sends

first_namerequired

account holder first name

last_namerequired

account holder last name

middle_namesent empty ''

sent as "" when absent

phonenormalised

normalised 0244…→233…

account_numberrequired

the EXISTING Ecobank account

◂ Ecobank returns

success / messageEcobank mints

raw envelope — passed straight through

header.responsecode / responsemessageEcobank mints

bank verdict

↳ Returned raw. This is the “bring your existing Ecobank account” path — waiting on a decision to surface it in the app.

What we supply · what only Ecobank can give

The clean answer to "are there other details we must have?" — yes, and here is which side each comes from.

We must supply

From the person + their Ghana Card. Without these we cannot make the call.

first_namelast_namedobcard_idphonesexissue_dateexpiry_datelive_selfiemiddle_nameemailaddress

Only Ecobank mints

Generated on the bank's side. We hold and reconcile them — never create, guess, or fake them.

accountRefNoaccountNoexternalrefnorequestIdcustomernameresponsecode

Source of truth: services/api/src/ecobank/bibia.ts and the Sikafon-Eco Postman collection. The relay forwards only these operations; every other bank capability returns a clean, money-safe denial until Sikafon's direct connection lands.

Loading the console

{ "success": true, "message": "Account retrieved successfully", "data": { "ecobank": { "header": { "requestId": "478294620", "responsecode": "000", "responsemessage": "SUCCESS" }, "customername": "Ansuaa Jennifer " } } }