About this guide

This document describes how to integrate your application with the Nium API in scenarios typical for an online travel agent.
The document does not contain detailed API functions or report format descriptions. For reference, consult the REST API Reference Guide or the Reports Reference Guide .

📘

NOTE

This document is written for developers and assumes that you know how to use APIs.

What's new in this version?

The following information has been added to the current version of this guide.

Overview

What is Nium?

Nium is a virtual card platform for businesses. With Nium, you can create and load virtual cards on demand and track and reconcile your virtual card transactions.

For many businesses, a virtual card is an excellent alternative to a corporate credit card. Just like traditional credit cards, you can use a virtual card to make purchases online or by phone. Virtual cards have a 16-digit card number, CVV, and expiry date. But unlike traditional cards, virtual cards are pre-paid, significantly reducing the risk of fraud. Virtual cards are also cost-effective and make reconciliation more efficient and accurate than conventional corporate credit cards.

How will you benefit from using Nium?

This guide will walk you through the various actions and functions available within the
Nium web app and through the Nium API. Each step and function offers a range of
benefits:

How does Nium work?

With the Nium web app, you can manage your funding accounts, create and load virtual cards, and track, monitor, and reconcile payments.

The Nium team will set up your Nium web app account, configuring it for the requirements you identify during your onboarding.

Setting up a Nium company account

To get started, you must contact our Client Delivery team. We will set up your Nium company account and one or more funding accounts. You can manage your company and funding accounts through the Nium web app.

Add money to your funding accounts

In simple terms, funding accounts are where your money is deposited and stored before you use it to top up a virtual card.

During your account setup, we create one or more funding accounts for you. Your team can create additional funding accounts after account creation.

You must add money to your funding account(s) from your bank account via bank transfer. Funding account balances can be tracked through APIs or online through the Nium web app.

Create and load virtual cards

You can load funds onto one or more virtual cards with the Nium API or the Nium web app. All cards you create and load are instantly available to use.

Track the history of virtual card activities

Nium’s APIs and web app provide you with an entire history of card activity, including balances and transactions. Automated card activity notifications ensure tight integration with your existing systems.

Track the history of funding account activities

Your operations team can track the history of funding account balances and activities through the Nium APIs or web app.

Key Nium concepts

This section describes essential concepts that must be understood to integrate your application with Nium APIs in the described scenarios.

Single-fund card

A single-fund virtual card can only be loaded (topped up) once. All subsequent load attempts will fail if you load a single-fund card with any amount.

📘

NOTE

A single-fund card is often configured as a single-spend card and is sometimes referred to as a single-use card.

Single-spend card

A single-spend virtual card can only be used for a single transaction:

• Once the single-spend card is used for any transaction for any amount, it is automatically frozen and cannot be used for any other transactions.
• Once a settlement arrives for the transaction that the card was used for, the card is automatically deleted. Any money remaining on the card is returned to one of your funding accounts.

Multi-fund card

A multi-fund virtual card can be loaded (topped up) repeatedly.

📘

NOTE

A multi-fund card is often configured as a multi-spend card and is sometimes referred to as a multi-use card.

Multi-spend card

A multi-spend virtual card can be used for an unlimited number of transactions:

• A multi-spend card is never automatically frozen or deleted. If you want to freeze or delete a multi-spend card, you need to do this manually in the Nium web app or through our API.
• A multi-spend can be used for an unlimited number of transactions. However, we recommend using this card type for unique, multi-stage transactions. For example, a post-payment scenario for one customer and one hotel only. Using multi-spend cards in this manner simplifies reconciliation

Virtual card factory (card type)

A virtual card factory is a set of parameters used when creating any virtual cards in Nium. You can think of it like a virtual card recipe. Card factories determine the card scheme (Visa or Mastercard), whether the cards created are single-fund, single-spend, multi-fund, or multi-spend, and additional properties such as interchange rates. All cards made using a single factory share the same parameters.
Users cannot configure their card factories. These are set up during your Nium deployment. If you need to create new card factories, please get in touch with your Nium Account Manager.

🚧

IMPORTANT

In the Nium web app, card factories are called card types.

Pre-Auth Protection

Pre-auth protection on single-spend cards extends their usability when the recipient pre-authorizes the payment.
When Pre-auth protection is enabled within a virtual card factory (or card type), the single-spend card will not be frozen after the first pre-authorization of a value up to 1.0 in the transaction currency. However, the card will be automatically frozen if a second pre-authorization occurs.
Pre-auth protection cannot be enabled for multi-spend cards.

Examples of payment scenarios

Pre-payment scenario

This scenario can be applied if a service must be paid for in advance, such as:

• Payment for a flight
• Pre-paid hotel booking

📘

NOTE

In this scenario, we recommend using a card configured as a single-spend card. A multi-spend card can also be used, but it will have to be manually deleted later.

🚧

IMPORTANT

In this scenario, the recipient does not attempt to confirm the card before payment.

Pre-authorisations / card confirmations

Recipients can attempt to confirm a card in several ways, such as charging the card for a small amount (and then later refunding this amount to the card). In this instance, this “test charge” would trigger a single-spend card to be automatically frozen, which means it could not be charged by the recipient for the total amount of the transaction later.
However, if the recipient makes a zero-value authorization request or a minimum-value authorization request of up to 1.0 in the transaction currency, the pre-auth protection feature (see 0) should be used for single-spend cards. When enabled, pre-auth protection prevents the card from being frozen after the first pre-authorisation. (However, if additional pre-authorisation attempts are made, the card will still be automatically frozen.)
In pre-payment scenarios, we recommend asking the recipient of the payment to ensure they do not confirm the card before the payment.

Example: Direct payment to an airline

Your customer pays for a flight on your website. After processing their card through your payment gateway, you immediately use Nium to generate and load a virtual card. You use this virtual card to make a payment to the airline.

Example: Pre-paid hotel booking

Your customer pays for a hotel stay on your website in advance and in full. After processing their card through your payment gateway, you immediately use Nium to generate and load a virtual card. You use this virtual card to make a full payment to the hotel. (Pre-paid hotel payments are usually non-refundable.)

Pre-payment API flow

In a pre-payment scenario, the following conditions must be met before you call the APIs:

• You must know the total price of the service and the currency
• You must know if there are any additional fees associated with creating and using the card
• A single-spend factory must be available (see Key Nium concepts).
• A funding account must be available and contain enough money to fund the card (price and fees)

📘

NOTE

For detailed API call syntax, consult the appropriate API reference guide (provided separately).

📘

NOTE

For detailed API call syntax, consult the appropriate API reference guide (provided separately).

1. Call the login() API.
   This step is required to provide credentials to access Nium. You are granted access and receive a securityToken used for subsequent API calls as a session identifier.

2. Call the issueVirtualCard() API.
   In this step, the virtual card is created. Provide all the information necessary for creating a card, including the fundingAccountReference, the currency, and the load amount. You can also use cardInfo to store traveler/reservation details and link the virtual card to your internal booking system/process. The card is created and loaded with funds, and you receive a cardReference that can be used to get card information.

📘

NOTE

Loading the card in this step is recommended but not necessary. If you do not
load the card at creation time, you must use the transferFunds() API.

3. Call the getVirtualCardDetails() API using the cardReference.
   This step is required to retrieve the card information needed to make the payment: the card number, the expiry date, and possibly the CVV code. To get the CVV code, you must set the getCvv parameter to true.
   You will receive all the information you need to proceed with the payment. For example, nameOnCard, cardNumber, expiryDateMonth, expiryDateYear, cvv.

🚧

IMPORTANT

Do not store the received card information unless you are fully PCI
compliant.

4. Make the payment.
   This step is completed outside of Nium, either manually or by integrating
   the recipient’s system. If your system has a notification listener set up (handleNotification() API), you receive a REAL_TIME_AUTH_NOTIFY notification.

📘

NOTE

The single-spend virtual card is automatically frozen until settlement and cannot be used for any other transactions.

Pre-payment Report content

As a result of virtual card creation and payment, the following transactions will appear in your reports.
Your reports are generated nightly as files. You can download them the next day using a dedicated service. See the Reports Reference Guide for report access and format details.

After card creation

The following transactions will appear in reports the day after the creation of the card and the payment.

📘

NOTE

The same information is also available in the relevant Funding Account Activity Monthly Report and the Card Activity Monthly Report at the end of the month.

After settlement

The following transactions will appear in your reports after receiving the settlement (usually within 3 to 30 days).

📘

NOTE

If your system has a notification listener set up (handleNotification() API), you receive a CARD_PURCHASE_NOTIFY notification when the settlement comes in and a CARD_DELETED_NOTIFY notification when the card is automatically deleted.

Post-payment scenario

This scenario refers to a service that is paid entirely in arrears or arrears with a deposit, such as:
• Part-paid hotel booking
• Post-paid hotel booking

📘

NOTE

In this scenario, a multi-spend card must be used.

Example: Pre-authorised, pre-paid hotel booking

Your customer pays for the hotel stay on your website in advance and in full. After processing their card through your payment gateway, you use Nium to create and load a virtual card instantly. You use this card to make a full payment to the hotel. The hotel attempts to confirm (pre-authorise) the card before charging the full payment.

Example: Part-paid hotel booking

Your customer makes an advance payment for a hotel stay on your website. After processing their card through your payment gateway, you use Nium to create and load a virtual card instantly. You use the card to make an advance payment to the hotel. Around the check-out date, you process the payment from the customer’s card and then pay to the hotel on your virtual card.

Example: Post-paid hotel booking

You use Nium to generate a card so the hotel can confirm it. Around the check-out date, you process payment through the customer card in your payment gateway. Then, you use a Nium virtual card (created earlier) to make the final payment to the hotel.

Post-Payment API Flow

The following conditions must be met before you call the APIs:

• You must know the total price of the service you need to pay for, the deposit amount (if any, depending on the scenario), and the currency
• You must know if there are any additional fees associated with creating and using the card
• A multi-spend factory must be available
• A funding account must have enough money to fund the card (deposit, remaining payment, and fees).

📘

NOTE

To avoid Forex fees, the funding account should be in the same currency as the expected payment.

📘

NOTE

For detailed API call syntax, consult the appropriate API reference guide (provided separately).

1. Call the login() API.

This step is required to provide credentials to access Nium.
You are granted access and receive a securityToken that is used for subsequent API calls as a session identifier.

2. Call the issueVirtualCard() API.

In this step, the virtual card is created. Provide all the information necessary for a card to be created, including the fundingAccountReference, the currency, and the initial load amount (see the options below). You can also use cardInfo to store traveler/reservation details and link the virtual card to your internal booking system/process.

📘

NOTE

Loading the card in this step is recommended but not necessary. If you do not load the card at creation time, you must additionally use the transferFunds() API.

• If the scenario involves a reservation with no payment, load the card at creation time with a small amount that is enough for successful authorisation. For example, 1 euro if the payment is in euros.
• If the scenario involves a deposit, load the card with the deposit amount (including applicable fees) at creation time.

The card is created, loaded with an initial amount, and you receive a cardReference that can be used to get card information.

3. Call the getVirtualCardDetails() API using the cardReference.

This step is required to retrieve the card information you need to make the reservation or a deposit: the card number, the expiry date, and possibly the CVV code. To get the CVV code, you must set the getCvv parameter to true.
You receive all the information needed to proceed with the reservation or a deposit, for example, nameOnCard, cardNumber, expiryDateMonth, expiryDateYear, cvv.

🚧

IMPORTANT

Do not store received card information unless you are fully PCI compliant.

4. Make the reservation or pay the deposit.

This step is completed outside of Nium, either manually or using integration with the payment recipient system.
If your system has a notification listener set up (handleNotification() API), you receive a REAL_TIME_AUTH_NOTIFY notification. If the scenario involves a deposit, you will receive a CARD_PURCHASE_NOTIFY notification for the deposit payment when the settlement arrives.

5. Call the scheduleLoad() API.

In this step, you define an amount to be loaded onto the card in the future (on scheduleDate), and you schedule card deletion (on clearanceDate).

📘

NOTE:

You should allow sufficient time for settlement before the card is deleted. This is because scheduled deletion happens regardless of whether the settlement was received. For hotel reservations, we advise the scheduleDate to be just before the check-in date and the clearanceDate to be 3 days after the check-out date.

If your system has a notification listener set up (handleNotification() API), you receive a SCHEDULE_LOAD_CREATED_NOTIFY notification.

6. The card is charged for the full amount or the remaining amount (depending on the scenario) at a later date.

The payment recipient performs this step.
If your system has a notification listener set up (handleNotification() API), you receive a REAL_TIME_AUTH_NOTIFY notification.

📘

NOTE

Multi-spend virtual cards are not automatically deleted. You must manually delete them yourself. To do so, you may schedule deletion using scheduleLoad(). You can also manually delete the card using deleteVirtualCard().

Post-Payment Report Content

As a result of virtual card creation and payment, the following transactions will appear in your reports.
Reports are generated nightly as files. You can download them the next day using a dedicated service. See the Reports Reference Guide for report access and format details.

After card creation

The following transactions will appear in the reports the day after the creation of the card and the reservation and/or the deposit.

📘

NOTE

The same information will also be available in the relevant Funding Account Activity Monthly Report and the Card Activity Monthly Report at the end of the month.

After the deposit settlement

The following transactions will appear in the reports after receiving the deposit settlement (usually within 3 to 30 days).

📘

NOTE

This only applies to scenarios where a deposit is paid. No settlement is received for pre-authorisation.

After the scheduled load is performed

The following transactions appear in the reports when the scheduled load is performed.

📘

NOTE

An additional Scheduled Loads Report (generated daily) indicates the aggregate amount per funding account that must be available for card loads to be successful based on pending scheduled loads.

After the card is charged

The following transactions appear in your reports when the card is charged for the remaining or the total amount (depending on the scenario).

After the final settlement

The following transactions will appear in the reports after the remaining amount, or total amount settlement is received (usually within 3 to 30 days).

After scheduled card deletion

The following transactions will appear in your reports after the card is deleted as scheduled.

📘

NOTE

If your system has a notification listener set up (handleNotification() API), you receive a CARD_PURCHASE_NOTIFY notification when the settlement arrives and a CARD_DELETED_NOTIFY notification when the card is deleted.

Modifying a Reservation

Part-paid or post-paid reservations may be modified, for example:
• If the date of the traveler's stay at the hotel is changed
• If the stay is lengthened or shortened
• If extra services are ordered, and the payment amount is increased
Modification may involve a change in amount, scheduleDate, or clearanceDate.

1. Call the login() API.

This step is required to provide credentials to access Nium.
You are granted access and receive a securityToken that is used for subsequent API calls as a session identifier.

2. Call the update ScheduleLoad() API.

Use the scheduleReference you received from scheduleLoad() earlier to refer to a particular scheduled load and provide new data as needed.
If your system has a notification listener set up (handleNotification() API), you receive a SCHEDULE_LOAD_UPDATED_NOTIFY notification.

Cancelling a Reservation

Part-paid or post-paid reservations may be canceled.

1. Call the login() API.

This step is required to provide credentials to access Nium.
You are granted access and receive a securityToken that is used for subsequent API calls as a session identifier.

2. Call the cancelScheduleLoad() API.

Use the scheduleReference you received from scheduleLoad() earlier to refer to a particular scheduled load to be canceled.
If your system has a notification listener set up (handleNotification() API), you receive a SCHEDULE_LOAD_CANCELLED_NOTIFY notification.

3. Call the deleteVirtualCard() API.

You must manually delete the card if a scheduled load that included scheduled card deletion is canceled. Use the cardReference obtained earlier from issueVirtualCard() to refer to a particular card.
If your system has a notification listener set up (handleNotification() API), you receive a CARD_DELETED_NOTIFY notification. Funds from the deleted virtual card are unloaded to the configured funding account.

📘

NOTE

The funding account to which funds are returned is configured using the Portal. For details, see the Portal User Guide (provided separately).

Additional Information

Paying in different currencies

When you are paying in a currency different from what you loaded your virtual card with, you need to estimate the amount you need to load onto the card to make the payment in the foreign currency.
The load amount should generally be approximately 3% more than the original amount. Take the following into account when calculating the load amount:

• The booking amount in the transaction currency (the currency in which you are paying your supplier)
• The Forex (foreign exchange) fee charged by Nium is a percentage-based fee (details can be found in your agreement)
• The authorisation reserved padding. This is set at 1% and covers fluctuations in the exchange rate between authorisation and settlement dates. Your card is always charged for an amount based on the exchange rate on the settlement date (not the authorisation date). Any unused amount will be automatically returned to your funding account.

Managing refunds

If a refund or an OCT (Original Credit Transaction) is processed on your virtual card, you can refund the traveler’s card via your processor.
If your system has a notification listener set up (handleNotification() API), you will receive a notification of type CARD_PURCHASE_NOTIFY with purchaseType REFUND or ORIGINAL_CREDIT respectively.
These transactions are also included in the Card Activity Report (Daily/Monthly) and the Funding Account Activity Report (Daily/Monthly).

📘

NOTE

If the virtual card receiving the refund/OCT has been deleted, funds will be automatically unloaded to the configured funding account.

Notifications

When certain events occur in the system, you can receive notifications in two ways:

• Directly as part of your integration. For this, you need to have a listener on your system that implements the handleNotification() API. See the relevant API Reference Guide (provided separately) for more information.
• To a configured email address.

Notification preferences are set at the deployment stage. Contact your Nium Professional Services Manager for more information.