> ## Documentation Index
> Fetch the complete documentation index at: https://docs.panoqore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
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"}'
```

```json theme={null}
{
  "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.

```bash theme={null}
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"}'
```

```json theme={null}
{
  "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.

```json theme={null}
{ "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](https://docs.panoqore.com/guides/reconciliation.md).

In `FULL` mode this call is refused with `INTEGRATION_MODE_FULL`.

## Look up

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.