API Integration Scenarios
Product version 3.57
Last edited December 2022
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.
| Date | Version | Description |
|---|---|---|
| 15th Feb 2021 | 3.57 | Updated formatting to match brand guidelines |
| 12th Apr 2022 | 3.57 | Product and documentation rebranding |
| 1st December | 3.57 | Product documentation transition to web view |
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:
| Automated reconciliation | You can easily automate transaction reconciliation by creating a unique card for every payment or merchant. You can also attach additional information (custom fields) to cards, enabling you to reconcile payments and supplier receipts without relying on third parties to send you purchase data |
| Save on credit card surcharges | Some Nium virtual cards can help you avoid the fees associated with credit or commercial cards. |
| Save on Forex costs | You can create Nium cards in multiple currencies to save on the forex fees associated with cross-currency transactions. |
| Potential ancillary revenues | Some Nium virtual cards allow you to generate new revenue streams, turning payment costs into profits. |
| Better payments oversight | Nium gives you a real-time view of card balances and purchasing activity. With its notification feature, you can even request alerts when a card balance reaches a certain threshold or when a transaction occurs. |
| Better control than corporate credit cards | With Nium, you can control employee purchases by simply issuing virtual cards on demand and loading them with the exact amount required for a transaction. |
| Eliminate wire transfers and physical cheques | Virtual cards are more cost-effective, easier to administer, and offer better payment protection than wire transfers and physical cheques. Payments made with Nium virtual cards are protected by Visa and Mastercard’s chargeback process, which can reverse card payments in the case of fraud, or if a merchant cannot honor a purchase or enters default. By contrast, wire transfers and cheques do not offer chargeback protection. And, if a wire transfer is made to the wrong account, you must shoulder the administrative burden of attempting to reclaim it. |
| Multiple currency support | Nium allows you to create funding accounts and virtual cards in different currencies. The number of currencies you can access depends on your commercial agreement with Nium and available BIN types. With an ever-expanding banking network, we’re constantly adding new currencies. Ask your Nium Professional Services Manager for more details. |
| Less fraud exposure | Since Nium virtual cards are prepaid, they significantly reduce fraud exposure and can eliminate the risk of supplier duplicate or erroneous charges. Nium’s scheduled loads feature further removes the risk of fraud by allowing you to choose the precise date and time to load cards. After a transaction, Nium can also automatically empty and delete virtual cards to reduce fraud risk further. |
| Unlock working capital | Scheduled card loads not only reduce fraud — but also help you maximize working capital. Nium also offers credit funding to pre-approved companies. With credit funding, Nium users can load cards without topping up their funding accounts. |
| Comprehensive reporting | Our reporting system will give you and your financial team complete visibility of the movement of funds and purchase activities. You will see all fund movements from and to your funding accounts, all transactions performed on your virtual cards, and any scheduled payments. |
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).
-
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. -
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.
- 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.
- 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.
Figure 1: A sequence diagram of the pre-payment API flow
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.
| Funding Account Activity Daily Report | transactionType: Card created | This represents the creation of the virtual card and any related charges. |
| transactionType: Transfer | This represents the amount loaded onto the virtual card from the funding account. | |
| Card Activity Daily Report | transactionType: Transfer | This represents the amount loaded onto the virtual card from the funding account. |
| transactionType: Authorisation | This represents the transaction amount that was authorised on the virtual card by the recipient of 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).
| Funding Account Activity Daily Report | transactionType: Card deleted | This represents the automatic deletion of the virtual card and the transfer of any money remaining on the card to a configured funding account. NOTE: For single-fund cards, the funding account is the original funding account that the card was loaded from. If that account is no longer available, money will be transferred to a default funding account. For details, see the Portal User Guide (provided separately). |
| Card Activity Daily Report | transactionType: Purchase | This represents the amount loaded onto the virtual card from the funding account. |
| transactionType: Card deleted | This represents the automatic deletion of the virtual card. | |
| transactionType: Transfer (optional) | This represents the remaining funds unloaded from the virtual card to the funding account, if any. |
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.
Figure 2: A sequence diagram of the pre-payment report flow
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).
- 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.
- 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.
- 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.
- 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.
- 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.
- 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().
Figure 3: A sequence diagram of the post-payment API flow
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.
| Funding Account Activity Daily Report | transactionType: Card created | This represents the creation of the virtual card and any related charges. |
| transactionType: Transfer | This represents the amount loaded onto the virtual card from the funding account. Depending on the scenario, this may be a deposit or a minimum amount for successful authorisation. | |
| Card Activity Daily Report | transactionType: Transfer | This represents the amount loaded onto the virtual card from the funding account. Depending on the scenario, this may be a deposit or a minimum amount for successful authorisation. |
| transactionType: Authorisation | This represents the transaction amount authorised on the virtual card by the recipient of the payment. Depending on the scenario, this may be a deposit or a minimum amount to make sure the card is valid. |
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).
| Card Activity Daily Report | transactionType: Purchase | This entry represents the settled payment transaction. |
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.
| Funding Account Activity Daily Report | transactionType: Transfer (Optional) | This represents the amount loaded on schedule from the funding account to the virtual card. Depending on the scenario, this may be the remaining amount (after the deposit) or the total payment amount. |
| Card Activity Daily Report | transactionType: Transfer (Optional) | This represents the amount loaded on schedule from the funding account to the virtual card. Depending on the scenario, this may be the remaining amount (after the deposit) or the total payment amount. |
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.
Figure 4: A sequence diagram of the post-payment report flow
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).
| Card Activity Daily Report | transactionType: Authorisation | This represents the transaction amount authorised on the virtual card by the payment recipient. Depending on the scenario, this may be the remaining amount (after the deposit) or the total payment amount. |
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).
| Card Activity Daily Report | transactionType: Purchase | This represents the settled payment transaction. |
After scheduled card deletion
The following transactions will appear in your reports after the card is deleted as scheduled.
| Funding Account Activity Daily Report | transactionType: Card deleted | This represents the scheduled deletion of the virtual card and unloading any remaining funds to the configured funding account. Note: The funding account to which funds are unloaded is configured using the Portal. For details, see the Portal User Guide (provided separately). |
| Card Activity Daily Report | transactionType: Card deleted | This represents the scheduled deletion of the virtual card. |
| transactionType: Transfer (optional) | This represents the remaining funds unloaded from the virtual card to the funding account, if any. |
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.
Figure 5: A sequence diagram of the post-payment report flow (continued)
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.
- 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.
- 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.
Figure 6: A sequence diagram of the modification API flow
Cancelling a Reservation
Part-paid or post-paid reservations may be canceled.
- 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.
- 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.
- 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).
Figure 7: A sequence diagram of the cancellation API flow
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.
Updated 6 months ago