Introduction

In today's rapidly evolving tech landscape, mastering the potential of APIs is non-negotiable for constructing efficient, interconnected systems. Welcome to your ultimate guide on best practices tailored to NIUM’s API.

Throughout this guide, we'll delve into critical aspects, covering security concerns and pitfalls to avoid, and offer recommendations for a successful integration strategy. The upcoming subsections unveil the key components essential for a seamless integration. Sections marked as ‘Required’ demand your attention before implementation. Proof of incorporating these mechanisms will be crucial.

Each section concludes with a Pro Tip, a swift guide to immediate actions or noteworthy insights that add substantial value to you and your integration journey. Let's dive in and equip you with the necessary knowledge and strategies for a successful API integration.

NIUM Server Health Check

For optimal service performance, you can check the connectivity status of the NIUM server using getStatus(). If the status of the NIUM APIs is successful, the API will return a SUCCESS status. Any other response indicates that the server is experiencing downtime.

Proactive Monitoring: Schedule status checks at regular intervals (e.g., every 5 minutes) to ensure service availability, detect any potential anomalies, and provide real-time alerts.

Server Communication Timeout

Timeouts generally happen when a network or service problem causes delays that exceed the designated time limit. When this happens, NIUM will return an HTTP 500 status code.

Pro Tip: For optimal performance, our suggested timeout is 60 seconds to ensure the request is carried out within the timeframe NIUM aborts the transaction.

Under normal circumstances, our average card creation time is 0.74 seconds, and whilst all cards created within the 95th percentile are created in 1.17 seconds, we have a Target 95th Percentile of 2 seconds.

Safeguarding your data (Required)

Safeguarding sensitive data like your API credentials and card information should be your top priority. Your API key and Password serve as unique identifiers within the NIUM platform, providing access to its capabilities and the funds in your account. Due to their critical role, handling them with utmost care is paramount to prevent any unauthorized activity on your account.
This attention extends to card data, whether stored locally or offsite. Alternatively, you can choose a secure approach by storing a card reference and fetching the card data as needed, using our getVirtualCardDetails () API method.

Security Tip 1: Encrypt your credentials: Add an extra layer of protection by encrypting your credentials and strictly limiting access to authorized users.

Security Tip 2: Retrieve card details only when needed: Minimize risk by avoiding the storage of card details; instead, retrieve them from our system as required.
These security measures ensure that your integration stays robust and secure. Let’s keep your data safe and your integration even safer.

IP Whitelisting (Required)

Ensuring the integrity of shared data over the internet is paramount, and implementing IP whitelisting emerges as a crucial security measure to achieve this goal. This practice is a robust defense against unauthorized access attempts, ensuring that only approved IP addresses can communicate with the protected resources. Furthermore, IP whitelisting acts as a safeguard, mitigating the potential misuse of your API credentials in the event of accidental leaks.

Pro Tip: Keep your security measures up to date by regularly reviewing and communicating any IPs that require whitelisting. Let’s work together to keep your data secure and your system running smoothly.

Notification Push Service

At NIUM, our comprehensive push notification system offers integrators access to more than 15 distinct notifications, empowering proactive management of various card scenarios such as low balances, real-time authorizations, and purchases. The strategic utilization of these notifications significantly streamlines backend workflows, eliminating the need for repetitive requests and enhancing overall efficiency.

Common scenarios, such as checking a card's balance or retrieving transaction history post-payment, are seamlessly addressed through our Push architecture. NIUM takes the lead by instantly sending JSON notifications, indicating relevant actions like a PURCHASE event. Upon receiving these notifications, you can initiate corresponding requests, ensuring timely and accurate data retrieval. This innovative approach eliminates the necessity for repetitive queries, optimizing the entire integration process.

Our push notifications keep you informed and pave the way for a more responsive and efficient integration experience.

Pro Tip: When consuming NIUM's push notifications, be prepared to supply a designated URL for us to push notifications to. To ensure the authenticity of the notifications, your NIUM Integration Specialist will provide a list of IPs from where these notifications will be issued, along with a notificationKey. This key allows you to validate the genuineness of the notifications you receive.

The snippets below provide a glimpse into a real-time authorization and purchase notification in our system. Leveraging this information ensures you stay ahead in managing card scenarios efficiently within your integration.

{
  "notificationType": "REAL_TIME_AUTH_NOTIFY",
  "notificationCreationTime": 1719405954278,
  "notificationContent": {
    "approvalCode": "167146",
    "authState": "PROCESSED",
    "billingAmount": "100.50",
    "cardAcceptorIdentifier": "51569373",
    "transactionReference": "0UwLAzKCTw_jombsulKQQK1nD",
    "posCardHolderAuthenticationMethod": "NOT_AUTHENTICATED",
    "messageTypeIndicator": "400",
    "transactionCode": "SALE_OR_PURCHASE",
    "cardReference": "0UwLAfjDtfiL8bb5t0qIpYBR4",
    "billingConversionRate": "1.00000",
    "transactionTimestamp": "2024-06-26T12:43:53.760Z",
    "posCardHolderPresence": "NOT_PRESENT_MAIL_ORDER",
    "notificationKey": "57TR6NdXMQMZGZ98",
    "realTimeAuthReference": "0UwJISzrT6UxqWxf5zXBoKwDf",
    "mccCode": "3013",
    "billingCurrency": "EUR",
    "originalTransactionAmount": "100.508",
    "cardAcceptorLocation": "ALITALIA||ROME|||ITA|",
    "originalTransactionCurrency": "EUR",
    "terminalCode": "46403716"
  }
}

{
  "notificationType": "CARD_PURCHASE_NOTIFY",
  "notificationCreationTime": 1690378386216,
  "notificationContent": {
    "notificationKey": "44dZXXXXXXXXXJTD",
    "cardCurrency": "EUR",
    "cardAdjustmentAmount": "9.08",
    "cardReference": "0RACDbTAEn8Xp85ihV84lXSBX",
    "purchaseCurrency": "USD",
    "purchaseType": "PURCHASE",
    "purchaseAmount": "10.00"
  }
}

Getting Your Reports via Secure FTP

Save time and enhance efficiency by leveraging an FTP client to pull reports directly from our system, eliminating the need for manual downloads from the portal.

We offer access to an SFTP server for seamless integration with our reports. This ensures ease of use and allows you to retrieve essential data effortlessly.

Connect with us to find out more.

Building a Future-Proof Integration (Required)

NIUM's dedication to innovation propels us to continuously enhance and resolve challenges, all while remaining backward compatible to ensure a smooth integration process. To achieve this, consider optimizing your API integration to minimize unnecessary checks to make your integration future-proof.

Best Practice: Avoid overly strict validation criteria to minimize the chances of integration issues. For instance, there is no need to strictly verify that an API response returns an exact number of parameters, such as precisely five.

Keeping a Generic Integration (Required)

When building any piece of software, a fundamental best practice is maintaining the generality of components and steering clear of hardcoded configuration parameters. By abstracting crucial configuration details – such as funding account references, card types, and API keys – from the code, you unlock the flexibility to modify these parameters independently. This approach ensures that adjustments don't disrupt the core structure of your code.

Pro Tip: Elevate your integration architecture by abstracting essential parameters. This not only enhances modularity but also provides the adaptability needed for seamless adjustments in the future.

HTTP Response codes & mitigation (Required)

In the rare event of temporary system downtime impacting API calls, our notification system will promptly inform you through HTTP response codes, indicating the success or failure of specific requests. For a detailed understanding of errors, refer to our comprehensive documentation.

To effectively address such scenarios, you are required to implement an exponential backoff retry mechanism with a maximum retry limit. This proactive measure prevents excessive load on requests, ensuring optimal performance.

Enhance Reliability: Introduce a retry strategy to increase the likelihood of a successful response.

Pro Tip: When confronted with 4xx errors, take remedial action before resending the request to avoid repeating the same outcome.

However, relying solely on retries may not be sufficient. In cases where glitches persist despite retries, our dedicated customer support team is here to assist and resolve them. If applicable, consider using our Nium portal for business continuity as you work through the challenges.

For urgent support on your PROD environment, please contact [email protected] to ensure a swift response from our Support team.

Testing and Error Handling (Required)

Software testing is a pivotal step in ensuring the quality of your integration, helping identify and address potential issues before they impact functionality and reliability. Techniques such as using appropriate error codes, implementing comprehensive logging of error details, and incorporating try-catch blocks can significantly aid in identifying, managing, and resolving errors effectively.

To establish a robust testing strategy, it's essential to cover various use cases and API methods in your implementation. Ensure thorough testing by including common paths that involve different API method calls. Examples of these paths include Card Creation, Get Card Details, Transfer Funds, Update Card Information, and Scheduled Loads.

Testing Tip: Log the requests and responses exchanged with the platform during integration testing for a comprehensive audit trail. You will be required to present these logs for final certification.

Troubleshooting Tip: Maintain a record of apiReference within your error handling mechanisms. Additionally, keeping a record of request and response logs together with the relevant stack traces or screenshots can help streamline troubleshooting efforts with your NIUM Integration Specialist.

Once certified and LIVE on Production, it's recommended to retain stack traces for a minimum of 5 days. These stack traces may be requested when seeking assistance from our technical team.

Conclusion and Next Steps

Congratulations on completing this comprehensive guide to NIUM's API integration! We trust you've gained valuable insights for optimizing your integration, ensuring security, and overcoming challenges.

For ongoing assistance and personalized support, don't hesitate to reach out to our dedicated technical team at [email protected]. We can also arrange a private chat tailored to your specific integration needs.

Your success is our top priority, and we eagerly await the opportunity to assist you further.

Ready to get certified? 👉 API Certification Form