Card Present

Introduction

Forward supports in-person card payments, referred to as Card Present (CP) transactions. A CP transaction requires the payer, aka cardholder, to provide a payment instrument at a merchant’s point of sale (POS). The payer will swipe, dip, or tap a card reader terminal to complete a CP transaction. While the manner in which a payer makes a payment may be different, the process partners follow to process payments is consistent across in-person and online payments.

Forward’s Card Present API supports many different types of card terminals, thus ensuring partners are able to integrate once yet support a range of devices that best meet their merchants’ needs.

API

Review the Transaction API for details on all the endpoints and parameters available for Card Present transactions.

Prerequisites

1. Understand the process to Accept Payments
2. Familiarity with API Key Usage
3. Merchant enabled for Card Present payments
4. Supported terminal(s) installed on site and fully enabled

Accepting Card Present Transactions

The Partner POS integration initiates a session and the payment processing workflow begins.

Specifically, the partner application initiates the card present transaction, calls the merchant terminal, gathers card information from the payer and provides the necessary responses. The diagram below provides a high-level overview of this process:

Accepting Card Present Transactions

These are the steps to get your Customers’ accepting Card Present transactions:

• Step 1: Create Card Present Session
• Step 2: Create a Payment Intent
• Step 3: Run the Payment

Step 1: Create Session

Context

A session connects the terminal to the POS system. Forward enables you to create a session by making the following request

How

curl --location 'https://api.getfwd.com/terminals/fiserv/connect' \
--header 'Content-Type: application/json' \
--header 'x-api-key: key_123456789' \
--data { "hsn" : "221985232000", "force": "true" } // Add optional "force" if needed to override an existing session

This returns a session key. This key must be present in all subsequent steps. This session key must be included in each Terminal API request.

A session key is valid for 10 minutes after it is generated. To generate a new session key run the following command:

curl --location 'https://api.getfwd.com/terminals/fiserv/connect' \
--header 'Content-Type: application/json' \
--header 'x-api-key: key_123456789' \
--data {
    "hsn": "221985232000",
    "force": "true" <- Add This
}

Step 2: Create Payment Intent

Context

It is required that a CP transaction create a Payment Intent via the API. To perform this API call, review the documentation on Creating a Payment Intent Using the API.

curl -X POST "https://api.getfwd.com/payment_intents" \
--header 'Content-Type: application/json' \
--header 'x-account-id: acct_12345678' \
--header 'x-api-key: key_123456789' \
--data {
    "amount": 1000
}

Step 3: Run The Payment

Card present authorizations can be manual or card.

How

Card Authorization

curl --location 'https://api.getfwd.com/terminals/fiserv/auth_card' \
--header 'Content-Type: application/json' \
--header 'x-api-key: key_123456789' \
--header 'x-session-key: yudfVqvxUm6kAWloeHcF7RLWwVbGUT545gIiIS0yLSM' \
--data {
    "hsn": "221985232000",
    "payment_intent_id": "pi_2UURIXJ5jxdHJ6ksdM07thFcFvp"
}

Manual Authorization

curl --location 'https://api.getfwd.com/terminals/fiserv/auth_manual' \
--header 'Content-Type: application/json' \
--header 'x-api-key: key_123456789' \
--header 'X-session-key: yudfVqvxUm6kAWloeHcF7RLWwVbGUT545gIiIS0yLSM' \
--data {
    "hsn": "221985232000",
    "payment_intent_id": "pi_2UURIXJ5jxdHJ6ksdM07thFcFvp"
}

Optional: Sync Session and Terminal Time

Context

Your terminal connection is required to ensure the terminal's time for transaction reporting and receipts is accurate. To do this perform, perform a dateTime request:

Making this call also allows the terminal's nightly PCI reboot outside of business hours, as intended.

How

curl --location 'https://api.getfwd.com/terminals/fiserv/date_time' \
--header 'Content-Type: application/json' \
--header 'X-session-key: yudfVqvxUm6kAWloeHcF7RLWwVbGUT545gIiIS0yLSM' \
--header 'x-api-key: key_123456789' \
--data {
    "dateTime": "2021-09-01T12:00:00Z",
    "hsn": "221985232000"
}

Retry Flows

Session Timeout

A session token has a maximum life of ten (10) minutes. When a session expires, it will return an error that you can recover from by creating a new session.

curl --location 'https://api.getfwd.com/terminals/fiserv/connect' \
--header 'Content-Type: application/json' \
--header 'x-api-key: key_123456789' \
--data {
    "hsn": "221985232000",
    "force": "true" <- Add This If Needed To Override an existing session
}

Clover Terminal Activation

Context

When merchants unbox a new Clover terminal device, they are required to enter an activation code during the initial setup. This code is sent in a welcome email, but can also be retrieved via the API to simplify the setup process for merchants.

How

To retrieve the activation code, use the following request:

curl --location 'https://api.getfwd.com/terminals/fiserv/activation_code' \
--header 'Content-Type: application/json' \
--header 'x-api-key: key_123456789' \
--data {
    "hsn": "221985232000"
}

response:

{
    "activation_code": "123456"
}

This activation code should be provided to the merchant to complete the Clover terminal setup.

When a timeout is encountered

The gateway will time out after two minutes and 30 seconds for a transaction to complete.

Card Declined

When a card is declined it is possible to resubmit with another card. Please see this section for how to run a payment.

Card Present API Summary

Session Management

Endpoint	Description
/terminals/fiserv/date_time	Set the terminal's current local time.
/terminals/fiserv/list_terminals	Retrieve a list of terminals associated with a merchant ID.
/terminals/fiserv/terminal_details	Retrieve detailed information about the terminals associated with the provided merchant ID.
/terminals/fiserv/connect	Establish a session between a terminal and Forward.
/terminals/fiserv/ping	Verify a terminal has an open session.
/terminals/fiserv/disconnect	Disconnect the current session
/terminals/fiserv/activation_code	Retrieve the activation code for a Clover terminal.

Card Authorized Payment and Tokenization

Endpoint	Description
/terminals/fiserv/read_card	Generate a token for the session.
/terminals/fiserv/auth_card	Generate a token for the session and run a payment.
/terminals/fiserv/tip	Prompt the user to select a tip amount prior to authorization.

Manual Authorized Payment and Tokenization

Endpoint	Description
/terminals/fiserv/read_manual	Generate a token for the session.
/terminals/fiserv/auth_manual	Generate a token for the session and run a payment.