Fund a Wallet

Run in Postman

Use the Fund Wallet request to fund a digital wallet through your application.

Supported funding sources

Fund a wallet using any of the following methods:

Method	Description
Prefunding	Transfer money to the wallet before a transaction settles or immediately when the financial institution processes funds. Use any source or destination currency.
Bank transfer	Transfer funds to a bank account.
Card	Use a debit or credit card to fund the wallet. Must be enabled by Nium. Source and destination currency must be the same.
Direct debit	Set up automatic transfers from a customer’s bank account to their wallet. Must be enabled by Nium.

Wallets can be funded by yourself, third-parties, or your own customers. Contact Nium Support or your account manager for details on what funding channels are available for you.

note

• For prefunding, source and destination currencies can differ.
• For bank transfer and card, both currencies must be the same.

Self-fund wallet

Fund a wallet from your own financial institution. Start by creating a Virtual Account Number (VAN).

1. Use the Fetch Client Details request to confirm which currencyCode and bankName values are available.
2. Use the Assign Payment ID request to create a paymentId.
   • The paymentId represents your VAN.
   • Include the currencyCode and bankName you want the paymentId to use.
3. Fetch the VAN details using the Fetch Virtual Account Details V2 request.

After you’ve created a VAN:

1. Transfer funds through from your financial institution to your Nium wallet using the VAN details.
2. Nium's financial institution confirms the credit through Inward Credit Confirmation (ICC). An authorization code (authCode) is returned once the transfer begins.
3. Use the authCode to fetch the transaction using the Fetch Transactions request. When complete:
   • status is Approved
   • complianceStatus is Settled

Third-party funds wallet

Accept wallet funding from a customer, partner, vendor, or other external account. Start by creating a Virtual Account Number (VAN):

1. Use the Fetch Client Details request to confirm which currencyCode and bankName values are available.
2. Use the Assign Payment ID request to create a paymentId.
   • The paymentId represents your VAN.
   • Include the desired currencyCode and bankName.
3. Fetch the VAN using the Fetch Virtual Account Details V2 request.

After the VAN is shared:

1. The third party sends funds to your wallet using the VAN details.
2. Nium's financial institution confirms the credit through ICC, and an authCode is returned.
3. Use the authCode with the Fetch Transactions request to fetch the status of the transfer.
   • When complete:
     • status is Approved
     • complianceStatus is Settled
   • If webhooks are configured, you also receive the Wallet Funded webhook on success.

Fund wallet using a card

To fund a wallet using a card, after a successfully completing onboarding through Electronic Know Your Customer (eKYC):

1. Call the Fund Wallet request using a debit or credit card as the funding method.
2. Nium provides a returnUrl to complete 3D Secure One-Time Password (3DS OTP) verification.
   • If 3DS fails, the transaction is restarted.
   • If successful, you get redirected the customer to your predefined return URL.

URL format:

https://<client_URL>/wallet/fund/{systemReferenceNumber}

3. Use the Fetch Transactions request with the systemReferenceNumber={authCode} query parameter. Include the authCode returned through ICC.
   • If the status is Approved or Declined, the transaction ends.
   • If the status is Pending, wait for the Wallet Funding webhook to confirm the transfer.

FAST and PayNow

Use Fast And Secure Transfers (FAST) or PayNow to instantly fund a wallet.

Fund wallet using direct debit

For details on how to fund a wallet using direct debit, see Direct Debit.

Funding wallets around the world

Funding flows around the world can differ depending on the country and local currency. The following highlights important regional requirements for wallet funding.

Brazil

Nium enables clients and corporate customers in Brazil to fund wallets locally in BRL, reducing costs and improving transaction speed.

Please note, local funding is only available for corporate customers with a valid CNPJ (Cadastro Nacional da Pessoa Jurídica).

• The CNPJ can be provided during onboarding in the taxDetails object using the Onboard Corporate Customer request.
• You can also add CNPJ details to the customer at a later time using the Update Corporate Customer request.

If you're planning to enable BRL funding, make sure your onboarding flow collects this information to avoid any interruptions.

Please note, only wallet funding is supported in BRL. Collecting funds from a third party is not supported.

Supported payment methods

No transaction limits are in place for payment methods in Brazil.

Method	Speed	Availability
PIX	Real-time	24/7
TED	Same day	Cutoff: 15:00 BRT

Funding wallets in Brazil

Unlike other currencies, BRL funding does not use a Virtual Account Number (VAN). Instead, use the static bank details provided by Nium and includes their CNPJ in the payment reference.

1. Share the following BRL bank details with your customer:

   • Account name: NIUM PTE. LTD.
   • Account number: 11504943
   • Bank name: Banco BS2 S.A.
   • Bank code: 218
   • Branch: 0001
   • Currency: BRL

2. The customer initiates a PIX or TED payment, with their financial institution, from their bank account and includes their CNPJ details in the transaction details.

3. Nium matches the CNPJ in the incoming payment with the CNPJ on file for the customer’s wallet.

4. Once matched and reconciled, the customer's wallet is credited in BRL.

For more on onboarding corporate customers, see the Corporate Account Onboarding guide.