Loading...
This guide assumes that you’re integrating directly to our REST API from within your own already-built terminal application. We focus on showing you how to send commands to our API from your terminal application rather than how to develop one from the ground up.
Our steps show you how to process and capture a transaction with POST commands for a chip-insert debit transaction scenario. We also provide information on other types of scenarios as well as how to handle end-of-day procedures like batch and settlement.
For information on application development, we recommend that you consult your terminal manufacturer’s reference materials.
Our API also supports standalone, semi-, and cloud integrations for card-present transactions. However, the JSON code samples in this guide are for connecting to the API directly with a payment terminal attached to your application to handle the associated payment card data.
Full integration is the most demanding method of connecting to our API, but it also provides the most flexibility. You have full control over the payer experience and workflows. This type of integration requires a certification to our processing platform followed by EMV certifications in each processing region. In addition, you would be coding directly to a payment device to retrieve card/EMV data to send us for transaction processing.
To compare full integration with our other types like standalone, semi-, and cloud, see In-Store Payments - Overview.
This section covers some considerations and resources to keep in mind when choosing a full integration:
For full integrations, you need to code directly to our API or use one of our SDKs (see SDK & Libraries). Alternatively, you can bypass our SDKs and incorporate our code directly into your terminal application.
Coding directly to our API for card-present transactions requires a basic understanding of how our API works, from authentication to transaction processing. For more information, see API Explorer or API Definitions.
We provide the following resources to help:
Our source code is publicly available on GitHub. You also can find this GitHub link in the footer of our portal pages under Connect.
We provide use cases and sample API requests and responses on Postman. For more information, see Postman Collection.
Terminal ID number (TID) management should also be considered as it could impact how your software functions when processing secondary transactions. Consult with your account manager to ensure that there are no regional nuances with this approach. Our devices can be configured to have a single TID per location as long as the lane is identified in the transaction (for example, Front Desk, Bar, and so on).
Cloud servers or local “fat” software installed on a computer can act as a controller for all lanes, sending transactions, receiving responses, and routing them to the originating device or lane. The advantage is that secondary transactions are no longer tied to the device or lane that processed the original transaction. Secondary transactions can be performed at any lane, thereby improving the customer and server experience. Consult with your account manager to ensure that there are no regional nuances with this approach.
Fully integrated solutions must be certified to our platform. A certification analyst will collect details — such as your terminal application; EMV kernel, PCI PTS, and PA-DSS approvals; supported industries and transaction types, and so forth — and configure a certification script tailored to your solution. The typical approach is to certify mag-stripe transactions first. Once that is successfully completed, we begin the EMV certification.
EMV certification requires you to purchase the UL BTT software, which simulates the various issuers’ EMV chip card profiles for contact and contactless EMV test cases, as well as digital wallets.
Any compliant terminal (With the above requirements for EMV kernel, PCI PTS, and PA-DSS approvals) that supports custom applications can be used to code an integration to our API. That said, if a terminal is required, we are able to provide a variety of terminal models for your use as well. For available models, please contact your account manager.
Payment devices need to have keys injected into the device to properly function. End-to-end encryption (E2EE) takes clear PAN data found on track 1 and track 2 of the mag stripe or in the chip data and encrypts it using cryptographic keys, which are securely injected into the card reader/terminal.
The keys are used to transform the clear track data into a unique data string before it’s transmitted. This is usually done within a secure hardware module on a PCI PTS certified terminal, ensuring it can’t be read and decoded during transmission. The string of data is then transmitted to us, where we securely decrypt it and send to the card issuer for processing.
To avoid sending full PAN or PIN data over the internet, a form of end-to-end encryption called TDES DUKPT is standard. For a transaction on a successfully injected terminal to include this, the key serial number (KSN) must be included on the transaction request, as shown in the code sample below.
Our API identifies the physical device using only the account_name parameter, rather than by using a serial number, TID, or other fields common in other environments.
In this example, we use a swipe entry mode and end-to-end encryption.
Before starting the steps in this guide, you must do the following:
The first step is to create an authorization. This creates the transaction, assigns it a transaction ID, and processes the authorization. A sale transaction can be flagged for automatic capture using the capture_mode flag or flagged as requiring a separate capture action later. By default, it will automatically attempt capture.
Partial authorizations are possible by setting the authorization_mode to partial. This allows your application to be notified if only part of the transaction was approved and a second form of payment will be required to complete the balance (for example, on a $100 sale, only $85 was approved, leaving a remaining balance of $15 that requires a secondary form of payment to complete). If the authorization_mode flag is not set, transactions will instead decline.
In a card-present environment, many types of transactions are possible, including chip insert (dipped), tapped (contactless), swiped, or keyed (depending upon your region). The below example is of a chip-insert debit transaction. The type of transaction is indicated by the entry_mode flag on the request.
{
"id": "TRN_ewFfZZmrdQ6jGaObwu2FbyRonAerwG",
"time_created": "2024-02-28T21:35:06.077Z",
"type": "SALE",
"status": "CAPTURED",
"channel": "CP",
"capture_mode": "AUTO",
"amount": "1999",
"currency": "USD",
"country": "US",
"merchant_id": "MER_c4c0df11039c48a9b63701adeaa296c3",
"merchant_name": "Sandbox_merchant_2",
"account_id": "TRA_6716058969854a48b33347043ff8225f",
"account_name": "Transaction_Processing",
"reference": "93459c78-f3f9-427c-84df-ca0584bb55bf",
"payment_method": {
"result": "00",
"message": "APPROVED 000APPROVED O00999",
"entry_mode": "CHIP",
"card": {
"funding": "DEBIT",
"brand": "INTERAC",
"masked_number_last4": "XXXXXXXXXXXX0016",
"authcode": "",
"brand_reference": "",
"brand_time_created": "2024-02-28T16:35:07.000Z",
"tag_response": "910A11111111111111111111",
"provider": {
"result": "00"
}
}
},
"batch_id": "BAT_943493-494",
"action": {
"id": "ACT_ewFfZZmrdQ6jGaObwu2FbyRonAerwG",
"type": "AUTHORIZE",
"time_created": "2024-02-28T21:35:06.077Z",
"result_code": "SUCCESS",
"app_id": "U1lRHKomEn7DN907RCDPxVhyMfiMLcfy",
"app_name": "dev_portal_demo"
}
}If the capture_mode flag is not set to AUTO, the transaction must be captured at a later date. This is frequently done in scenarios where you want to finalize the purchase price later. This is also known as a pre-authorization and is frequently used in hospitality and lodging scenarios.
To capture a transaction, you must use the original ID returned in the authorization response in the query URL. You can capture a transaction for any amount up to 115% of the original value. If you don't include an amount in your request, by default the full amount will be captured.
{
"id": "TRN_uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",
"time_created": "2021-05-03T21:23:39.718Z",
"type": "SALE",
"status": "INITIATED",
"amount": "11099",
"currency": "USD",
"country": "US",
"reference": "becf9f3e-4d33-459c-8ed2-0c4affc9555e",
"batch_id": "BAT_234234234",
"payment_method": {
"result": "00",
"message": "Successful",
"card": {
"authcode": "string",
"brand_reference": "string"
}
},
"action": {
"id": "ACT_uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",
"type": "string",
"time_created": "2021-05-03T21:23:39.718Z",
"result_code": "SUCCESS",
"app_id": "U1lRHKomEn7DN907RCDPxVhyMfiMLcfy",
"app_name": "demo_app"
}
}Our API supports many other card-present functions you may want to implement. This includes voids, returns, refunds, and adjustments, among others. The most common of these is an adjustment, also known as a tip or gratuity.
Tips are a common way for customers to reward staff for good service in North America and other markets, and are an additional amount added to a transaction either during the sale (prompted on the physical device) or after the sale (signed on a receipt and later adjusted by staff).
Add tips using our Adjust capability.
Add supplemental charges using our Increment capability.
Before implementing batches, check with your account manager for any specific market or platform requirements.
Card-present transactions are managed in batches. Typically, a batch of transactions is an entire business day for a merchant. A batch must be closed for transactions to be settled and funded.
Depending upon your region, our platform may automatically batch your daily transactions for you. In some regions, you may be required to batch your transactions yourself on your application.