Named accounts and inbound credits

A named account is a partner-side address for a ledger account, not a separate balance. The customer’s money is a liability on the ledger, and the same money sits in the partner’s pool, mirrored by your settlement account.

Open the account at the partner

You open the account with the partner, using the customer’s BVN or NIN, because PanoQore holds no personal data. Then you bind the number.

Connect a partner

GET /v1/partners lists the tenant’s partners and each one’s mode.

Mode	How credits arrive
`LEDGER_ONLY`	Your code talks to the partner, and reports each credit.
`FULL`	PanoQore takes the partner’s notices and confirms each with the partner.

You need two accounts for each partner and currency, using the partner’s code. For Safehaven, that is AST:SET:NGN:SHV for settlement and LIA:SUS:NGN:SHV for suspense.

Bind a number

Binding needs named:write. Only a wallet can be bound.

curl -X POST "$PANOQORE_URL/v1/accounts/$WALLET/named-accounts:bind" \
  -H "Authorization: Bearer $PANOQORE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"partner":"safehaven","accountNumber":"0123456789","accountName":"Ada Stores"}'

{
  "id": "nam_01M6F1CJAPF7Q9SFKR49QYM6CJ",
  "accountId": "acc_01M6F1BK8KE6JT32WRN50HYC4R",
  "accountLabel": "First wallet",
  "partner": "safehaven",
  "partnerName": "Safehaven MFB",
  "accountNumber": "0123456789",
  "bankCode": "090286",
  "accountName": "Ada Stores",
  "currency": "NGN",
  "status": "ACTIVE"
}

The number is 6 to 34 digits. In FULL mode, PanoQore first checks with the partner that the number is an open account under your credentials, and uses the partner’s name for it. A number can be bound once, and a wallet can have one open binding at each partner. Changing a binding is console work with approval. For a new number, close the binding and bind the new one.

Record a credit

In LEDGER_ONLY mode, report each credit the partner tells you about. This needs named:write or entries:write, and takes no Idempotency-Key: it is idempotent on externalId, the partner’s transaction id.

curl -X POST "$PANOQORE_URL/v1/partners/safehaven/credits" \
  -H "Authorization: Bearer $PANOQORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalId":"000013261005091207","accountNumber":"0123456789","amount":"250000","currency":"NGN","fromName":"A Sender"}'

{
  "externalId": "000013261005091207",
  "entryId": "je_01M6F1CJEPF8TR2A854N7G76RY",
  "fromName": "A Sender",
  "source": "API",
  "result": "CREDITED",
  "amount": "250000",
  "currency": "NGN",
  "accountNumber": "0123456789",
  "namedAccountId": "nam_01M6F1CJAPF7Q9SFKR49QYM6CJ"
}

The entry debits settlement and credits the wallet, with kind: TRANSFER_IN.

`result`	Meaning
`CREDITED`	The wallet was credited.
`DUPLICATE`	This `externalId` was seen before. Nothing posted, and the answer describes the first credit.
`QUARANTINED`	The money went to the suspense account. `reason` says why.

Quarantine

The settlement account moves on every credit, because the money is at the partner whatever else is true. The other side goes to suspense when the number is unbound, the binding is not active, the wallet is not active, or the currency differs. It is never credited to a default account.

{ "result": "QUARANTINED", "amount": "7000", "accountNumber": "0999999999", "reason": "No named account is bound to this number." }

A quarantined credit opens a reconciliation break of kind UNBOUND_CREDIT, and a person places the money by an approved adjustment. See Reconciliation. In FULL mode this call is refused with INTEGRATION_MODE_FULL.

Look up

curl "$PANOQORE_URL/v1/named-accounts/safehaven/0123456789" -H "Authorization: Bearer $PANOQORE_API_KEY"
curl "$PANOQORE_URL/v1/named-accounts/$NAMED/credits" -H "Authorization: Bearer $PANOQORE_API_KEY"

A closed binding does not resolve.

Get started

Using the API

Concepts

Guides

Named accounts and inbound credits

Open the account at the partner

Connect a partner

Bind a number

Record a credit

Quarantine

Look up

​Open the account at the partner

​Connect a partner

​Bind a number

​Record a credit

​Quarantine

​Look up

Open the account at the partner

Connect a partner

Bind a number

Record a credit

Quarantine

Look up