Direct Debit Funding user guide

Overview

With Direct Debit Funding, your business customers in the United States with a US bank account can fund their wallet on the Nium One platform using Automated Clearing House (ACH) payments system. To use this API suite, call four unique API payment operations. With the endpoints, add your customer's funding instrument so you can add funds to it through Direct Debit. The Direct Debit functionality is only supported in the United States at this time.

Prerequisites

For this API functionality, you need:

• Your customer's US bank account information and their Nium USD wallet
• Enough money in the added bank account when you start your transactions

Configuration

1. Client and product: As a new or existing client, contact a Nium sales representative. Nium configures direct debit as another funding option for your wallets. You accept Nium’s terms and conditions (T&C). Nium then provides compliance approval according to the geography where the direct debit is set up. Once you complete these steps, you can use the Direct Debit Funding functionality.

2. Customer: Your customer wants to fund their Nium wallet. To help them, you call the Add Funding Instrument API. If you haven't signed up for the service, you receive a message asking you to contact your Nium representative. Your customer can add as many funding instruments as needed to their multicurrency wallet.

3. Callback redirect set up: Nium leverages the Plaid Inc. integration to return a URL field called return_url as a response when using the Add Funding Instrument API. Once your customer completes the authentication, your customer goes to your web page, which shows the final acknowledgment of the account's addition.

API URI resources

Combine one of the following host names with the API resource path from the Direct Debit Funding API details section to create the URI.

• Sandbox: https://gateway.nium.com/baas/1.0/payin-service
• Production: https://api.spend.nium.com

Supported country and currency

📘

NOTE

Currency codes are 3-character ISO 4217 alphanumeric designators for the currency that this API recipe supports.

Direct Debit Funding API endpoints

To use the direct debit funding feature call the following APIs:

📘

NOTE

The Add Funding Instrument and Get Funding Instrument Details APIs are new and currently only support the Direct Debit Funding feature

Direct Debit Funding API details

The Direct Debit Funding API suite involves the following four API URI resource paths.
The combined usage of the endpoints helps you onboard your customer to add funding instruments they can use to make their transactions.

Add the funding instrument to your customer's wallet to start a direct debit funding transaction

URI POST /api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}

Use this API to add the payer’s funding instrument to the customer's wallet so that direct debit payments can be initiated against it. Provide the funding instrument's country and currency code. To execute this operation, pass the unique client identifier generated and shared before the API handshake. Then, pass the customer identifier generated when the customer is created and the unique wallet identifier that's generated simultaneously.

Get a customer's funding instrument details

URI GET /api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstrumentId/{fundingInstrumentId}/fundingInstrumentDetails

Use this API to get the funding instrument details. To execute this operation, pass the unique client identifier generated and shared before the API handshake. Then, pass the customer identifier generated when the customer is created and the fundingInstrumentId that is returned in the above Add Funding Instrument API call.

Get a list of funding instruments registered with a customer.

URI GET /api/v1/client/{clientHashId}/customer/{customerHashId}/fundingInstruments

Use this API to get a list of all the funding instruments registered for your customer. To execute this operation, pass the unique client identifier generated and shared before the API handshake. Then, pass the customer identifier generated when the customer is created.

Fund the customer's wallet for a direct debit transaction

URI POST /api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/fund

Use this API to fund into your customer's wallet using the direct debit option. To execute this operation, pass the customer identifier generated when the customer is created and the unique wallet identifier that's generated simultaneously when the customer is created. You also need to provide the funding instrument ID and select the funding channel as direct_debit during the API call.

Payment flow

1. Call the Add Funding Instrument API to add your customer’s bank account.
2. The API returns a return URL that lets you redirect the customer to the Plaid page.
3. The customer chooses their bank account (funding instrument) to add through Plaid and completes the authentication.
4. Nium returns the funding instrument ID.
5. Client calls the Fund Wallet API to pull funds into the wallet with the correct funding instrument ID.
6. Your customer’s bank account is debited.
7. Nium initiates compliance checks and after a pre-determined period credits the money to your customer’s wallet
8. If the customer raises a chargeback, Nium will manage the chargeback according to T&C.

Use cases

📘

TIP

To learn more about the technical words this guide uses, refer to our Glossary of Nium terms.