Fund Wallet Account

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
}

{
    "status": "true",
    "message": "Charge attempted",
    "reference": "TX-5X3WSN9A3DD00V55DK72RT",
    "link": "",
    "2faEnable": false
}

{
  "message": "Invalid amount or missing parameters",
  "success": false
}

{
  "message": "Invalid or missing API key",
  "success": false
}

{
  "message": "Unable to generate hosted link",
  "success": false
}

POST

api

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
}

{
    "status": "true",
    "message": "Charge attempted",
    "reference": "TX-5X3WSN9A3DD00V55DK72RT",
    "link": "",
    "2faEnable": false
}

{
  "message": "Invalid amount or missing parameters",
  "success": false
}

{
  "message": "Invalid or missing API key",
  "success": false
}

{
  "message": "Unable to generate hosted link",
  "success": false
}

string

required

Unique identifier for the subaccount account wallet.

number

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

string

A unique identifier for the funding transaction.

string

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

string

Currency of transaction.

string

This is passed to provider to redirect your users.

string

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

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": "true",
    "message": "Charge attempted",
    "reference": "TX-5X3WSN9A3DD00V55DK72RT",
    "link": "",
    "2faEnable": false
}

{
  "message": "Invalid amount or missing parameters",
  "success": false
}

{
  "message": "Invalid or missing API key",
  "success": false
}

{
  "message": "Unable to generate hosted link",
  "success": false
}

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.

Wallet API(s)

Transfer API(s)

Misc

Status Codes

Notes

Best Practices

​Status Codes

​Notes

​Best Practices

Status Codes

Notes

Best Practices