Named accounts and inbound credits

Bind a partner’s account number to a wallet, and record what arrives.

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.