POST
/
api
/
v1
/
wallets
/
account
/
{accountWalletId}
/
fund
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"
}'
{
  "status": "true",
  "message": "Authorization URL created",
  "reference": "TX-3WW0SR5EZ5A0P0HXD2CJH5",
  "link": "https://checkout.paystack.com/wmrhuc99fpiajsv",
  "2faEnable": false
}
​
accountWalletId
string
required

Unique identifier for the subaccount account wallet.

​
amount
number

The amount to be funded into the wallet account (in the smallest currency unit if required by the provider).

​
reference
string

A unique identifier for the funding transaction.

​
description
string

A short description or note for the transaction (e.g., “Wallet top-up”).

​
currency
string

Currency of transaction.

​
redirectUrl
string

This is passed to provider to redirect your users.

​
transactionType
string

This is optional but it is required for direct charge request. value: direct_debit

​
mandateReference
string
required

This is optional but it is required for direct charge request. A unique identifier to indicate the mandate to perform direct charge on.

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"
}'
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"
}'
{
  "status": "true",
  "message": "Authorization URL created",
  "reference": "TX-3WW0SR5EZ5A0P0HXD2CJH5",
  "link": "https://checkout.paystack.com/wmrhuc99fpiajsv",
  "2faEnable": false
}

​
Status Codes

CodeDescription
200Checkout link generated successfully
400Validation error or missing parameters
401Unauthorized or invalid API key
500Internal 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.