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

# Wallets

> Understand Payfonte wallet types, balances, and operational actions for collections and disbursements.

Payfonte assigns wallets per merchant and market to separate collection inflows from disbursement outflows.

## Wallet Types

<CardGroup cols={2}>
  <Card title="Collection Wallet (Deposit)" icon="arrow-down">
    Incoming payment funds are settled here first. Use this wallet as your primary collection balance.
  </Card>

  <Card title="Disbursement Wallet (Disbursement)" icon="arrow-up">
    Disbursement and transfers are deducted from this wallet when you run disbursements.
  </Card>
</CardGroup>

## Wallet Status

Wallets can appear in these states:

| Status          | Meaning                                                           |
| --------------- | ----------------------------------------------------------------- |
| `active`        | Wallet can receive and send funds based on configured operations. |
| `post-no-debit` | Wallet can receive funds, but outgoing debits are blocked.        |

<Info>
  `post-no-debit` is commonly used as a safety control when credentials or disbursement controls may be compromised.
</Info>

## Wallet Operations

<AccordionGroup>
  <Accordion title="Transfer funds between wallets" icon="right-left" defaultOpen>
    Move funds from collection wallet to disbursement wallet when you need disbursement liquidity.
  </Accordion>

  <Accordion title="Suspend outgoing activity" icon="shield-halved">
    Apply a suspend/post-no-debit control to stop outgoing deductions while investigations or security checks are ongoing.
  </Accordion>

  <Accordion title="Resume normal operations" icon="circle-check">
    Remove restrictions when controls are restored and your account is verified as safe.
  </Accordion>
</AccordionGroup>

## Fetch Wallet Balances via API

Use the wallet endpoint to query current balances by `country` and `currency`.

```bash theme={null}
curl --location 'https://api.payfonte.com/billing/v1/wallets?country=NG&currency=NGN' \
  --header 'client-id: <your-client-id>' \
  --header 'client-secret: <your-client-secret>'
```

Sample response shape:

```json theme={null}
{
  "data": [
    {
      "type": "deposit",
      "amount": 1250000,
      "currency": "NGN",
      "country": "NG",
      "status": "active"
    },
    {
      "type": "disbursement",
      "amount": 500000,
      "currency": "NGN",
      "country": "NG",
      "status": "active"
    }
  ]
}
```

## Recommended Workflow

<Steps>
  <Step title="Monitor collection inflow">
    Track funds entering your deposit/collection wallet after successful transactions.
  </Step>

  <Step title="Fund disbursement wallet proactively">
    Transfer enough balance to disbursement wallet before high-volume disbursement runs.
  </Step>

  <Step title="Alert on low disbursement balance">
    Set internal alerts so disbursement operations do not fail due to insufficient wallet funds.
  </Step>

  <Step title="Apply security controls quickly">
    If compromise is suspected, suspend outgoing wallet operations and rotate credentials immediately.
  </Step>
</Steps>

## Related Docs

<CardGroup cols={3}>
  <Card title="Authorization" icon="key" href="/en/guides/introductions/authorization">
    Secure wallet API calls with required headers.
  </Card>

  <Card title="Disbursements" icon="money-bill-transfer" href="/en/guides/disbursements/overview">
    Learn disbursement flows that use your disbursement wallet.
  </Card>

  <Card title="API Reference" icon="file-code" href="/en/api-reference/introduction">
    Full endpoint details for wallet queries.
  </Card>
</CardGroup>