DEVELOPER
DEVELOPER

Back to Developer Blog

technicalseries

How Payment Request APIs Work
ecommercesemi-integratedhosted-payments

By Alex Sorbala and Laura Olson | September 23rd, 2024

How do payment APIs work?

Overall, payment request APIs function like most standard APIs, but a defining characteristic is that they are used to transmit highly sensitive data, such as credit card information, information about payment transactions, and more. The handling of this data is strictly regulated by multiple organizations, including the Payment Card Industry (PCI) and the credit card networks, such as Visa, MasterCard, and American Express. Each group requires that payment applications meet rigorous security and design criteria when constructing and transmitting a payment request. While this is a substantial responsibility for clients integrating with these APIs, some payment companies offer products that take on part (or all) of the burden of compliance.

The level of compliance that an API takes responsibility for is one of the most influential factors that shapes the API’s design. In general, payment APIs that meet most compliance regulations out-of-the-box require that the payment company retains a greater amount of control over the data. As a result, there are fewer aspects of the integration that the client can customize. On the other hand, integrations that give the client more control often require that they also bear more of the responsibility for meeting compliance regulations. This variety of designs allows clients to choose the type of API that best fits their existing environment, resources, and business model.

transaction lifecycle

Payment Request Data Flow

When a payment request object is sent, the data makes multiple stops before reaching its destination—the financial institution that issued the customer's credit card. This route typically includes the gateway, the processor, one of the major card networks, and finally, the issuing bank. Once these financial institutions have processed the payment, the bank returns a transaction authorization if the request is approved or an error message if the request was declined. The request is only successful if the requirements for each stop on the route are met. Once a response is obtained, it is sent back to the calling application by retracing the same route.
For requests that aren’t related to payments, there are generally fewer stops (or no stops) before the destination, if the data being requested is simply stored on a server. This means that there are fewer points of failure, since there aren’t as many organizations that must approve the request before a success response is obtained.

Get in Touch

Talk to us about your business's payment API requirements.

Types of Payment Request APIs

Because payment request APIs must be designed with industry requirements in mind, their architecture is a result of the way those requirements are addressed. Some of the most common types of payment API architecture include:

Full-Featured APIs

Full-featured payment APIs generally offer the highest degree of customization, while the client is responsible for meeting most or all regulatory requirements. These types of APIs come in various designs, such as:
  • Full-featured ACL-based APIs: This design requires that requests come from a server (or multiple servers) because of the use of Access Control List (ACL) rules based on IP address. The server’s IP address must be whitelisted to gain access to the API, but no other form of authentication is needed. This type of API, such as North’s Server Post API, is very easy to integrate.
  • Full-featured authentication-based APIs: In this design, requests can be sent from any device, but a more complex authentication process is required. These types of APIs, such as North’s Custom Pay API, may use algorithms such as HMAC-SHA256 for authentication. This can make them somewhat more difficult to integrate, in exchange for the flexibility of making calls from any location.

Semi-Integrated APIs

Semi-Integrated payment APIs provide a secure way for merchants to accept card-present payment methods without undergoing the lengthy EMV transaction certification process, if the software running on the physical payment terminal is already certified. Semi-Integrated APIs work in conjunction with a POS system, which sends the request to a payment terminal via LAN. The terminal then sends the request out of the LAN to the processor along the route to the card-issuing bank.
Semi-Integrated payment hardware
This type of integration handles most or all of the responsibility of compliance for the client because sensitive payment details never enter their server environment. In this type of implementation, such as North’s Ingenico Semi-Integrated API, payment-related data is confined to the terminal, which runs the payment company’s EMV-certified software, before being sent out of the LAN. When the terminal receives a response, only non-sensitive data is returned to the merchant’s environment, significantly reducing the PCI compliance scope for the merchant.

Gateway APIs and SDKs

Gateway APIs can be beneficial for clients who want a fast and easy integration with less customization than a full-featured API. Gateway APIs do a great job of meeting the client half-way by building much of the integration for them. Gateways may also offer additional features that work with the payment API, such as pre-built reporting dashboards or the ability to accept multiple currencies. Clients that want to get up and running quickly and don’t have many complex requirements that require customization may find that a gateway API like North’s iFrame JavaScript SDK is a great fit.

Hosted Payment Pages

Hosted payment pages remove most or all of the burden of compliance from the client, though they offer the lowest degree of customization. The payment page, such as North’s EPX Hosted Pay Page, is hosted on the processor’s server, which means that sensitive data never reaches the client’s environment. The processor is responsible for managing the security of the payment form as well as meeting regulatory requirements for the data it handles. Merchants and ISVs can make some customizations to the page, typically using HTML and CSS. When changes are needed on the page, a new file must be provided to the processor. Hosted payment pages can accept any of the gateway or processor's supported payment methods, including credit and debit cards, mobile wallets, and more.

Security Standards

Payment APIs must adhere to strict regulations that were developed by leaders in the industry, including the Payment Card Industry Security Standards Council (PCI SSC) and the major credit card networks. The PCI SSC maintains a set of Data Security Standards (PCI DSS) that are designed to safeguard security across the industry, and each credit card provider also maintains its own set of regulations that must be followed when handling payment-related data. Some of the major domains regulated by these organizations include the following:

API Authentication

The authentication process for APIs that don’t handle payment data is often simple. Typically for private APIs, a user requests credentials and is vetted in some way to ensure they qualify to use the product. If approved, some form of ID and password are returned, which can be used to authenticate. For public APIs, any user will be granted credentials, which is often done via an automated self-service tool.

Authenticating with a payment API is significantly more difficult because it has a major prerequisite: the user must have a Merchant Processing Account. This account allows merchants to send and receive funds through the gateway or processor, but the process to open a processing account is much more complex than a standard user account. Merchants must submit an application that includes detailed business and financial information, which is reviewed by the payment company to ensure that the business being underwritten is legitimate.

Man underwriting an account
The review can be thought of as a risk assessment that involves analyzing data such as the account holder’s Social Security Number, bank account details, credit history, and more. If approved, the merchant is granted an account with a Merchant Identification Number, which can then be used to obtain payment API credentials. Because the process to apply for and obtain a Merchant Processing Account is so complex, gaining access to a payment API is very different than accessing a typical API. To learn more about what’s involved in obtaining a Merchant Processing Account, refer to this article.

Data Storage

Due to the sensitive nature of payment-related information, the payment industry enforces strict rules about how data can be stored. In general, data is classified by type, and each type has a corresponding set of storage rules. For example, CVV and PIN values may never be stored in any format. The Primary Account Number (this is the 16-digit number on the credit card) may be stored if encrypted, although the first 6 and last 4 digits may be stored in clear-text. Data that’s considered less sensitive, such as the transaction amount, can be stored in any format.

Data Transfer

The regulations regarding the transfer of data are far reaching and may affect aspects of the client’s network infrastructure, security policies, and more. PCI DSS standards include topics such as the governance of network security controls, restricting access to and from the payment environment, and mitigating risks from untrusted networks. For more information about security requirements and PCI scope, refer to the latest PCI DSS standard as well as each credit card provider’s individual requirements.

How To Get Started

To learn more about which payment API is the right fit for your needs, contact North's Sales Engineering team.

Related Posts

technical

Integrated vs. Semi-Integrated Payment Architecture Solutions

Point of Sale system architecture choices can ease the burden of PCI responsibility for developers.

By Bryan Long | January 8th, 2024

technical

How To Use A POS Device To Accept Payments With North’s Ingenico Semi-Integrated API

Learn how North’s Ingenico Semi-Integrated API enables POS integrations to connect seamlessly to Ingenico hardware and firmware.

By Alex Sorbala and Laura Olson | August 4th, 2022

technical

The Benefits of Integrated Payments

Integrating directly with a processor gives businesses the most direct access to credit card networks, resulting in fast processing time and minimizing failure points.

By Alex Sorbala and Laura Olson | August 18th, 2022

Start your free Developer account and try it now.

Get Started
Working With UsHardwareSecurityFAQsGlossaryTags by Topic
Products
In Person PaymentsOnline PaymentsFull FeaturedFinTech Tools
Explore
About UsBlogNorth.comNorth HubNorth Exchange
More
Log InCreate AccountContact UsTerms of UsePrivacy PolicyCookies
©2025 North is a registered DBA of NorthAB, LLC. All rights reserved. North is a registered ISO of BMO Harris Bank N.A., Chicago, IL, Citizens Bank N.A., Providence, RI, The Bancorp Bank, Philadelphia, PA, FFB Bank, Fresno, CA, Wells Fargo Bank, N.A., Concord, CA, and PNC Bank, N.A.