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

# Fund Wallet Account

> Initiate a fund transaction for a wallet account and get a hosted payment link.

<ParamField path="accountWalletId" type="string" required="true">
  Unique identifier for the subaccount account wallet.
</ParamField>

<ParamField body="amount" type="number">
  The amount to be funded into the wallet account (in the smallest currency unit if required by the provider).
</ParamField>

<ParamField body="reference" type="string">
  A unique identifier for the funding transaction.
</ParamField>

<ParamField body="description" type="string">
  A short description or note for the transaction (e.g., "Wallet top-up").
</ParamField>

<ParamField body="currency" type="string">
  Currency of transaction.
</ParamField>

<ParamField body="redirectUrl" type="string">
  This is passed to provider to redirect your users.
</ParamField>

<ParamField body="transactionType" type="string">
  This is optional but it is required for direct charge request.  value: `direct_debit`
</ParamField>

<ParamField body="mandateReference" type="string" required="true">
  This is optional but it is required for direct charge request.
  A unique identifier to indicate the mandate to perform direct charge on.
</ParamField>

<RequestExample>
  ```bash Example Request theme={null}
  curl --location 'https://api.recital.finance/api/wallets/account/accountWalletId/fund' \
  --header 'Authorization: Bearer apiKey' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "amount": 100,
    "reference": "a",
    "currency": "NGN",
    "description": "test",
    "redirectUrl": "https://webhook.site/8f66fadd-4a9d-4e4c-bf1a-9463c3ee097f"
  }'
  ```
</RequestExample>

<RequestExample>
  ```bash Direct Charge Example Request theme={null}
  curl --location --request POST 'https://api.recital.finance/api/v1/wallets/account/{accountWalletId}/fund' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --data-raw '{
      "amount": "10000",
      "reference": "tbdzh85tfreee",
      "description": "test",
      "currency": "NGN",
      "redirectUrl": "https://google.com",
      "transactionType": "direct_debit",
      "mandateReference": "bpkaadfafahbf0"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "status": "true",
    "message": "Authorization URL created",
    "reference": "TX-3WW0SR5EZ5A0P0HXD2CJH5",
    "link": "https://checkout.paystack.com/wmrhuc99fpiajsv",
    "2faEnable": false
  }
  ```

  ```json Direct charge Success Response theme={null}
  {
      "status": "true",
      "message": "Charge attempted",
      "reference": "TX-5X3WSN9A3DD00V55DK72RT",
      "link": "",
      "2faEnable": false
  }
  ```

  ```json Invalid amount Response theme={null}
  {
    "message": "Invalid amount or missing parameters",
    "success": false
  }
  ```

  ```json Invalid API key Response theme={null}
  {
    "message": "Invalid or missing API key",
    "success": false
  }
  ```

  ```json Unable to generate hosted link theme={null}
  {
    "message": "Unable to generate hosted link",
    "success": false
  }
  ```
</ResponseExample>

### Status Codes

| Code  | Description                                       |
| ----- | ------------------------------------------------- |
| `200` | Checkout link generated successfully              |
| `400` | Validation error or missing parameters            |
| `401` | Unauthorized or invalid API key                   |
| `500` | Internal error occurred while generating the link |

***

### Notes

* The returned `link` is a hosted payment page where the user can complete funding using available payment options.
* You must capture the `reference` to track and confirm the transaction status later via webhook or API.
* For `direct charge` success response, when `2faEnable` is true this indicate that 2FA is required to complete direct charge by the bank.
  This is only applicable to all banks that have 2FA enable for direct charge.
* For `direct charge` success response, when `2faEnable` is true, `link` will have return a hosted authorization page where users can perform 2FA.

***

### Best Practices

✅ Always use a unique `reference` for each transaction.\
✅ Store the returned `link` and redirect users to it immediately for payment.\
✅ Use webhooks to listen for transaction status updates from the provider.