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

# Fund & Debit

> Credit and debit customer wallets, and retrieve merchant wallet balances.

## Credit a customer wallet

`POST /wallet/credit`

Transfers funds from your merchant settlement wallet to a customer wallet. The merchant wallet is debited the transfer amount plus any applicable wallet-to-wallet transfer fees.

<Note>
  The customer wallet must be `ACTIVE` and must not have post-no-credit (PNC) mode enabled. Credits are also subject to the customer's tier maximum balance limit — if the credit would push the wallet over its tier cap, the request is rejected.
</Note>

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token.
</ParamField>

<ParamField body="customerId" type="string" required>
  The UUID of the customer whose wallet you are crediting.
</ParamField>

<ParamField body="amount" type="number" required>
  Amount to credit, in kobo. Must be greater than 0.
</ParamField>

<ParamField body="reference" type="string">
  Your unique transaction reference. If omitted, one is auto-generated. Minimum 10 characters. Duplicate references are rejected.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value data attached to the transaction. Returned in webhook payloads.
</ParamField>

### Response

<ResponseField name="status" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string">
  `"Transaction successfully completed."` or `"Transaction successfully submitted for approval."` (for web-initiated requests that require maker-checker approval).
</ResponseField>

<ResponseField name="data" type="object">
  Present on successful API-initiated transactions.

  <Expandable title="data properties">
    <ResponseField name="amount" type="number">
      Amount credited to the customer wallet in kobo.
    </ResponseField>

    <ResponseField name="reference" type="string">
      Transaction reference.
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      Customer UUID.
    </ResponseField>

    <ResponseField name="customer_wallet_id" type="string">
      Customer wallet UUID.
    </ResponseField>

    <ResponseField name="transaction_fee" type="number">
      Fee charged to the merchant for this transfer, in kobo.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Your metadata if provided.
    </ResponseField>
  </Expandable>
</ResponseField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.tagpay.ng/v1/wallet/credit \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
      "amount": 500000,
      "reference": "REF-CREDIT-20240501-001",
      "metadata": { "orderId": "ORD-999" }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.tagpay.ng/v1/wallet/credit", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customerId: "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
      amount: 500000,
      reference: "REF-CREDIT-20240501-001",
      metadata: { orderId: "ORD-999" },
    }),
  });

  const data = await response.json();
  ```
</CodeGroup>

```json Response theme={null}
{
  "status": true,
  "message": "Transaction successfully completed.",
  "data": {
    "amount": 500000,
    "reference": "REF-CREDIT-20240501-001",
    "customer_id": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "customer_wallet_id": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transaction_fee": 0,
    "metadata": { "orderId": "ORD-999" }
  }
}
```

***

## Debit a customer wallet

`POST /wallet/debit`

Withdraws funds from a customer wallet and credits them to your merchant settlement wallet. The net amount received by the merchant is the debited amount minus any applicable transfer fees.

<Warning>
  Customer debit must be explicitly enabled on your merchant account. If `canDebitCustomer` is `false`, all debit requests return an error. Contact TagPay support to enable this feature.
</Warning>

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token.
</ParamField>

<ParamField body="customerId" type="string" required>
  The UUID of the customer whose wallet you are debiting.
</ParamField>

<ParamField body="amount" type="number" required>
  Amount to debit, in kobo. Must be greater than 0.
</ParamField>

<ParamField body="reference" type="string">
  Your unique transaction reference. Minimum 10 characters. Duplicate references are rejected.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value data attached to the transaction.
</ParamField>

### Response

<ResponseField name="status" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string">
  `"Transaction successfully completed"` on success.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data properties">
    <ResponseField name="amount" type="number">
      Amount debited from the customer wallet in kobo.
    </ResponseField>

    <ResponseField name="reference" type="string">
      Transaction reference.
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      Customer UUID.
    </ResponseField>

    <ResponseField name="customer_wallet_id" type="string">
      Customer wallet UUID.
    </ResponseField>

    <ResponseField name="transaction_fee" type="number">
      Fee deducted from the debited amount before crediting the merchant wallet.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Your metadata if provided.
    </ResponseField>
  </Expandable>
</ResponseField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.tagpay.ng/v1/wallet/debit \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
      "amount": 200000,
      "reference": "REF-DEBIT-20240501-001"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.tagpay.ng/v1/wallet/debit", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customerId: "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
      amount: 200000,
      reference: "REF-DEBIT-20240501-001",
    }),
  });

  const data = await response.json();
  ```
</CodeGroup>

```json Response theme={null}
{
  "status": true,
  "message": "Transaction successfully completed",
  "data": {
    "amount": 200000,
    "reference": "REF-DEBIT-20240501-001",
    "customer_id": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "customer_wallet_id": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transaction_fee": 0,
    "metadata": null
  }
}
```

***

## Get merchant wallet balances

`GET /wallet/balance`

Returns the total combined balance across all customer wallets under your merchant account. This is the sum of `availableBalance` for every customer wallet.

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token.
</ParamField>

### Response

<ResponseField name="status" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data properties">
    <ResponseField name="totalBalance" type="number">
      Total available balance across all customer wallets, in kobo.
    </ResponseField>
  </Expandable>
</ResponseField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.tagpay.ng/v1/wallet/balance" \
    -H "Authorization: Bearer <token>"
  ```
</CodeGroup>

```json Response theme={null}
{
  "status": true,
  "data": {
    "totalBalance": 4750000
  }
}
```

***

## Get settlement balance

`GET /wallet/settlement-balance`

Returns the total unsettled balance owed to customers — the difference between `bookedBalance` and `availableBalance` across all customer wallets. Use this before calling `POST /wallet/settle-customer-balance` to understand how much you need to fund.

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token. Requires `MANAGE_BALANCE_SETTLEMENT` permission.
</ParamField>

### Response

<ResponseField name="status" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="balance" type="number">
  Total pending settlement amount in kobo.
</ResponseField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.tagpay.ng/v1/wallet/settlement-balance" \
    -H "Authorization: Bearer <token>"
  ```
</CodeGroup>

```json Response theme={null}
{
  "status": true,
  "balance": 850000
}
```

***

## Settle customer balances

`POST /wallet/settle-customer-balance`

Transfers funds from your merchant settlement wallet to cover the outstanding balances of all customers who have a `bookedBalance` greater than their `availableBalance`. Settlement is processed smallest-balance-first until your merchant wallet is exhausted.

<Warning>
  This is an irreversible batch operation. Ensure your merchant wallet has sufficient funds before calling this endpoint. Check the settlement balance first using `GET /wallet/settlement-balance`.
</Warning>

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token. Requires `MANAGE_BALANCE_SETTLEMENT` permission.
</ParamField>

### Response

<ResponseField name="status" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string">
  `"Your customers wallet has been settled"`
</ResponseField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.tagpay.ng/v1/wallet/settle-customer-balance \
    -H "Authorization: Bearer <token>"
  ```
</CodeGroup>

```json Response theme={null}
{
  "status": true,
  "message": "Your customers wallet has been settled"
}
```

***

## Error responses

| HTTP Status | Description                                         |
| ----------- | --------------------------------------------------- |
| `400`       | Reference already exists                            |
| `400`       | Insufficient balance in merchant or customer wallet |
| `400`       | Customer wallet is inactive or not found            |
| `400`       | Post-no-credit is enabled on beneficiary wallet     |
| `400`       | Daily transaction limit exceeded                    |
| `400`       | Tier max balance would be exceeded                  |
| `400`       | Customer debit not enabled for this merchant        |
| `401`       | Missing or invalid authentication token             |
| `403`       | Insufficient permissions                            |

```json 400 Insufficient Balance theme={null}
{
  "status": false,
  "message": "Insufficient balance to complete this transaction"
}
```

```json 400 Post-No-Credit Enabled theme={null}
{
  "status": false,
  "message": "Post no credit has been enabled on the beneficiary account. Kindly reachout to support for help."
}
```