🔒 Finding your technical unicorn
A guide to select your next partner
Welcome to The Engineer Banker, a weekly newsletter dedicated to organizing and delivering insightful technical content on the payments domain, making it easy for you to follow and learn at your own pace
In this instance of The Engineer Banker we will explore technical facilitators in more detail. We will outline essential features that financial institutions should consider as prerequisites when initiating discussions with potential technical partners. If you're in the midst of selecting a technical partner, this article aims to equip you with a curated list of essential features and criteria that you should take into account to find your unicorn. Also, the article aims to serve as a valuable resource, helping you to better prepare and navigate discussions with potential partners. This is a paid article of The Engineer Banker, if you want full access to the article but still you’re not convinced to go paid you can refer the newsletter to your colleagues and get free access.
Let’s get started! if you are new to the concept of a technical facilitator we encourage you to read our introduction to the topic first:
Roadmap alignment
Choosing a partner that is in sync with your payments market expansion strategy is crucial for several reasons. Firstly, it ensures that both parties have a shared vision, which streamlines collaboration and decision-making. Secondly, such a partner is likely to offer tailored solutions that specifically address the unique challenges and opportunities in the markets you are targeting. This means quicker time-to-market and optimized operational efficiencies. Thirdly, their local expertise can provide invaluable insights into regulatory requirements, customer behaviors, and market trends, reducing risks and enhancing competitiveness. A well-aligned partner can thus be a catalyst for successful market expansion.
Having a partner that connects to multiple payment schemes that are aligned with your future payments offering and roadmap can have a significant strategic advantage. This enables a financial institution to quickly expand its reach across various markets and payment ecosystems without the need for separate integrations, thereby saving time and resources. When you are sitting with a partner do not forget to ask for what their plans are for the future and be open to share what are your needs today but also what are the next steps in your roadmap. You might be surprised but they could be onboarded with you they are always in the hunt to validate demand
Same applies for cross-border partners, aligning with a cross-border partner who comprehends your multi-currency and corridor prioritization rollout is pivotal for international scalability. Such a partner can offer a framework that easily adapts to multiple currencies, ensuring fluidity in transactions and simplifying currency conversion challenges. Furthermore, they will be knowledgeable about the intricacies of the corridors you're interested in, including regulatory constraints and market demand. This alignment facilitates not just technical integration but also risk management and compliance, allowing you to focus more on business growth rather than operational hurdles.
Comprehensive Payments API
In the process of evaluating potential technical facilitators, a critical aspect to scrutinize is the comprehensiveness and functionality of their API. This API should not only facilitate initiating payments but should also seamlessly manage recalls, return requests, payment status inquiries, and, more broadly, any outbound operations typically associated with a modern payment scheme. As you navigate through the discovery phase with potential partners, the clarity and detail of their API documentation should be a focal point of assessment. Well-crafted documentation will streamline the integration process, reducing the need for back-and-forth clarification discussions between technical teams.
The availability of downloadable Postman collections for the API is a strong indicator that the provider prioritizes developer experience. This feature simplifies the process of API testing and integration, allowing developers to explore the API's functionalities in a more interactive manner. It showcases a focus on ease-of-use and serves as a tool for accelerating development timelines, thereby enhancing overall operational efficiency.
During the evaluation phase, it's crucial to understand the 'unhappy' scenarios, such as payment returns, that could lead to emergency interventions and firefighting tasks by the engineering team and consequently increase their Business as Usual (BAU) workload. Comprehensive understanding of these edge cases will allow for more informed decision-making and system architecture planning.
Additionally, the presence of a detailed Changelog section that tracks the evolution of API versions can serve as a strong indicator of the level of care invested in both the documentation and the API design itself. This changelog not only provides insights into the maturity and stability of the API but also serves as a testament to the commitment of the facilitator in offering a well-thought-out and robust solution. As an API consumer you should consider the documentation as important as any other parts of the partner’s infrastructure components.
Early access to a sandbox environment can be invaluable for understanding an API's capabilities, limitations, and real behavior. This isolated testing space mimics the live environment, allowing developers to interact with the API without affecting production data. They can run various scenarios, testing both standard and edge cases, to gauge how the API responds. This preliminary experience provides insights into the system’s responses and performance, while also identifying any potential issues that could arise during actual implementation. By interacting with a sandbox, your team can validate assumptions, identify any nuances in the API behavior, and uncover limitations or challenges that may not be readily apparent through a mere review of the documentation. Furthermore, early sandboxing can significantly accelerate the development process, ensuring that teams can hit project milestones on time. The sandbox environment serves as a critical bridge between the theoretical aspects outlined in documentation and the real-world operational conditions you'll encounter in a live setting. It allows you to "test the waters" by simulating interactions with the system without any real-world repercussions.
Some partners will not get you access to the sandbox until you sign the contract, so be aware that this will not always be an option.
When integrating your organization with a payment scheme, you may encounter a certification requirement mandated by the governing body that regulates access to that scheme. This generally entails providing verifiable proof that your implementation complies with specified guidelines, often demonstrated through successful completion of rigorous tests during a predefined certification window.
It's crucial to have a partner that can effectively assist you in navigating this vital certification process. The availability of staging environments on both ends—yours and your partner's—can significantly expedite and streamline the testing phase. These environments serve as risk-free platforms where you can test, troubleshoot, and validate your implementation under conditions that closely mimic the live operational setting.
Furthermore, a cooperative partner can offer invaluable expertise and guidance, helping you to interpret complex compliance requirements, address potential bottlenecks, and troubleshoot issues proactively. Ultimately, their support can be useful in ensuring a successful and timely certification, paving the way for a smooth transition to full operational status within the payment scheme.
Idempotency
Idempotency refers to the characteristic of a system where executing the same function multiple times yields identical outcomes, regardless of the number of times it is called. This property ensures that repeated operations do not produce different effects, thus providing a layer of reliability and consistency in system interactions, formally:
In the context of distributed payment systems, idempotency signifies that repeated operations due to network conditions or other issues will not result in unwanted duplicate transactions. Essentially, idempotency and deduplication function as complementary concepts.
A system can achieve idempotency by incorporating robust deduplication logic, which helps to identify and eliminate redundant operations.
This ensures that if a payment command is unintentionally transmitted more than once, the system will recognize it as a duplicate and refrain from processing it multiple times, thus maintaining operational consistency and financial integrity.
The deduplication logic can manifest in various configurations and utilize diverse data points from incoming requests. Ultimately, it compares each new request against a predefined set of resource criteria to determine whether the request is genuinely new or merely a network retry, potentially triggered by a resilience framework like Resilience4J. This ensures that even if multiple concurrent requests are inadvertently sent due to a software bug, the system will maintain its integrity by creating only one unique resource. Meanwhile, it will flag the remaining redundant requests as conflicts, thereby notifying the sender that those operations were not successful.
As an API designed for payment processing, the infrastructure's idempotency mechanisms must be thoroughly articulated. Clear documentation should specify how idempotency is maintained and under which circumstances the system may potentially generate duplicate transactions. Typically partners will implement one of these three strategies to handle idempotency:
Client-controlled id at payment creation:
POST /api/v1/payments
-headers-
{
"id": "1103de5d-87ed-45f9-a523-4370148d2ec5",
"version": 0,
"organisation_id": "1234",
"amount": "150",
"beneficiary_party": {
"account_name": "Mrs Receiving Test",
"account_number": "73442403",
"account_number_code": "BBAN",
}
"currency": "GBP",
"debtor_party": {
"account_name": "Mr Sending Test",
"account_number": "73442403",
"account_number_code": "BBAN",
},
"end_to_end_reference": "00151519632ZCBBBJQ",
"created_timestamp": "2023-09-15T13:00:00.015Z",
"reference": "D/1234567890123456",
...
...
}
Idempotency key in HTTP Header:
POST /api/v1/payments
"Idempotency-Key": "1AdxBF7bRNHOe8Jz"
-extra headers-
{
//Id not part of the payload
...
}
201 Created
{
payment_id: "1103de5d-87ed-45f9-a523-4370148d2ec5",
...
links: [
https:// .../v1/payments/1103de5d-87ed-45f9-a523-4370148d2ec5/status
]
}
In these cases when the client-side does not control the id of the resource, the payment id is returned in a response and most often than not a link to query the payment status is also given as part of the response.
Deduplication logic is inferred from the payload information, eg same amount beneficiary account number and created timestamp for instance.
POST /api/v1/payments
-headers-
{
"version": 0,
"organisation_id": "1234",
"amount": "150",
"beneficiary_party": {
"account_name": "Mrs Receiving Test",
"account_number": "73442403",
"account_number_code": "BBAN",
}
"currency": "GBP",
"debtor_party": {
"account_name": "Mr Sending Test",
"account_number": "73442403",
"account_number_code": "BBAN",
},
"end_to_end_reference": "00151519632ZCBBBJQ",
"created_timestamp": "2023-09-15T13:00:00.015Z",
"reference": "D/1234567890123456",
...
...
}
Some partners build the deduplication logic inferring from a group of fields within the payment payload, meaning that if the system encounters a transaction with an identical amount, designated for the same beneficiary, and timestamped within the same period, it will interpret this as an unintended retry and will discard it.
Security
Understanding the security measures employed by a potential technical partner is crucial, not just for the safety of transactions but also to ensure that these measures are in harmony with the guidelines and expectations of your internal security and risk management teams. The security technologies you'll encounter with various partners can vary widely but will often include a few standard approaches.
At a baseline level, it's a given that the API should only be accessible via HTTPS to ensure encrypted data transmission. However, some partners go a step further by implementing mutual TLS with certificates. This offers an added layer of security by ensuring that connections are accepted only from pre-verified, specific client systems.
Additionally, some partners may offer VPN tunnel-based connectivity solutions for enhanced encryption of data. This is generally considered more secure, and often recommended for businesses that require the highest level of data protection. Another common security measure is IP whitelisting. Partners may require you to provide your public IP address or a specific IP range so they can configure their systems to reject connections from unapproved or unknown IP addresses, thereby adding an extra layer of protection for the production environment.
In the realm of API authentication and authorization, there are various methodologies that potential technical partners might employ. OAuth2 token-based authentication has become somewhat of an industry standard due to its robustness and ease of use. However, some partners opt for alternative methods like request signing to authorize access to specific API endpoints. Understanding the flexibility and configurability of these authentication and authorization mechanisms is essential. You'll want to delve into how accommodating the partner's system will be when it comes to setting up different roles, users, Access Control Entries (ACEs), and ultimately the credentials that govern API access.
For example, your organization might require a multi-tiered role system where different levels of employees have varying degrees of access to specific functionalities. Knowing whether the partner's system can accommodate such complexity can be crucial for maintaining internal controls. You should also inquire if their system allows for easy revocation and rotation of credentials, which is vital for maintaining security hygiene.
Another point to consider is whether the partner’s approach aligns well with your existing infrastructure and security policies. If you already employ OAuth2 for other services, for instance, choosing a partner that also utilizes OAuth2 could streamline integration and policy management. In next articles of TEB we will explain in detail all these mechanisms that protect the confidentiality and integrity of payments.
Audit logs from your partner are a foundational feature that you'll likely need to implement when launching a project. While some security teams may initially allow you to proceed without this functionality for a Minimum Viable Product (MVP), it will become mandatory in the long run for compliance and security oversight. An audit log serves as a detailed digital record, generated whenever an action is executed within a system. These logs are meticulously stored for future reference and can act as definitive evidence to verify that specific activities have occurred. They are highly versatile and can be employed to monitor a wide range of interactions, from user-to-application engagements such as clicks on a web interface, to application-to-application communications like API calls. The primary utility of audit logs extends beyond simple record-keeping; they are essential for compliance verification, security monitoring, and forensic analysis.
These logs serve multiple crucial functions, including generating alerts for privileged actions that may require subsequent team confirmation. They are instrumental in monitoring unusual HTTP activity based on factors such as the time of day and geographic location. Additionally, they are configured to trigger alerts for authentication failures and other anomalous events. In essence, these logs not only record activity but also play a proactive role in enhancing security measures and operational oversight. We will cover audit logging extensively as part of our first security article of The Engineer Banker.
Incident management
Keep reading with a 7-day free trial
Subscribe to The Engineer Banker to keep reading this post and get 7 days of free access to the full post archives.